sphinx-javadoc-xml

A Sphinx extension that renders Java API documentation from an XML doclet output in a JavaDoc-inspired style — fully integrated with your Sphinx theme, with cross-links to OpenJDK Javadoc and between all defined types.

Features

• Full XML doclet support: classes, interfaces, enums, methods, fields, constructors, annotations, type parameters, bounded wildcards, exceptions
• OpenJDK cross-links: java.util.List becomes a clickable link to the Oracle JDK 21 docs (configurable URL)
• Internal cross-references: all types defined in your API link to each other
• Package name stripping: types within the same package show short names
• Three directives: full API, single class, or package summary
• Theme-compatible CSS: works with Furo, Read the Docs, Alabaster, and others

Installation

pip install sphinx-javadoc-xml

Quick Start

1. Enable in conf.py

extensions = [
    "sphinx_javadoc_xml",
]

# Optional configuration
javadoc_jdk_url = "https://docs.oracle.com/en/java/javase/21/docs/api"
javadoc_load_fonts = True    # Load Roboto fonts from Google Fonts CDN
javadoc_load_bulma = False   # Load Bulma CSS from CDN (for non-Bulma themes)

With manticore-sphinx-theme

When using manticore-sphinx-theme, the extension automatically inherits the Manticore color scheme (--bst-* CSS variables), Roboto fonts, and Bulma CSS from the theme — no extra configuration needed:

html_theme = "manticore_sphinx_theme"
extensions = ["sphinx_javadoc_xml"]
# Fonts and Bulma are auto-detected and skipped (already provided by theme)

With other themes

The extension ships with the Manticore color scheme as defaults and loads Google Fonts (Roboto family) automatically. Optionally enable Bulma for enhanced table rendering:

html_theme = "furo"  # or alabaster, sphinx_rtd_theme, etc.
extensions = ["sphinx_javadoc_xml"]
javadoc_load_bulma = True  # Optional: pull Bulma from CDN

2. Place your XML file

docs/
├── _static/
│   └── api.xml
├── conf.py
└── api.rst

3. Use the directives

Full package API:

.. javadoc-api:: _static/api.xml
   :package: net.sf.jsqlparser.expression
   :public-only:

Single class:

.. javadoc-class:: _static/api.xml
   :class: net.sf.jsqlparser.expression.Function
   :public-only:

Package summary only (no type details):

.. javadoc-package:: _static/api.xml
   :package: net.sf.jsqlparser.statement.select
   :public-only:

Directives Reference

.. javadoc-api:: <path>

.. javadoc-class:: <path>

.. javadoc-package:: <path>

Configuration (conf.py)

Cross-Linking

The extension automatically creates hyperlinks:

• JDK types → Oracle Javadoc (e.g., java.util.List → docs.oracle.com/...)
• Internal types → anchor links within the same page or document
• External links open in a new tab and show a small ↗ indicator

Theme Compatibility

The CSS uses CSS custom properties (--jdx-*) that automatically inherit from manticore-sphinx-theme's --bst-* variables when available:

All CSS selectors are prefixed with javadoc- so they never conflict with theme styles.

The extension expects the XML structure produced by the xml-doclet or a compatible custom doclet. See the CHANGELOG for supported elements.

XML Format

The extension expects the XML structure produced by the xml-doclet or a compatible custom doclet. See the CHANGELOG for supported elements.

Publishing to PyPI

# Build
python -m build

# Upload to TestPyPI first
twine upload --repository testpypi dist/*

# Upload to PyPI
twine upload dist/*

Or use GitHub Actions with OIDC trusted publishing.

License

MIT