DocuOps & Asciidoctor in a JVM World

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

DocuOps: Documentation is an engineering problem.
5 . 1

Go from writing to publication in near-zero effort.
5 . 2

Reduce manual proof reading to absolute minimum that is still sensible.
5 . 3

Reduce the dev-doc distance
5 . 4

Focus on content, not formatting
5 . 5

Write-once, publish multiple formats
5 . 6

Prefer text-based markup
5 . 7

DocuOps is not restricted to technical documents.
5 . 8

DOCSIN JVM WORLD
Binary API (javadoc, groovydoc, scaladoc etc.)
REST API
User documentation
6

ASCIIDOCTOR
Written in Ruby
Runs as AsciidoctorJ via JRuby
Runs as Asciidocto.js via Opal transpilation.
Standard backends: HTML, Docbook5, PDF, EPUB.
8

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

PLUGGABLE SYNTAX HIGHLIGHTERS
Supports CodeRay, Pygments, Highlight.js, Prettify & Rouge
Includes dark pygment styles
highlightjs-languages attribute
9 . 2

CONVERTER API
Easier to register and implement a new backend converter.
Bridging APIs for legacy converters.
Built-in converters can be extended.
9 . 3

NICETIES
Asciidoctorj installed via SDKman.
Asciidoctor cheatsheet via asciidoctor(j) --help
Delegate unregistered backends
9 . 4

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

USING ASCIIDOC FOR MAVEN SITE
Place documents in src/site/asciidoc.
Runs independently from src/main/asciidoc.
10 . 2

Gradle is more than a tool for building Java/Groovy/Kotlin etc.
It is an advanced pipeline automation tool.
11

Asciidoctor plugin for Gradle is (probably) the most advanced integration
between build tooling and documentation production.
12

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

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

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

TIMELINE
10 months work
First commit 28 May 2018
First alpha release July 2018
Released in-time for Greach 2019
15 . 2

CODING
Everything done in Groovy.
Mostly statically compiled.
Spock 1.2 test framework.
TestKit for integration testing.
GradleTest for compatibility testing.
15 . 3

2.X: IMPROVEDGLOBAL CONFIGURATION
asciidoctorj {
version = '1.6.2'
groovyDslVersion = '1.6.0'
pdfVersion = '1.5.0-alpha.16'
epubVersion = '1.5.0-alpha.8.1'
diagramVersion = '1.5.12'
options doctype: 'book', ruby: 'erubis'
attributes toclevel: 2
}
16 . 1

CUSTOMISE ATTASK LEVEL
// Project extension
asciidoctorj {
attributes toclevel: 2
}
asciidoctor {
// Task extension
asciidoctorj {
attributes toc: right
}
}
16 . 2

FAILING ON WARNINGS
asciidoctorj {
fatalWarnings ~/missing attribute/
fatalWarnings missingIncludes()
}
16 . 3

ASCIIDOCTORJ EXTENSIONS
Inline Groovy String.
Inline Groovy closure
As a Groovy le.
As a subproject.
As an artifact.
16 . 4

INLINE EXTENSION
asciidoctorj {
extensions '''block(name: 'BIG', contexts: [':paragraph']) {
parent, reader, attributes ->
def upperLines = reader.readLines()*.toUpperCase()
.inject('')
{a, b -> "${a}n${b}"}
createBlock(parent, "paragraph",
[upperLines], attributes, [:])
}'''
}
16 . 5

GROOVY EXTENSION
asciidoctorj {
extensions {
block(name: 'BIG', contexts: [':paragraph']) {
parent, reader, attributes ->
def upperLines = reader.readLines()*.toUpperCase()
.inject('')
{a, b -> "${a}n${b}"}
createBlock(parent, "paragraph",
[upperLines], attributes, [:])
}
}
16 . 6

FILE EXTENSION
asciidoctorj {
extensions file('blockMacro.groovy')
}
16 . 7

SUBPROJECTEXTENSION
asciidoctorj {
extensions project(':blockmacro')
}
16 . 8

GROOVY DSL DEPENDENCY
asciidoctorj.extensions automatically adds groovy-dsl
dependency.
To override the version use
asciidoctorj.groovyDslVersion.
16 . 9

ARTIFACTEXTENSION
configurations {
asciidocExt
}
dependencies {
asciidocExt 'group:artifact:1.2.3'
}
asciidoctor {
configurations 'asciidocExt'
}
16 . 10

TASK CONFIGURATION
Learning from the past all Asciidoctor tasks have an extended set of DSL
con guration options.
17 . 1

SOURCES
Sources are always speci ed relative to a source root.
asciidoctor {
sourceDir 'src/docs/asciidoc'
sources {
include 'index.adoc'
}
}
17 . 2

OUTPUT
Specify where outputs will be written to.
asciidoctor {
outputDir "${buildDir}/docs"
}
17 . 3

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

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

CONTROLLING RESOURCE COPY
asciidoctor {
copyAllResources()
copyNoResources()
copyResourcesOnlyIf 'html'
}
17 . 6

INTERMEDIATE WORKING DIRECTORY
Some backends or extensions write working output into source
directory.
Keep source directory pristine.
asciidoctor {
useIntermediateWorkDir()
}
17 . 7

INTERMEDIATE ARTIFACTS
Some extensions create artifacts that might need copying to nal
output
Implies useIntermediateWorkDir.
asciidoctor {
withIntermediateArtifacts {
include 'diag-*.png'
}
}
17 . 8

PARALLEL PROCESSING
Documents can be converted in parallel.
asciidoctor {
parallelMode true
}
17 . 9

ADDING ADDITIONAL DEPENDENCIES
confgurations {
asciidocExtensions
}
dependencies {
asciidocExtensions 'group:my-super-extension:1.2.3'
}
asciidoctor {
configurations 'asciidocExtensions'
}
17 . 10

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

USING ASCIIDOCTOR DIAGRAM
asciidoctor {
asciidoctorj {
diagramVersion = '1.5.16'
}
}
17 . 12

ASCIIDOCTOR TASK
Generic task, use specialised tasks where applicable.
plugins {
id 'org.asciidoctor.jvm.convert' version '3.0.0-alpha.3'
}
asciidoctor {
// ....
}
18 . 1

SETTING OUTPUTOPTIONS
asciidoctor {
outputOptions {
backends 'html', 'docbook'
separateOutputDirs = true
}
}
18 . 2

PDF PLUGIN
plugins {
id 'org.asciidoctor.jvm.pdf' version '3.0.0-alpha.3'
}
asciidoctorPdf {
// ....
}
19 . 1

FONTS
asciidoctorPdf {
fontsDir 'src/fonts'
}
19 . 2

DOWNLOADA THEME
pdfThemes {
github 'fancy', {
organisation 'asciidoctor'
repo 'pdf-themes'
tag 'RELEASE_1_0'
relativePath 'fancy-theme'
}
}
19 . 3

LOCAL THEME
pdfThemes {
local 'myTheme', {
styleDir 'src/styles/my-new-style'
styleName 'myTheme'
}
}
19 . 4

USING A THEME
asciidoctorPdf {
theme 'fancy'
}
19 . 5

EPUB PLUGIN
plugins {
id 'org.asciidoctor.jvm.epub' version '3.0.0-alpha.3'
}
asciidoctorEpub {
// ....
}
20 . 1

OUTPUTFORMATS
KF8 requires kindlegen.
asciidoctorEpub {
eBookFormats KF8, EPUB
}
20 . 2

USING KINDLEGEN
kindlegen {
agreeToTermsOfUse = true
}
20 . 3

REVEAL.JSPLUGIN
plugins {
id 'org.asciidoctor.jvm.revealjs' version '3.0.0-alpha.3'
}
asciidoctorRevealJs {
theme 'beige'
sourceDir 'src/docs/asciidoc'
sources {
include 'index.adoc'
}
revealjsOptions {
controls = true
verticalCenter = true
}
}
21

ADDING GEMS
plugins {
id 'org.asciidoctor.jvm.gems' version '3.0.0-alpha.3'
}
repositories {
maven { url 'http://rubygems-proxy.torquebox.org/releases' }
}
dependencies {
asciidoctorGems 'rubygems:asciidoctor-bibtex:0.3.1'
}
asciidoctorj {
requires 'asciidoctor-bibtex'
}
22

WRITING JAVADOC IN ASCIIDOC
/**
* <h1>Asciidoclet</h1>
*
* <p>Sample comments that include {@code source code}.</p>
*
* <pre>{@code
* public class Asciidoclet extends Doclet {
* private final Asciidoctor asciidoctor = Asciidoctor.Factory
*
* {@literal @}SuppressWarnings("UnusedDeclaration")
* public static boolean start(RootDoc rootDoc) {
* new Asciidoclet().render(rootDoc);
* return Standard.start(rootDoc);
* }
* }
* }</pre>
23 . 1

WRITING JAVADOC WITH ASCIIDOCLET
/**
* = Asciidoclet
*
* Sample comments that include `source code`.
*
* [source,java]
* --
* public class Asciidoclet extends Doclet {
* private final Asciidoctor asciidoctor = Asciidoctor.Factory
*
* @SuppressWarnings("UnusedDeclaration")
* public static boolean start(RootDoc rootDoc) {
* new Asciidoclet().render(rootDoc);
* return Standard.start(rootDoc);
* }
* }
23 . 2

EXAMPLE API DOCS- STORMPOT
Source:
http://chrisvest.github.io/stormpot/site/apidocs/stormpot/Poolable.html
23 . 3

USING ASCIIDOCLETWITH BUILDTOOLING
Maven: maven-javadoc-plugin plugin.
Gradle: asciidoclet artifact.
Ant: Via javadoc task.
23 . 4

JDK SUPPORT
Up to JDK8.
Final changes being made for support JDK11+
23 . 5

STAGES
1. Build API docs (groovydoc).
2. Build user documentation (asciidoctor).
3. Build the CHANGELOG (asciidoctor).
4. Build landing page for multiple versions (asciidoctor).
5. Commit build documentation.
6. Publish.
24 . 2

BUILD& COMMIT
gitlab-ci.yml
publish:
stage: release
image: java:8
script: ./gradlew installDocs publishPlugins gitPublishPush -i <
dependencies:
- jdk8
only:
- release
24 . 4

PUBLISHING DOCSFROM CI
gitlab-ci.yml
pages:
stage: release
script: ls -la
artifacts:
paths:
- public
cache:
paths:
- .gradle/
only:
- pages
24 . 5

ABOUTTHIS…
Written in Asciidoc
Styled by Reveal.js
Orchestrated by Gradle
Backend is asciidoctor-revealjs plugin
25

CONTRIBUTING
Languages
Ruby, Java, Groovy, JavaScript
CI
Travis, GitLab Pipelines
Project
How to start
Fix docs, bugs. Add features.
https://github.com/asciidoctor
26

QUESTIONS?
Schalk W. Cronjé
@ysb33r
ysb33r@gmail.com
27

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

DocuOps & Asciidoctor in a JVM World

More Related Content

What's hot (20)

Similar to DocuOps & Asciidoctor in a JVM World (12)

More from Schalk Cronjé (20)

Recently uploaded (20)

DocuOps & Asciidoctor in a JVM World