用Python-Sphinx解析javadoc

Question

我使用一个部分包含Java和Python代码的共享存储库。代码的基础主要是python，但是有些库是用Java编写的。

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

Answer 1

javadoc命令允许您编写和使用您自己的doclet类来生成您选择的任何形式的文档。输出不需要直接人类可读的.所以没有什么能阻止你输出斯芬克斯兼容的格式。

但是，我找不到任何现有的doclet来完成这个特定的工作。

参考文献：

• 甲骨文的Doclet概述

更新

鸦胆子素扩展可能是更好的选择。它允许您从嵌入在Java源代码中的javadoc注释生成Sphinx文档。

Answer 2

(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版本似乎已经中断了进口，这些问题似乎在最近的检查中并不存在。

设置与配置

假设您已经有了一个工作的狮身人面像装置：

重要：将java“域”添加到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，如果当前环境处于活动状态，您可以将其称为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 3

狮身人面像不提供解析JavaDoc的内置方式，我也不知道这个任务有任何第三方扩展。

您可能需要为Sphinx自动文档扩展编写自己的文档。您可能会遵循不同的方法：

• 手动解析JavaDoc。不过，我不认为有用于Python的JavaDoc pParser。
• 使用DO2将JavaDoc解析为XML，并解析该XML。狮身人面像扩展呼吸可以做到这一点，尽管是针对C++的。
• 编写一个Doclet，将JavaDoc转换为您可以处理的任何输出格式，并解析这个输出。