How is managed vert.x documentation - vert-x3/wiki GitHub Wiki

This page presents how is managed the vert.x documentation.

Documentation source

The documentation is written in a package-info.java file as follows:

/**
 * = Your documentation
 *
 */
@Document(fileName = "index.adoc")
@ModuleGen(name = "vertx-module-name", groupPackage = "io.vertx.ext.module")
package io.vertx.core;

import io.vertx.docgen.Document;

The documentation is written in a Javadoc block in the package-info.java. The package declaration is annotated with @ModuleGen and Document. The Javadoc block is written using the asciidoc syntax.

Processing

In the pom.xml file, you need to have this dependency.

<dependency>
  <groupId>io.vertx</groupId>
  <artifactId>vertx-docgen</artifactId>
  <optional>true</optional>
</dependency>

The maven-compiler-plugin must be configured using:

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-compiler-plugin</artifactId>
  <executions>
    <execution>
      <id>default-compile</id>
      <configuration>
        <annotationProcessors>
          <annotationProcessor>io.vertx.docgen.JavaDocGenProcessor</annotationProcessor>
          <annotationProcessor>io.vertx.codegen.CodeGenProcessor</annotationProcessor>
        </annotationProcessors>
        <compilerArgs>
          <!-- output directory -->
          <arg>-Adocgen.output=src/main/asciidoc/$lang</arg>
          <!-- some variables (see below) -->
          <arg>-Amaven.groupId=${project.groupId}</arg>
          <arg>-Amaven.artifactId=${project.artifactId}</arg>
          <arg>-Amaven.version=${project.version}</arg>
        </compilerArgs>
        <generatedSourcesDirectory>${generated.dir}</generatedSourcesDirectory>
      </configuration>
    </execution>
  </executions>
</plugin>

So, at compile time, the asciidoc content is extracted and a .ad file is created in src/main/asciidoc/$lang, where $lang is the language name replaced automatically to Java, JavaScript, Ruby, Groovy...

Variables

As seen before you can define variables in the maven-compiler-plugin configuration. They can be used using the ${name} syntax:

compile '${maven.groupId}:${maven.artifactId}:${maven.version}'

Syntax

Combining asciidoc and javadoc syntaxes has many benefits (links, source code inclusion...). Learn more in the docgen documentation: https://github.com/vert-x3/vertx-docgen.

From the project to the web site

The .ad file is generated from the javadoc contained in the package-info.java
The .ad files are packaged in the -sources artifact of your project
The vertx-stack project downloads the sources artifacts and unpacks them, it assemble all the .ad files in an artifact
The web-site project downloads this artifacts and generate the HTML output than is integrated to the web site.