Asciidoctor | A fast, open source text processor and publishing toolchain for converting AsciiDoc content to HTML5, DocBook, PDF, and other formats.

Following on from the releases of Asciidoctor 1.5.0 and AsciidoctorJ 1.5.0, version 1.5.0 of Asciidoclet has been released with several significant new features, including a new look & feel!

What is Asciidoclet?

Asciidoclet allows Java developers to write Javadoc comments in the portable and rich AsciiDoc syntax instead of HTML.

In short, why write messy Javadoc like this?

/**
 * This class has the following features:
 * <ul>
 *   <li>Support for <strong>foo</strong></li>
 *   <li>Support for bar</li>
 * </ul>
 */
public class Thing implements Something { ... }

…when you can write tidy Javadoc like this!

/**
 * This class has the following features:
 *
 * - Support for *foo*
 * - Support for bar
 */
public class Thing implements Something { ... }

Much better! Now comments in the source code are much easier to read and write and can be reused outside of Javadoc. Best of all, the HTML generated from Javadoc still looks great (perhaps even better).

Of course, this example just scratches the surface of what’s possible. Tables, lists, code examples with syntax highlighting, links, includes and all of Asciidoctor’s capabilities are available via the lightweight AsciiDoc syntax.

Now, developers can focus on content rather than formatting, and still achieve a beautiful end result.

Artifact information

Artifact information (jCenter @ Bintray)
Group Id	Artifact Id	Version	Download
org.asciidoctor	asciidoclet	1.5.0	pom jar javadoc (jar) sources (jar)

Artifact information (Maven Central)
Group Id	Artifact Id	Version	Download
org.asciidoctor	asciidoclet	1.5.0	pom jar javadoc (jar) sources (jar)

Installing

In Maven, just add the Asciidoclet doclet name and artifact to the maven-javadoc-plugin declaration:

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-javadoc-plugin</artifactId>
  <version>2.9</version>
  <executions>
    <execution>
      <goals>
        <goal>jar</goal>
      </goals>
    </execution>
  </executions>
  <configuration>
    <doclet>org.asciidoctor.Asciidoclet</doclet>
    <docletArtifact>
      <groupId>org.asciidoctor</groupId>
      <artifactId>asciidoclet</artifactId>
      <version>1.5.0</version>
    </docletArtifact>
  </configuration>
</plugin>

See the Asciidoclet guide for examples that apply to other build systems and all the available doclet options.

Release highlights

Built on Asciidoctor 1.5.0

Asciidoclet inherits all of the improvements from Asciidoctor 1.5.0 and AsciidoctorJ 1.5.0.

Asciidoctor 1.5.0 introduced some syntax changes. Please refer to the migration guide for details about how to migrate your content.

Improved stylesheets

Asciidoclet includes a default stylesheet with styles from Asciidoctor 1.5.0. This means that AsciiDoc content in the Javadoc is rendered with a similar look and feel to Asciidoctor in other environments.

Figure 1. Example Javadoc using the Java 8-derived stylesheet

Javadoc’s HTML output varies between releases of the Java platform, so Asciidoclet selects an appropriate stylesheet based on the Java version it is running under:

For Java 7 & 8, a stylesheet based on the default Java 8 Javadoc stylesheet is used.
For Java 5 & 6, the stylesheet is based on the Java 6 Javadoc stylesheet.

If you want to use your own stylesheet, you can still do this by using Javadoc’s -stylesheetfile option.

AsciiDoc overview files

Javadoc’s -overview option lets you specify an HTML file that will be used as the overview or index page in the generated documentation. This is especially useful for larger projects, where the overview can provide users with a useful introduction and help them to navigate the API.

Asciidoclet now supports overview files written in AsciiDoc as well, with full support for AsciiDoc features such as includes and document attributes. Overview files named *.adoc, *.ad, *.asciidoc or *.txt are processed by Asciidoclet. Other files are assumed to be HTML, and will be processed by Javadoc’s standard doclet.

Document attributes

Asciidoclet now fully supports Asciidoctor’s document attributes. These are one of Asciidoctor’s most powerful features. Document attributes are parameters that can be passed to Asciidoctor to affect how the final output is generated.

Attributes are specified using one or more -a (or --attribute) options when running Asciidoclet. The --attributes-file option reads attributes from an AsciiDoc file. The attributes are passed to Asciidoctor when it renders Javadoc comments.

Here are some examples of how document attributes might be useful in your Javadoc.

Variable substitution

Attribute references in Javadoc comments or overview files are replaced with attribute values:

/**
 * {product-name} will change your life!
 * @version {version}
 */

When the doclet is run with -a product-name=Foo -a version=1.0, Asciidoctor replaces all {product-name} and {version} attribute references with the given values in the generated HTML output. This makes it very simple to inject values into the Javadoc, without changing the source.

Conditional inclusion

AsciiDoc’s conditional directives can selectively include content based on the presence or absence of attributes. This is useful when the same AsciiDoc source is used in different environments.

For example, if you wanted to reuse the same AsciiDoc content in your Javadoc overview page and your web site, but with some differences, you can use attributes to tell Asciidoctor when certain content should be included:

= Documentation for the Foo project

ifdef::javadoc[]
// content that should only appear in Javadoc
endif::javadoc[]

ifdef::my-website[]
// content that should only appear on the web site
endif::my-website[]

Asciidoclet automatically sets the javadoc attribute when it runs, so Javadoc-only content can easily be selected. You can of course define your own attributes as well.

Java and Ruby extension support

Asciidoctor can be extended using Java or Ruby libraries, and Asciidoclet inherits this capability as well.

Java extensions are loaded automatically when they are made available in the classpath, using AsciidoctorJ’s Extension SPI.
Ruby libraries (Gems) are loaded using the -r (or --require) option.

When using the --require option, we recommend specifying the --gem-path option as well to explicitly set the location of installed gems. Doing so ensures that your build remains portable and reproducible. You can use the gem-maven-plugin to install gems directly into your build directory.

Many extensions are available, but one that is probably most useful for Javadoc authors is Asciidoctor Diagram. Let’s see how it can be used with Asciidoclet.

Embedding diagrams in Javadoc

Asciidoctor Diagram is a popular Asciidoctor extension that lets you embed plain text diagram descriptions in your AsciiDoc source, which get rendered to images when Asciidoctor runs. This can be extremely valuable in Javadoc for describing the architecture or behavior implemeted by the software.

Here’s an example of a Javadoc comment containing a PlantUML sequence diagram:

/**
 * This class implements the following protocol:
 *
 * [plantuml]
 * ....
 * Alice -> Bob: Authentication Request
 * Bob --> Alice: Authentication Response
 *
 * Alice -> Bob: Another authentication Request
 * Alice <-- Bob: another authentication Response
 * ....
 */
public class AuthServer { ... }

Here’s how the diagram above appears in the Javadoc output:

Figure 2. Example output using Asciidoctor Diagram

Not bad! Developers can easily view and update diagrams in plain text, and users reading the Javadoc will see nicely rendered images.

Many other types of diagrams are supported, including Graphviz, blockdiag and ditaa. See the documentation for Asciidoctor Diagram for more examples.

To enable Asciidoctor Diagram support in Asciidoclet:

Install the Asciidoctor Diagram gem, asciidoctor-diagram:
```
$ gem install asciidoctor-diagram
```

Run Asciidoclet with the following doclet options:

--require asciidoctor-diagram
--gem-path ${env.GEM_PATH} (1)
--attribute data-uri (2)

1	The `--gem-path ${env.GEM_PATH}` option tells Asciidoctor’s JRuby runtime where to find gems when using `--require` (effectively setting the `$GEM_PATH` environment variable internally).
2	The `data-uri` attribute is required so that the image data is embedded inside the generated HTML files.^[1]

Admire the beautiful diagrams adorning your Javadoc!

Thanks!

We hope this new version makes your Javadocs even better. We appreciate everyone who has contributed to Asciidoclet. If you have ideas about how to improve on it, ideas and pull requests are always welcome via the repository on GitHub.

1. Without the data-uri attribute, Asciidoctor Diagram writes image files to a location that doesn’t line up with the generated HTML. This problem is being addressed in Asciidoctor Diagram at the time of writing. Refer to issue #39 for details.

We’re excited to announce the newest member of the Asciidoctor family, Asciidoclet. Asciidoclet is a Javadoc Doclet based on Asciidoctor that enables developers to write Javadoc comments using the AsciiDoc syntax.

Motivation

From the very beginning, a concept the designers of Java got right was to include documentation with source code. This allowed documentation to stay closer in sync with ever-changing source and allowed multiple viewing platforms, most notably the HTML generation and IDE integration.

The main drawback of Javadoc has been the requirement to use embedded HTML fragments to achieve advanced (or even modest) formatting. This is where the AsciiDoc integration shines. Being a lightweight markup language, AsciiDoc gives developers access to advanced formatting without having to fiddle with low-level HTML markup. In other words, developers can focus on the content rather than the markup and still achieve a beautiful end result.

Pairing AsciiDoc with Javadocs means readable source and beautifully rendered Javadocs, the best of both worlds!

Usage

Once Asciidoclet is plugged into Javadoc, it’s just a matter of using AsciiDoc mark up in Javadocs. The following example demonstrates a number of features of Asciidoclet:

/**
 * = Asciidoclet (1)
 *
 * Sample comments that include +source code+. (2)
 *
 * [source,java] (3)
 * --
 * public class Asciidoclet extends Doclet {
 *     private final Asciidoctor asciidoctor = Asciidoctor.Factory.create();
 *
 *     @SuppressWarnings("UnusedDeclaration") (4)
 *     public static boolean start(RootDoc rootDoc) {
 *         new Asciidoclet().render(rootDoc);
 *         return Standard.start(rootDoc);
 *     }
 * }
 * --
 *
 * @author https://github.com/johncarl81[John Ericksen] (5)
 */
public class Asciidoclet extends Doclet {
}

1	Titles are easy to create using the `=` markup.
2	Paragraphs are the default and do not require the `<p>` html tag. Inline source may be marked up by surrounding the text in `+` symbols.
3	Source is easily marked up using the `[source,language]` tag and block delimiters, `--`, also called "fences"
4	The notorious `@` symbol is automatically handled by Asciidoclet, avoiding the standard `{@literal @}` boilerplate.
5	Inline AsciiDoc markup is available within Javadoc tags. This example highlights link rendering.

Distribution

Asciidoclet is published to Maven Central. The artifact information is summarized in the table below.

Artifact information for Asciidoclet
Group Id	Artifact Id	Version	Download
org.asciidoctor	asciidoclet	0.1.3*	pom jar javadoc (jar) source (jar)

* This release is based on the Asciidoctor 0.1.3 release.

Installation

Asciidoclet is a standard Javadoc Doclet and may be used as such. One of the easiest ways to install Asciidoclet is by adding it as a Doclet to the maven-javadoc-plugin:

Maven Doclet declaration

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-javadoc-plugin</artifactId>
    <version>2.9</version>
    <executions>
        <execution>
            <id>attach-javadocs</id>
            <goals>
                <goal>jar</goal>
            </goals>
        </execution>
    </executions>
    <configuration>
        <doclet>org.asciidoctor.Asciidoclet</doclet>
        <docletArtifact>
           <groupId>org.asciidoctor</groupId>
           <artifactId>asciidoclet</artifactId>
           <version>${asciidoclet.version}</version>
        </docletArtifact>
    </configuration>
</plugin>

We hope that this extension helps you push your Javadocs to new heights. As always, collaboration is welcome and you may find (and fork) the source on GitHub.

A big thanks to Alex Soto of the Asciidoctor Java integration project, Jason Porter and Dan Allen for their feedback and support and everyone else who contributes to the Asciidoctor project. Writing this extension could not have been easier because of the great work and collaboration of the Asciidoctor community.

Asciidoclet 1.5.0 released!

by John Ericksen and Ben Evans - Tuesday, September 9, 2014