org.asciidoctor

Class Asciidoclet

java.lang.Object

com.sun.javadoc.Doclet

org.asciidoctor.Asciidoclet

public class Asciidoclet
extends com.sun.javadoc.Doclet

Asciidoclet

Asciidoclet is a Javadoc Doclet that uses Asciidoctor (via the Asciidoctor Java integration) to interpet AsciiDoc markup within Javadoc comments.

Usage

Run javadoc with the org.asciidoctor.Asciidoclet doclet class. Some examples for common build systems are shown below. See Doclet Options for supported options.

Maven

Asciidoclet may be used via a maven-javadoc-plugin doclet:

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-javadoc-plugin</artifactId>
    <version>2.9</version>
    <configuration>
        <source>1.7</source>
        <doclet>org.asciidoctor.Asciidoclet</doclet>
        <docletArtifact>
            <groupId>org.asciidoctor</groupId>
            <artifactId>asciidoclet</artifactId>
            <version>${asciidoclet.version}</version>
        </docletArtifact>
        <overview>src/main/java/overview.adoc</overview>
        <additionalparam>
          --base-dir ${project.basedir}
          --attribute "name=${project.name}"
          --attribute "version=${project.version}"
          --attribute "title-link=http://example.com[${project.name} ${project.version}]"
        </additionalparam>
    </configuration>
</plugin>

Gradle

Asciidoclet may be used via a doclet in the Javadoc task:

configurations {
    asciidoclet
}

dependencies {
    asciidoclet 'org.asciidoctor:asciidoclet:1.+'
}

javadoc {
    options.docletpath = configurations.asciidoclet.files.asType(List)
    options.doclet = 'org.asciidoctor.Asciidoclet'
    options.overview = "src/main/java/overview.adoc"
    options.addStringOption "-base-dir", "${projectDir}" (1)
    options.addStringOption "-attribute", (2)
            "name=${project.name}," +
            "version=${project.version}," +
            "title-link=http://example.com[${project.name} ${project.version}]")
}

1. Option names passed to Gradle’s javadoc task must omit the leading "-", so here "-base-dir" means "--base-dir". See Doclet Options below.

2. Gradle’s javadoc task does not allow multiple occurrences of the same option. Multiple attributes can be specified in a single string, separated by commas.

Ant

Asciidoclet may be used via a doclet element in Ant’s javadoc task:

<javadoc destdir="target/javadoc"
         sourcepath="src"
         overview="src/overview.adoc">
  <doclet name="org.asciidoctor.Asciidoclet" pathref="asciidoclet.classpath"> (1)
    <param name="--base-dir" value="${basedir}"/>
    <param name="--attribute" value="name=${ant.project.name}"/>
    <param name="--attribute" value="version=${version}"/>
    <param name="--attribute" value="title-link=http://example.com[${ant.project.name} ${version}]"/>
  </doclet>
</javadoc>

1. Assumes a path reference has been defined for Asciidoclet and its dependencies, e.g. using Ivy or similar.

Doclet Options

--base-dir <dir>

Sets the base directory that will be used to resolve relative path names in Asciidoc include:: directives. This should be set to the project’s root directory.

-a, --attribute "name[=value], …"

Sets document attributes that will be expanded in javadoc comments. The argument is a string containing a single attribute, or multiple attributes separated by commas.

This option may be used more than once, for example: -a name=foo -a version=1.

Attributes use the same syntax as Asciidoctor command-line attributes:

• name sets the attribute (with an empty value)

• name=value assigns value to the attribute. Occurrences of {name} in the javadoc will be replaced by this value.

• name=value@ assigns value to the attribute, unless the attribute is defined in the attributes file or javadoc.

• name! unsets the attribute.

The document attribute javadoc is set automatically by the doclet. This can be used for conditionally selecting content when using the same Asciidoc file for javadoc and other documentation.

--attributes-file <file>

Reads document attributes from an Asciidoc file. The attributes will be expanded in javadoc comments.

If <file> is a relative path name, it is assumed to be relative to the --base-dir directory.

Attributes set by the -a/--attribute option take precedence over those in the attributes file.

-r, --require <library>,…

Make the specified RubyGems library available to Asciidoctor’s JRuby runtime, for example -r asciidoctor-diagram.

This option may be specified more than once. Alternatively multiple library names may be specified in a single argument, separated by commas.

--gem-path <path>

Sets the GEM_PATH for Asciidoctor’s JRuby runtime. This option is only needed when using the --require option, and the GEM_PATH environment variable is not set, or a different GEM_PATH is required.

-overview <file>

Overview documentation can be generated from an Asciidoc file using the standard -overview option. Files matching *.adoc, *.ad, *.asciidoc or *.txt are processed by Asciidoclet. Other files are assumed to be HTML and will be processed by the standard doclet.

Examples

Custom attributes

{project_name}

AsciiDoc Javadoc Doclet

{project_desc}

Asciidoclet is a Javadoc Doclet that allows you to write Javadoc using the AsciiDoc format.

{project_version}

1.5.4

Code block (with syntax highlighting added by CodeRay)

/**
 * = Asciidoclet
 *
 * A Javadoc Doclet that uses http://asciidoctor.org[Asciidoctor]
 * to render http://asciidoc.org[AsciiDoc] markup in Javadoc comments.
 *
 * @author https://github.com/johncarl81[John Ericksen]
 */
public class Asciidoclet extends Doclet {
    private final Asciidoctor asciidoctor = Asciidoctor.Factory.create(); (1)

    @SuppressWarnings("UnusedDeclaration")
    public static boolean start(RootDoc rootDoc) {
        new Asciidoclet().render(rootDoc); (2)
        return Standard.start(rootDoc);
    }
}

1. Creates an instance of the Asciidoctor Java integration

2. Runs Javadoc comment strings through Asciidoctor

Inline code

code()

Headings

Heading 1

Heading 2

Heading 3

Heading 4

Heading 5

Links

Doc Writer <doc@example.com>
AsciiDoc is a lightweight markup language.
Learn more about it at http://asciidoctor.org.

Bullets

Unnumbered

• bullet

• bullet

  • bullet

  • bullet

• bullet

  • bullet

  • bullet

    • bullet

    • bullet

      • bullet

      • bullet

        • bullet

        • bullet

      • bullet

    • bullet

  • bullet

• bullet

Numbered

1. bullet

2. bullet

   1. bullet

   2. bullet

3. bullet

   1. bullet

      1. bullet

      2. bullet

         1. bullet

         2. bullet

      3. bullet

      4. bullet

   2. bullet

   3. bullet

4. bullet

Tables

Table 1. An example table

Column 1	Column 2	Column 3
1	Item 1	a
2	Item 2	b
3	Item 3	c

Sidebar block

Optional Title

Usage: Notes in a sidebar, naturally.

Admonitions

Important

Check this out!

Since:

0.1.0

Version:

1.5.4

Author:

John Ericksen

See Also:

Asciidoclet

Constructor Summary

Constructors

Constructor and Description
Asciidoclet(com.sun.javadoc.RootDoc rootDoc)

Method Summary

Modifier and Type	Method and Description
static void	exampleDeprecated(String field) Deprecated. for example purposes
static com.sun.javadoc.LanguageVersion	languageVersion() Sets the language version to Java 5.
static int	optionLength(String option) Sets the option length to the standard Javadoc option length.
static boolean	start(com.sun.javadoc.RootDoc rootDoc) The starting point of Javadoc render.
static boolean	validOptions(String[][] options, com.sun.javadoc.DocErrorReporter errorReporter) Processes the input options by delegating to the standard handler.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Asciidoclet

public Asciidoclet(com.sun.javadoc.RootDoc rootDoc)

Method Detail

exampleDeprecated

public static void exampleDeprecated(String field)
                              throws Exception

Deprecated. for example purposes

Example usage

exampleDeprecated("do not use");

Throws:

Exception - example

RuntimeException - example

languageVersion

public static com.sun.javadoc.LanguageVersion languageVersion()

Sets the language version to Java 5.

Javadoc spec requirement.

Returns:

language version number

optionLength

public static int optionLength(String option)

Sets the option length to the standard Javadoc option length.

Javadoc spec requirement.

Parameters:

option - input option

Returns:

length of required parameters

start

public static boolean start(com.sun.javadoc.RootDoc rootDoc)

The starting point of Javadoc render.

Javadoc spec requirement.

Parameters:

rootDoc - input class documents

Returns:

success

validOptions

public static boolean validOptions(String[][] options,
                                   com.sun.javadoc.DocErrorReporter errorReporter)

Processes the input options by delegating to the standard handler.

Javadoc spec requirement.

Parameters:

options - input option array

errorReporter - error handling

Returns:

success