asciidoctor-extension-apidoc

Easily link to Javadoc from an Asciidoc user guide !

This extension is an inline macro based on the idea of Ruby ImplicitApidocInlineMacro extension from the asciidoctor-extensions-lab.

It is written in Java using JRuby and AsciidoctorJ 2.x bindings, with the assumption that referencing Javadoc links in a documentation likely means Java is already present in the build toolchain.

It is compatible with any Asciidoctor backend (html5, pdf, ...)

References

• AsciidoctorJ extension API
• Javadoc technology
• Naming a package
• Identifiers in Java

Building the project

Pre-requisites are Maven 3+ and JDK8+:

mvn install

Willing to contribute ? Check this guide !

Usage

Here is how to use the extension:

Implicit macro

The idea is to write full-qualified Java class or package names in the document, and let the extension generate the actual links.

Rather than:

See link:{jse-apidocs}/java/net/HttpURLConnection.html[`HTTPUrlConnection`] for more info.

It allows:

See `java.net.HttpURLConnection` for more info.

The benefits are:

• The improved readability of the .adoc files
• The Javadoc-linking is systematic and consistent
• There is a single place to version and update Javadoc base URLs.

In addition the document remains semantically correct without the extension. When rendering Asciidoc on github without document attributes, it's better than a broken link for readability.

The extension does its best to avoid false-positives. But if required, the macro can be bypassed using pass macro:

pass:[com.company.some_property_that_looks_like_a_package]

Explicit macro

The macro may also be called explicitly:

apidoc:java.util.List[]

asciidoctor-maven-plugin

Simply add the extension as a dependency of asciidoctor-maven-plugin:

<plugin>
  <groupId>org.asciidoctor</groupId>
  <artifactId>asciidoctor-maven-plugin</artifactId>
  <dependencies>
    <dependency>
      <groupId>com.amadeus.asciidoc</groupId>
      <artifactId>asciidoctor-extension-apidoc</artifactId>
    </dependency>
  </dependencies>
</plugin>

The extension registers itself via its /META-INF/services/org.asciidoctor.extension.spi.ExtensionRegistry

Attribute apidocs_config

To configure the extension, add a document attribute apidocs_config linking to a .properties file:

<plugin>
  <groupId>org.asciidoctor</groupId>
  <artifactId>asciidoctor-maven-plugin</artifactId>
  <configuration>
    <attributes>
      <apidocs_config>apidoc.properties</apidocs_config>
    </attributes>
  </configuration>
</plugin>

The file should contain keys with fully-qualified packages, and values with the corresponding Javadoc base URL (the path parent of index.html, including the trailing slash):

java=https://docs.oracle.com/javase/10/docs/api/
javax=https://javaee.github.io/javaee-spec/javadocs/
org.springframework.boot=https://docs.spring.io/spring-boot/docs/2.0.2.RELEASE/api/
org.springframework.batch=https://docs.spring.io/spring-batch/3.0.x/apidocs/
org.springframework=https://docs.spring.io/spring/docs/5.0.7.BUILD-SNAPSHOT/javadoc-api/

The most precise key will be used, if any. Otherwise the element processing will be skipped, a warning will be logged and the rendering won't be altered.

Relative links are allowed, if the documentation is hosted next to some javadoc. This will only work with an HTML backend though.

Note: the configuration cannot be done "inline" in pom.xml, as ascidoctorj attributes don't allow nested XML tags.

Class-level Javadoc

The class needs to be fully-qualified.

java.lang.String

is processed as:

link:https://docs.oracle.com/javase/8/docs/api/java/lang/String.html[`String`]

Nested classes:

java.util.Map.Entry

is processed as:

link:https://docs.oracle.com/javase/8/docs/api/java/util/Map.Entry.html[`Map.Entry`]

Annotation classes support an optional '@' prefix:

@javax.inject.Inject

is processed as:

link:https://docs.oracle.com/javaee/7/api/javax/inject/Inject.html[`@Inject`].

Package-level Javadoc

Requires at least one sub-package (obviously). To avoid false positives, it requires an explict macro call. The warning regarding unknown configured package is skipped when only 1 sub-package, as it triggers false positives with "filename.extension" texts.

apidoc:java.util.logging[]

is processed as:

link:https://docs.oracle.com/javase/8/docs/api/java/util/logging/package-summary.html[`java.util.logging`]

Relative URLs

It can be convenient to use relative URLs when referencing some Javadoc from the project itself, when it is hosted at the same place as the userguide.

For instance:

https://my.company.com/docs/v1.0.0/userguide.html
https://my.company.com/docs/v1.0.0/apidocs/index.html

com.company.my=apidocs/

But when using other Asciidoctor backends like pdf, those relative links will be broken.

To solve this, the attribute apidocs_baseurl configures the base URL to use for relative Javadoc URLs:

<plugin>
  <groupId>org.asciidoctor</groupId>
  <artifactId>asciidoctor-maven-plugin</artifactId>
  <configuration>
    <attributes>
      <apidocs_config>apidoc.properties</apidocs_config>
    </attributes>
  </configuration>
  <executions>
     <execution>
        <id>backend-html</id>
        <configuration>
            <backend>html5</backend>
            <!-- Keep relative links, as HTML userguide will be hosted alongside the Javadoc -->
        </configuration>
     </execution>
     <execution>
        <id>backend-pdf</id>
        <configuration>
            <backend>pdf</backend>
            <attributes>
              <!-- Transform relative links into absolute URLs -->
              <apidocs_baseurl>https://my.company.com/</apidocs_baseurl>
            </attributes>        
        </configuration>
     </execution>
  </executions>
</plugin>