Parsing javadoc with Python-Sphinx

The javadoc command allows you to write and use your own doclet classes to generate documentation in whatever form you choose. The output doesn't need to be directly human-readable ... so there's nothing stopping you outputting in a Sphinx compatible format.

However, I couldn't find any existing doclet that does this specific job.

References:

• Oracle's Doclet Overview

---

UPDATE

The javasphinx extension may be a better alternative. It allows you to generate Sphinx documentation from javadoc comments embedded in Java source code.

javasphinx (Github) (Documentation)

It took me way to long to find all the important details to set this up, so here's a brief for all my trouble.

Installation

# Recommend working in virtual environments with latest pip:
mkdir docs; cd docs
python3 -m venv env
source ./env/bin/activate
pip install --upgrade pip

# Recommend installing from source:
pip install git+https://github.com/bronto/javasphinx.git

The pypi version seemed to have broken imports, these issues did not seem to exist in the latest checkout.

Setup & Configuration

Assuming you've got a working sphinx setup already:

Important: add the java "domain" to sphinx, this is embedded in the javasphinx package and does not follow the common .ext. extension-namespace format. (This is the detail I missed for hours):

# docs/sources/conf.py
extensions = ['javasphinx']

Optional: If you want external javadoc linking:

# docs/sources/conf.py
javadoc_url_map = {
    '<namespace_here>' : ('<base_url_here>', 'javadoc'),
}

Generating Documentation

The javasphinx package adds the shell tool javasphinx-apidoc, if your current environment is active you can call it as just javasphinx-apidoc, or use its full path: ./env/bin/javasphinx-apidoc:

$ javasphinx-apidoc -o docs/source/ --title='<name_here>' ../path/to/java_dirtoscan

This tool takes arguments nearly identical to sphinx-apidoc:

$ javasphinx-apidoc --help
Usage: javasphinx-apidoc [options] -o <output_path> <input_path> [exclude_paths, ...]

Options:
  -h, --help            show this help message and exit
  -o DESTDIR, --output-dir=DESTDIR
                        Directory to place all output
  -f, --force           Overwrite all files
  -c CACHE_DIR, --cache-dir=CACHE_DIR
                        Directory to stored cachable output
  -u, --update          Overwrite new and changed files
  -T, --no-toc          Don't create a table of contents file
  -t TOC_TITLE, --title=TOC_TITLE
                        Title to use on table of contents
  --no-member-headers   Don't generate headers for class members
  -s SUFFIX, --suffix=SUFFIX
                        file suffix (default: rst)
  -I INCLUDES, --include=INCLUDES
                        Additional input paths to scan
  -p PARSER_LIB, --parser=PARSER_LIB
                        Beautiful Soup---html parser library option.
  -v, --verbose         verbose output

Include Generated Docs in Index

In the output directory of the javasphinx-apidoc command there will have been a packages.rst table-of-contents file generated, you will likely want to include this into your index.html's table of contents like:

#docs/sources/index.rst 

Contents:

.. toctree::
   :maxdepth: 2

   packages

Compile Documentation (html)

With either your python environment active or your path modified:

$ cd docs
$ make html
or 
$ PATH=$PATH:./env/bin/ make html