<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-javadoc-plugin</artifactId>
<version>3.6.3</version>
<configuration>
<source>11</source>
<additionalJOptions>
<additionalJOption>-J--add-exports=jdk.javadoc/jdk.javadoc.internal.tool=ALL-UNNAMED</additionalJOption> // (1)
<additionalJOption>-Xdoclint:all,-html,-accessibility</additionalJOption> // (2)
</additionalJOptions>
<doclet>org.asciidoctor.asciidoclet.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=https://example.com[${project.name} ${project.version}]"
</additionalparam>
</configuration>
</plugin>
- All Implemented Interfaces:
Doclet
Asciidoclet
that uses Asciidoctor (via the Asciidoctor Java integration) to interpret AsciiDoc markup within Javadoc comments. <p> == Usage
Run Javadoc with the org.asciidoctor.asciidoctlet.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:
-
For the asciidoclet to work, it needs access to the internals of the
javadoc
tool. This incantation makes that access possible on moduler JDKs. -
Asciidoctor may generate HTML that produces doclint errors, which can cause the build to fail. To work around that, we have to disable these doclint categories.
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.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=https://example.com[${project.name} ${project.version}]")
}
-
Option names passed to Gradle’s
javadoc
task must omit the leading "-", so here "-base-dir" means "--base-dir". See Doclet Options below. -
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.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=https://example.com[${ant.project.name} ${version}]"/>
</doclet>
</javadoc>
-
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
assignsvalue
to the attribute. Occurrences of{name}
in the Javadoc will be replaced by this value. -
name=value@
assignsvalue
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 to load additional gems on theGEM_PATH
. - -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. - --asciidoclet-include <filter>
- --asciidoclet-exclude <filter>
-
Explicitly include or exclude classes from being processed as Asciidoc comments by ant-style path matching (see ant-style-path-matcher).
If
--asciidoclet-include
is specified, only classes and packages matching the include filter are processed. Likewise, if--include
is unspecified, all classes are processed. If--asciidoclet-exclude
is specified, classes matching the filter are not processed.Both
--asciidoclet-include
and--asciidoclet-exclude
can be mixed. In addition, classes excluded with--asciidoclet-exclude
or not matching a specified--asciidoclet-include
may be included by annotating the class level javadoc with@asciidoclet
. Doing so allows writing one class at a time while respecting refactors. This feature allows the migration of documentation from HTML to Asciidoc in a piecemeal way.
<p>
== Examples
<p>
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}
;; 2.0.0-SNAPSHOT
<p>
Code block (with syntax highlighting added by CodeRay)::
+
/**
* = Asciidoclet
*
* A Javadoc Doclet that uses https://asciidoctor.org[Asciidoctor]
* to render https://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)
@author https://github.com/johncarl81[John Ericksen]
@version {project_version}
@SuppressWarnings("UnusedDeclaration") public static boolean start(RootDoc rootDoc) {
new Asciidoclet().render(rootDoc); // (2)
return Standard.start(rootDoc);
}
}
-
Creates an instance of the Asciidoctor Java integration
-
Runs Javadoc comment strings through Asciidoctor <p>
- Inline code
-
code()
<p> - Headings
-
Heading 1
<p>
Heading 2
<p>
Heading 3
<p>
Heading 4
<p>
Heading 5
<p>
- Links
-
Doc Writer <doc@example.com>
AsciiDoc is a lightweight markup language.
Learn more about it at https://asciidoctor.org.
<p> - Bullets
-
Unnumbered
-
bullet
-
bullet
-
bullet
-
bullet
-
-
bullet
-
bullet
-
bullet
-
bullet
-
bullet
-
bullet
-
bullet
-
bullet
-
bullet
-
-
bullet
-
-
bullet
-
-
bullet
-
-
bullet
Numbered-
bullet
-
bullet
-
bullet
-
bullet
-
-
bullet
-
bullet
-
bullet
-
bullet
-
bullet
-
bullet
-
-
bullet
-
bullet
-
-
bullet
-
bullet
-
-
bullet
<p>
-
- Tables
-
Table 1. An example table Column 1
Column 2
Column 3 <p>
1
Item 1
a <p>
2
Item 2
b <p>
3
Item 3
c
<p>
- Sidebar block
-
<p>
- Admonitions
-
Important
Check this out!
- Since:
- 0.1.0
- See Also:
-
Nested Class Summary
Nested classes/interfaces inherited from interface jdk.javadoc.doclet.Doclet
Doclet.Option
-
Constructor Summary
-
Method Summary
Modifier and TypeMethodDescriptiongetName()
Set
<? extends Doclet.Option> void
boolean
run
(DocletEnvironment environment)
-
Constructor Details
-
Asciidoclet
public Asciidoclet()Creates a new
Asciidoclet
object.
-
-
Method Details
-
init
-
getName
-
getSupportedOptions
- Specified by:
getSupportedOptions
in interfaceDoclet
-
getSupportedSourceVersion
- Specified by:
getSupportedSourceVersion
in interfaceDoclet
-
run
-