Skip to content

Documentation

Jump to bottom
Julien Viet edited this page Mar 6, 2015 · 7 revisions
Clone this wiki locally

Vert.x 3 documentation

Vert.x 3 developer documentation

The developer manual and the api documentation (Javadoc, JSDoc, etc…​). The documentation content uses the Asciidoc format.

Toolchain

Vert.x 3 developer documentation combines several tools used in a toolchain to produce the developer manual and the api documentation:

  • Asciidoctor : a text processor transforming Asciidoc content to HTML5, DocBook & more

  • Docgen : a Vert.x 3 project extracting Asciidoc content from Java source files

  • Api docs : tools for creating Api reference documentation from Java source files such as Javadoc, JSDoc, etc…​

Documentation generation

Documentation happens at various steps of the build

Asciidoc generation

The Docgen tool is an annotation processor and so requires to compile the project sources or run the maven-processor-plugin plugin to generate the Asciidoc files from the Java sources. The compilation overhead is very small and therefore is always enabled, allowing to detect errors (like the documentation pointing to a non existing api element) and also preview the documentation (using the Chrome Asciidoctor.js plugin).

This happens during the compilation phase.

The generated Asciidoc are placed in the src/main/asciidoc directory:

  • Java manual is in src/main/asciidoc/java

  • Groovy manual is in src/main/asciidoc/groovy

  • JavaScript manual is in src/main/asciidoc/js

  • Cheatsheets are in src/main/asciidoc/cheatsheet

JavaDoc, JSDoc, GroovyDoc generation

This happens during the package phase of the build.

Documentation preview

The build creates a preview of the doc in the target/docs directory.

Documentation archive

The build creates a -docs.zip archive that contains Asciidoc + JavaDoc + GroovyDoc + JSDoc that is used by the toolchain later to create documentation.

Documentation layout

Preview

We use this directory layout for the preview

  • apidocs : the Java API reference

  • ${artifactId}/cheatsheet : the cheatsheets

  • ${artifactId}/java/*/.adoc : the Java manual

  • ${artifactId}/js/*/.adoc : the JavaScript manual

  • ${artifactId}/groovy/*/.adoc : the Groovy manual

  • ${artifactId}/js/jsdoc/** : the JavaScript API reference

  • ${artifactId}/groovy/groovydoc/** : the Groovy API reference

Archive docs.zip

We use this directory for the $docs.zip archive:

  • cheatsheet : the cheatsheets

  • java/*/.adoc : the Java manual

  • js/*/.adoc : the JavaScript manual

  • groovy/*/.adoc : the Groovy manual

  • js/jsdoc/** : the JavaScript API reference

  • groovy/groovydoc/** : the Groovy API reference

Note
 we don’t bundle JavaDoc because it is re generated later with the entire stack to have a single API reference doc and provide correct links from the Java manual to the JavaDoc.
Website

We use the same layout than for the preview, the apidocs is created from the -sources.jar of the projects. The layout creation is straightforward : it unpacks the -docs.zip in their respective ${artifactId}.

Vertx Extensions

Vertx extension can use the vertx-ext-parent to take care of most of the task to do for building/archiving documentation.

Note
 the intensive processing is done in the package phase, so using the test phase will not trigger it
Tip
 part of documentation generation can be skipped using the -DskipDocs flag to speed up things