Configuration reference

Settings, directive options and link syntax. For a first build, start with Generate your API pages.

Sphinx configuration

Set these in conf.py. Paths are relative to conf.py, except java_generate, which is relative to the Sphinx source directory.

Setting	Default	Purpose
java_sources	[]	Java files or source roots; directories are scanned recursively.
java_sourcepath	[]	Source directories used only for lookup and inherited comments; no pages.
java_classpath	[]	Dependency JARs or class directories. No wildcards.
java_encoding	"UTF-8"	Source file encoding, as Javadoc’s -encoding accepts it.
java_exclude_packages	[]	Packages, with their subpackages, left out of the pages like Javadoc’s -exclude. They still compile; an entry matching no package warns.
java_jdk	""	JDK 25 home; empty uses the runtime on PATH.
java_release	""	Source/API release; empty uses the JDK default. Tested: 17, 21, 25.
java_generate	""	Directory for generated pages, such as "api". Empty generates no pages.
java_visibility	"protected"	"public", or "protected" for public plus protected declarations.
java_model	""	Pre-extracted XML model; excludes java_sources.
java_external_javadoc	{}	Package prefixes mapped to external Javadoc roots; see below.
java_maximum_signature_line_length	None	Signatures longer than this put each parameter on its own line. Unset uses Sphinx’s maximum_signature_line_length.

Empty or missing source roots and missing classpath entries are errors. A site that only links to another site’s Java API through intersphinx leaves java_sources and java_model unset and needs no JDK.

Directives

.. java:autoclass:: com.example.Widget
   :members: find(java.lang.String,int); LABEL
   :exclude-members: old
   :visibility: public
   :no-index:

• Without :members:, only the type’s declaration and description appear. An empty :members: includes all declared members.

• Separate selected members with semicolons, because signatures contain commas. A bare name selects every overload; a signature selects one.

• :no-index: renders an excerpt without registering anchors or inventory entries. Use it when the object also has a generated page.

• Unknown members and duplicate documentation warn.

Other directives work the same way:

.. java:automethod:: com.example.Widget#find(java.lang.String,int)
.. java:autofield:: com.example.Widget#LABEL
.. java:autopackage:: com.example

.. java:autosummary::

   com.example
   com.example.Widget
   com.example.Widget#find(java.lang.String,int)

java:autopackage renders the package-info.java comment. java:autosummary lists each entry with a link and its first sentence; unknown entries warn as java.summary. As in Javadoc, members are listed with their declared parameters, and methods and fields get a column with their modifiers and type, such as static <L, R> Pair<L, R>. Generated pages consist of these directives.

What gets documented

• Private and package-private declarations are never shown, and @hidden declarations are omitted. public visibility also omits public types nested in protected types.

• Only declared members are listed. An overriding method inherits its ancestor’s comment; other inherited methods stay on the declaring type’s page.

• As in Javadoc, an overriding method notes what it implements or overrides: “Specified by: convert in interface Transformer”, or “Overrides: hashCode in class Object”.

• Nested types get their own pages.

• Signatures show only @Documented annotations, as the standard doclet does, so @Override and @SuppressWarnings are left out.

Roles

:java:type:`com.example.Widget`
:java:type:`com.example.Widget.Nested`
:java:method:`com.example.Widget#find(java.lang.String,int)`
:java:method:`com.example.Widget#<init>()`
:java:field:`com.example.Widget#LABEL`
:java:package:`com.example`

java:obj accepts any kind. Targets are fully qualified: there are no imports or short-name guessing. Parameters are erased, fully qualified types, with [] for varargs; constructors are <init>. A method without a parameter list resolves only when it has one overload; otherwise it warns. References inside Java comments are resolved by the compiler as usual.

Source links

Enable sphinx.ext.linkcode to add a [source] link to each declaration. For the java domain, info holds fullname (the canonical ID), source (the file path relative to its source root, such as com/example/Widget.java) and line:

extensions = ['sphinx_java_autodoc', 'sphinx.ext.linkcode']

def linkcode_resolve(domain, info):
    if domain != 'java' or not info['line']:
        return None
    return (
        'https://github.com/example/project/blob/main/src/main/java/'
        f"{info['source']}#L{info['line']}"
    )

line is empty for packages and for compiler-generated members, such as an enum’s values(). With several source roots, choose the root in linkcode_resolve, for example by checking which root contains source.

External Javadoc and intersphinx

Map package prefixes to Javadoc roots; the longest prefix wins:

java_external_javadoc = {
    'java': 'https://docs.oracle.com/en/java/javase/25/docs/api/{module}/',
    'vendor.api': 'https://vendor.example/docs/api/',
}

{module} becomes the referenced module, such as java.base. Links use the Javadoc 9+ URL structure; Javadoc 8 anchors are not supported. URLs are built without fetching or checking the remote site.

A role that no source comment references has no module metadata. For those, map the exact package without {module}:

java_external_javadoc = {
    'java.lang': 'https://docs.oracle.com/en/java/javase/25/docs/api/java.base/',
}

For external members written by hand, use the Javadoc fragment spelling: ... for varargs and declared type variables. The extension cannot check these.

Every documented object is in objects.inv, so another Sphinx project can link to it with intersphinx and the same Java roles, without sources or a JDK:

extensions = ['sphinx_java_autodoc', 'sphinx.ext.intersphinx']
intersphinx_mapping = {
    'library': ('https://docs.example/library/', None),
}

For supported Javadoc tags, HTML and snippets, see Supported Javadoc.