java - 使用 Python-Sphinx 解析 javadoc

Question

我使用部分包含 Java 和 Python 代码的共享存储库。代码基础以python为主，部分库用java编写。

是否有可能解析或预处理 Java 文档以便使用 稍后在 Python-Sphinx 甚至插件中？

Answer 1

javasphinx ( Github ) ( Documentation )

我花了很长时间才找到所有重要的细节来设置它，所以这里有一个简短的说明来解决我所有的麻烦。

安装

# 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

pypi 版本似乎有错误的导入，这些问题在最近的检查中似乎不存在。

设置和配置

假设您有一个可用的 sphinx setup已经:

重要:将 java “域”添加到 sphinx，这是嵌入在 javasphinx 包中的，不遵循常见的 .ext. 扩展命名空间格式。 (这是我错过了几个小时的细节):

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

可选:如果你想要external javadoc linking :

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

生成文档

javasphinx 包添加了 shell 工具 javasphinx-apidoc，如果您当前的环境是 Activity 的，您可以直接调用它 javasphinx-apidoc ，或使用其完整路径:./env/bin/javasphinx-apidoc:

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

此工具采用与 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

在索引中包含生成的文档

在 javasphinx-apidoc 命令的输出目录中，将生成一个 packages.rst 目录文件，您可能希望包含此文件进入您的 index.html 的目录，例如:

#docs/sources/index.rst 

Contents:

.. toctree::
   :maxdepth: 2

   packages

编译文档(html)

激活 python 环境或修改路径:

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