Skip to content

Latest commit

 

History

History
229 lines (193 loc) · 7.49 KB

README.asciidoc

File metadata and controls

229 lines (193 loc) · 7.49 KB
Raw

Asciidoclet

Table of Contents

Asciidoclet is a Javadoc Doclet based on Asciidoctor that lets you write Javadoc in the AsciiDoc syntax.

Introduction

Traditionally, Javadocs have mixed minor markup with HTML which, if you’re writing for HTML Javadoc output, becomes unreadable and hard to write over time. This is where lightweight markup languages like AsciiDoc thrive. AsciiDoc straddles the line between readable markup and beautifully rendered content.

Asciidoclet incorporates an AsciiDoc renderer (Asciidoctor via the Asciidoctor Java integration library) into a simple Doclet that enables AsciiDoc formatting within Javadoc comments and tags.

Example

Here’s an example of a class with traditional Javadoc.

A Java class with traditional Javadoc
/**
 * <h1>Asciidoclet</h1>
 *
 * <p>Sample comments that include {@code source code}.</p>
 *
 * <pre>{@code
 * public class Asciidoclet extends Doclet {
 *     private final Asciidoctor asciidoctor = Asciidoctor.Factory.create();
 *
 *     {@literal @}SuppressWarnings("UnusedDeclaration")
 *     public static boolean start(RootDoc rootDoc) {
 *         new Asciidoclet().render(rootDoc);
 *         return Standard.start(rootDoc);
 *     }
 * }
 * }</pre>
 *
 * @author <a href="https://github.com/johncarl81">John Ericksen</a>
 */
public class Asciidoclet extends Doclet {
}

This is the same class with Asciidoclet.

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

The result is readable source and beautifully rendered Javadocs, the best of both worlds!

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>
          -include-basedir ${project.basedir}
          -attributes "name=${project.name}; \
                       version=${project.version}; \
                       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:0.+'
}

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

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="-include-basedir" value="${basedir}"/>
    <param name="-attributes"
           value="name=${ant.project.name};
                  version=${version};
                  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

-include-basedir <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.

-attributes "key[=value]; …​"

Sets document attributes that will be expanded when processing javadoc comments. The argument is a string containing a list of attributes in the form of key, key! or key=value. Attributes must be separated by semicolons.

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

-overview <file>

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

Resources and help

For more information:

If you have questions or would like to help develop this project, please join the Asciidoctor discussion list.

License

Copyright 2013 John Ericksen

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

   http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.