Troubleshooting

Fix the first extraction or compiler error first: missing API pages usually follow from it.

The build cannot find JDK 25

Check java -version, javac -version and javadoc --version, or set java_jdk = "/path/to/jdk-25" in conf.py. java_release = "17" sets the library’s target release; extraction still runs on JDK 25.

The compiler reports a missing package or symbol

Add the dependency’s JAR or class directory to java_classpath (paths relative to conf.py, no wildcards), and generate sources before the build. See Add dependencies and publish.

A type, member or link is missing

• Check that the source is in java_sources and that java_visibility includes it. Private, package-private and @hidden declarations are omitted.

• Inherited methods without an override appear on the ancestor’s page.

• Role targets must be fully qualified, with parameter types for overloads: org.apache.commons.lang3.StringUtils#abbreviate(java.lang.String,int). Separate :members: entries with semicolons. See Configuration reference.

An excerpt produces duplicate-documentation warnings

Add :no-index: to the java:autoclass directive in your guide when the type also has a generated page.

Comments are incomplete or produce warnings

Unsupported tags, HTML, /// Markdown comments and advanced snippets warn with the symbol; see Supported Javadoc. To inherit a dependency’s Javadoc, add its sources to java_sourcepath.

Warnings use the java.extract, java.html, java.type, java.member and related categories. Suppressing a warning does not add the missing content. Outside Sphinx, --warnings-as-errors makes extraction diagnostics fail.

The extension refuses to overwrite a generated page

You edited a file in the generated directory, or put your own file there. Move your content to a handwritten page, then delete the file; the next build recreates it.

A removed type still has an HTML page

Sphinx keeps old HTML files in an existing output directory. Publish from a clean output directory.