Troubleshoot a documentation build¶
Run sphinx-build -W --keep-going -n docs docs/_build/html from your project
root. Fix the first extraction or compiler error before chasing missing API
pages; those pages depend on successful extraction.
The build cannot find JDK 25¶
Check java -version, javac -version and javadoc --version. Set
java_jdk = "/path/to/jdk-25" in conf.py if the default Java runtime is an
older JDK. Extraction uses the tools from the selected runtime’s actual home.
java_release = "17" selects the library’s source/API release; it does not
allow extraction to run on JDK 17.
The compiler reports a missing package or symbol¶
Check java_sources and java_classpath relative to conf.py. Supply
existing dependency JARs or class directories, and produce generated sources
before extraction. List files explicitly; classpath wildcards are unsupported.
See Build with dependencies and CI for Maven, Gradle and multiple source roots.
A type, member or link is missing¶
Check that the declaration’s source is included and that visibility permits it.
Private, package-private and @hidden declarations are omitted. Methods that
are inherited without an override stay on the declaring ancestor’s page.
In a handwritten guide, use a fully qualified target. Include parameter types
for overloaded methods, for example org.apache.commons.lang3.StringUtils#abbreviate(java.lang.String,int).
A member selection uses semicolons between entries. See Configuration and reference for the
exact role and directive syntax and external Javadoc configuration.
An excerpt produces duplicate-documentation warnings¶
Add :no-index: to the java:autoclass directive in your guide if the type
also has a generated API page. Keep one canonical location for each object.
The extension refuses to overwrite a generated page¶
Move your handwritten content outside the generated directory and back it up
before removing the edited file. The next build can recreate a missing generated
page. Keep API prose in Java comments and guide prose in handwritten .rst pages;
the generated-page manifest protects edited and unowned files from replacement.
A removed type still has an HTML page¶
Sphinx may retain old HTML in an existing output directory even after generated
sources and inventory entries are removed. Publish from a clean output directory.
Each independent Sphinx process also needs its own generated-source/output
directories; a single build’s -j 2 workers are supported.
Comments are incomplete or produce warnings¶
Traditional Javadoc descriptions, common tags and plain inline
{@snippet}bodies are supported; see Supported Javadoc for the supported content.///Markdown comments, unsupported tags and unsupported HTML warn with an alternative or source symbol. External/hybrid snippets, regions, IDs and markup actions warn and keep the original tag as literal text; snippets are never executed. Malformed comments and unresolved links also warn. Use traditional comments and supported markup for content you need to publish.To inherit a dependency’s Javadoc, include its source as well as its binaries. Those additional sources are also eligible for generated pages. Unresolved explicit inheritance is marked visibly and warned; missing inherited parts also warn. Class and constructor documentation does not inherit.
Warnings use
java.extract,java.html,java.type,java.memberand related Sphinx categories. Suppressing a warning does not supply missing content. JDK/compiler failures stop the build and preserve prior output. For extraction outside Sphinx, use--warnings-as-errorsto fail on extraction diagnostics. Run strict builds: