sphinx-java-autodoc

Documentation

Publish your Java library's guides and API reference in one searchable Sphinx site. Keep API contracts in Java sources and Javadoc; write guides that help your users choose an API and complete a task.

sphinx-java-autodoc reads Java sources and Javadoc comments with the JDK compiler APIs and renders them as native Sphinx content:

• Generated, searchable pages for classes, interfaces, enums, records, annotation types and nested types.
• Signatures, overloads, Javadoc links and inherited method documentation.
• Class excerpts in handwritten guides, and links between projects through intersphinx.
• Pages that refresh when sources change, with content-based extraction caching.

Extraction never executes application classes or annotation processors, and never downloads Java dependencies. See the Apache Commons Lang example for what the output looks like.

Requirements

Python 3.12+, Sphinx 9.1.x, and JDK 25 for extraction. Your library can keep targeting Java 17 or 21. See compatibility and limits for the tested versions.

Quick start

uv add sphinx-java-autodoc

In docs/conf.py:

extensions = ["sphinx_java_autodoc"]
java_sources = ["../src/main/java"]
java_release = "17"
java_generate = "api"
java_visibility = "public"

Add api/index to the toctree in docs/index.rst, then build:

uv run sphinx-build -W --keep-going -n docs docs/_build/html

Publish your first API pages walks through these steps. Then continue with:

• Write a guide your users can follow
• Build with dependencies and CI: Maven/Gradle classpaths, pre-extracted models and publishing to GitHub Pages
• Configuration and reference and supported Javadoc
• Troubleshooting
• How it works and the architecture decision

Development

From a clone of this repository:

uv sync --locked
uv run --locked pre-commit install
uv run --locked pre-commit run --all-files
uv run --locked pytest
uv run --locked --group showcase python showcase/build.py
uv run --locked sphinx-build -W --keep-going -n docs docs/_build/html

Development and releases are documented in CONTRIBUTING.md. CI covers lint, compiler warnings, integration tests, built distributions, dependency vulnerabilities, six HTML themes, the text builder, and Chromium browser interactions.

MIT licensed.