Choosing a tool

Several tools put Java API documentation into Sphinx, and a plain Javadoc site is always an option. This page shows how they compare so you can pick the one that fits your project, even if that isn’t this extension.

The other tools were assessed in October 2026 by reading their documentation and source code, not by running them. If something here is out of date, please open an issue.

At a glance

	sphinx-java-autodoc	sphinx-javadoc-xml	javasphinx	Doxygen + Breathe / Exhale
Maintained	Yes	Yes	No, archived in 2019	Yes
Reads your Java with	The JDK’s own javadoc tool	A third-party XML doclet you run in Maven or Gradle	javalang, a Python parser for Java 8 syntax	Doxygen’s own parser
Modern Java (records, sealed types, modules)	Whatever JDK 25 accepts	Limited to what the XML doclet records; no record components	No	Partial
{@link} in comments	Clickable link to the resolved target	Shown as code, not linked	Linked by name, resolved by Sphinx	Linked by Doxygen’s resolver
{@inheritDoc}	Resolved; a warning if it can’t be	Removed	Not supported	Handled by Doxygen
Comment rendering	Native Sphinx nodes	Converted to reStructuredText text	HTML converted to reStructuredText text	Breathe: native nodes; Doxysphinx: Doxygen HTML
Java roles for your own pages (:java:type:)	Yes	No	Yes	No, only the C++ domain
Intersphinx inventory for other sites	Yes	No	Yes	C++ objects only
Look	Follows your Sphinx theme	Own Javadoc-style CSS; loads web fonts from a CDN by default	Follows your Sphinx theme	Follows your Sphinx theme
API pages	Generated during the Sphinx build	One directive per API, package or class in your pages	Generated by a separate command; you commit the files	One directive per class, or generated by Exhale
Needs at docs build time	JDK 25, or no JDK with a pre-extracted model	Only the XML file	Only Python	The doxygen program

When to choose which

sphinx-java-autodoc fits when you want guides and the API reference in one Sphinx site, with links that resolve and inherited documentation that stays in place. You need JDK 25 to extract, although your library can target Java 17 or 21. See Compatibility and limits for tested versions and known limits.

sphinx-javadoc-xml fits when you already produce XML doclet output in your build and want a page that looks like classic Javadoc, and missing {@link} targets and inherited comments don’t matter for your API.

javasphinx isn’t a good choice for new projects. Its own README says it should be used for historical purposes only, and it can’t parse Java newer than 8. Several forks exist, but none is released under a new name.

Doxygen with Breathe or Exhale fits when one site documents C or C++ next to Java and you already run Doxygen. Its Java support is secondary, and Java objects appear as C++ ones in Sphinx.

A separate Javadoc site fits when your readers expect the standard Javadoc layout and your guides can live elsewhere. Sphinx pages can link to it with sphinx.ext.extlinks. sphinx-javalink did this with Java-aware roles but hasn’t changed since 2016.

The design notes explain why this extension uses the JDK instead of these approaches.