Python:使用Python-Sphinx解析javadoc

Question

我使用部分包含Java和Python代码的共享存储库.代码基础主要位于python上,但有些库是用Java编写的.

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

Answer 1

javasphinx(Github)(文档)

我花了很长时间才找到所有重要的细节来设置它,所以这里是我所有麻烦的简要说明.

安装

# 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设置:

重要提示:将java"domain"添加到sphinx,它嵌入在javasphinx包中,不遵循常见的.ext.扩展名称空间格式.(这是我错过了几个小时的细节):

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

可选:如果您想要外部javadoc链接:

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

生成文档

该javasphinx软件包添加了shell工具javasphinx-apidoc,如果您当前的环境处于活动状态,您可以将其称为just 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

Answer 2

javadoc命令允许您编写和使用自己的doclet类以选择的任何形式生成文档。输出不需要是直接可读的...因此，没有什么会阻止您以Sphinx兼容格式进行输出。

但是，我找不到任何可以完成此特定工作的现有doclet。

参考文献：

• Oracle Doclet概述

更新

该javasphinx扩展可能是一个更好的选择。它允许您从Java源代码中嵌入的javadoc注释生成Sphinx文档。