What is DocuOps. How does Asciidoctor contribute? How to add it to your Maven & Gradle build. Tying all of the tech documentation together in a single project from commit to publish.
Building Real-Time Data Pipelines: Stream & Batch Processing workshop Slide
DocuOps & Asciidoctor in a JVM World
1. DOCUOPS & ASCIIDOCTOR IN A JVMDOCUOPS & ASCIIDOCTOR IN A JVMDOCUOPS & ASCIIDOCTOR IN A JVMDOCUOPS & ASCIIDOCTOR IN A JVMDOCUOPS & ASCIIDOCTOR IN A JVMDOCUOPS & ASCIIDOCTOR IN A JVMDOCUOPS & ASCIIDOCTOR IN A JVMDOCUOPS & ASCIIDOCTOR IN A JVMDOCUOPS & ASCIIDOCTOR IN A JVMDOCUOPS & ASCIIDOCTOR IN A JVMDOCUOPS & ASCIIDOCTOR IN A JVMDOCUOPS & ASCIIDOCTOR IN A JVM
WORLDWORLDWORLDWORLDWORLDWORLDWORLDWORLDWORLDWORLDWORLDWORLD
Schalk W. Cronjé
@ysb33r
ysb33r@gmail.com
1
15. ASCIIDOCTOR
Written in Ruby
Runs as AsciidoctorJ via JRuby
Runs as Asciidocto.js via Opal transpilation.
Standard backends: HTML, Docbook5, PDF, EPUB.
8
16. ASCIIDOCTORJ 2.1.0RELEASED
Fully separate API from implementation engine.
Default JRuby engine is Ruby Asciidoctor 2.0
Binary incompatible with AsciidoctorJ 1.6.x
Extensions will need to be recompiled.
9 . 1
17. PLUGGABLE SYNTAX HIGHLIGHTERS
Supports CodeRay, Pygments, Highlight.js, Prettify & Rouge
Includes dark pygment styles
highlightjs-languages attribute
9 . 2
18. CONVERTER API
Easier to register and implement a new backend converter.
Bridging APIs for legacy converters.
Built-in converters can be extended.
9 . 3
20. USING ASCIIDOCTOR WITH MAVEN
pom.xml
Sources go in ${basedir}/src/main/asciidoc. Output goes to
${project.build.directory}/generated-docs.
<plugins>
<plugin>
<groupId>org.asciidoctor</groupId>
<artifactId>asciidoctor-maven-plugin</artifactId>
<version>1.5.8</version>
...
</plugin>
</plugins>
10 . 1
21. USING ASCIIDOC FOR MAVEN SITE
Place documents in src/site/asciidoc.
Runs independently from src/main/asciidoc.
10 . 2
22. Gradle is more than a tool for building Java/Groovy/Kotlin etc.
It is an advanced pipeline automation tool.
11
23. Asciidoctor plugin for Gradle is (probably) the most advanced integration
between build tooling and documentation production.
12
24. STATE OF ASCIIDOCTOR GRADLE PLUGINS
v1.5.x & v1.6.x in maintenance
v2.1.0 released
v2.2.0 in progress
v3.0.0 in development
13
25. LEGACY: 1.5.X / 1.6.X
Latest releases 1.5.12 & 1.6.1.
Now uses external Java process to build.
Urgent maintenance xes only.
Not guaranteed to work with Gradle 5.0+
Uses AsciidoctorJ 1.5.x/1.6.x as engine
14
26. 2.0.0
Complete redesign.
Some backwards compatibility.
Requires Gradle 4.0+.
Groovy DSL & Kotlin DSL.
7 subprojects & 10 plugins.
(1.5.x: 1 project & 2 plugins).
Will probably support Asciidoctor.js in future.
15 . 1
27. TIMELINE
10 months work
First commit 28 May 2018
First alpha release July 2018
Released in-time for Greach 2019
15 . 2
28. CODING
Everything done in Groovy.
Mostly statically compiled.
Spock 1.2 test framework.
TestKit for integration testing.
GradleTest for compatibility testing.
15 . 3
40. SOURCES
Sources are always speci ed relative to a source root.
asciidoctor {
sourceDir 'src/docs/asciidoc'
sources {
include 'index.adoc'
}
}
17 . 2
42. SECONDARY SOURCES
Non-asciidoc les that are used by backends.
Changes to them Gradle up-of-date status.
Relative to source root.
Some backends add default patterns.
asciidoctor {
secondarySources {
include '**/docinfo*.xml'
}
}
17 . 4
43. RESOURCES
File that might be processed by backends, and will probably be
required in the nal output.
Changes to them affect Gradle up-to-date status.
asciidoctor {
resources {
from 'src/images', {
include '**/*.png'
}
}
}
17 . 5
45. INTERMEDIATE WORKING DIRECTORY
Some backends or extensions write working output into source
directory.
Keep source directory pristine.
asciidoctor {
useIntermediateWorkDir()
}
17 . 7
46. INTERMEDIATE ARTIFACTS
Some extensions create artifacts that might need copying to nal
output
Implies useIntermediateWorkDir.
asciidoctor {
withIntermediateArtifacts {
include 'diag-*.png'
}
}
17 . 8
49. FINE-TUNING FORKS
Works with processMode of OUT_OF_PROCESS and JAVA_EXEC
Similar to JavaForkOptions used elsewhere in Gradle.
asciidoctor {
forkOptions {
minHeapSize = '512m'
}
}
17 . 11
76. PROCESSMODESIN GRADLE
IN_PROCESS: Gradle worker.
OUT_OF_PROCESS: Gradle worker in separate Java process.
JAVA_EXEC: Separate Java process using javaexec.
Controlled on a per-task basis.
Default is JAVA_EXEC
28