javasphinx is a Sphinx extension that provides a Sphinx domain for documenting
Java projects and a javasphinx-apidoc command line tool for automatically
generating API documentation from existing Java source code and Javadoc
documentation.

To enable javasphinx for your existing Sphinx configuration add 'javasphinx'
to the list of extensions in your conf.py file. javasphinx can be configured to
cross link to external sources of documentation using the javadoc_url_map
option,

Each key in the map should be a Java package. Each value is a tuple of the form
(base_url,doc_type) where base_url is the base URL of the documentation
source, and doc_type is one of,

javadoc

For documentation generated by the Javadoc tool before version 8.

javadoc8

For documentation generated by the Javadoc tool after version 8. This is
required due to changes in how method anchors are generated (see JDK-8144118).

sphinx

For external documentation generated by javasphinx.

When comparing referenced types to the list of available packages the longest
match will be used. Entries for java, javax, org.xml, and
org.w3c packages pointing to http://docs.oracle.com/javase/8/docs/api are
included automatically and do not need to be defined explicitly.

Declare the given type as being provided by the given package. This
information helps javasphinx create cross references for types in type,
method, and field declarations. It also allows explicit cross references
(using the java:ref role) to exclude the package qualification.

The method, construct, field, and type directives all accept the following
standard options,

package

Specify the package the declaration is within. Can be used instead of, or to
override, a java:package directive.

outertype

Specify the class/interface the documented object is contained within. This
option should be provided for any constructor, method, or field directive
that isn’t nested within a corresponding type directive.

The javasphinx-apidoc tool is the counterpoint to the sphinx-apidoc tool
within the Java domain. It can be used to generate reST source from existing
Java source code which has been marked up with Javadoc-style comments. The
generated reST is then processed alongside hand-written documentation by Sphinx.

At minimum a source and destination directory must be provided. The input
directory will be scanned for .java files and documentation will be generated
for all non-private types and members. A separate output file will be generated
for each type (including inner classes). Each file is put within a directory
corresponding to its package (with periods replaced by directory separators) and
with the basename of the file deriving from the type name. Inner types are
placed in files with a basename using a hyphen to separate inner and outer
types, e.g. OuterType-InnerType.rst.

By default javasphinx-apidoc will not override existing files. Two options
can change this behavior,