Parsing javadoc with Python-Sphinx

问题:

I use a shared repository partly containing Java and Python code. The code basis mainly stands on python, but some libraries are written in Java.

Is there a possibility to parse or preprocess Java documentation in order to use it later in Python-Sphinx or even a plugin?

回答1:

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.

回答2:

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

回答3:

Sphinx does not provide a built-in way to parse JavaDoc, and I do not know of any 3rd party extension for this task.

You'll likely have to write your own documenter for the Sphinx autodoc extension. There are different approaches you may follow:

• Parse JavaDoc manually. I do not think that there is a JavaDoc pParser for Python, though.
• Use Doxygen to parse JavaDoc into XML, and parse that XML. The Sphinx extension breathe does this, though for C++.
• Write a Doclet for Java to turn JavaDoc into whatever output format you can hande, and parse this output.