8

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

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

4

3 回答 3

13

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 版本似乎已经破坏了导入，这些问题在最新的结帐中似乎不存在。

设置和配置

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

重要提示：将 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 tool 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
于 2016-07-11T02:03:45.283 回答
6

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

但是，我找不到任何执行此特定工作的现有 doclet。

参考：

更新

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

于 2013-01-10T09:32:27.503 回答
0

Sphinx 没有提供解析 JavaDoc 的内置方法，而且我不知道有任何 3rd 方扩展可用于此任务。

您可能必须为 Sphinx autodoc 扩展编写自己的文档。您可以采用不同的方法：

  • 手动解析 JavaDoc。不过，我认为没有适用于 Python 的 JavaDoc pParser。
  • 使用 Doxygen 将 JavaDoc 解析为 XML，然后解析该 XML。Sphinx 扩展呼吸可以做到这一点，尽管对于 C++。
  • 为 Java 编写一个 Doclet 以将 JavaDoc 转换为您可以处理的任何输出格式，并解析此输出。
于 2013-01-10T09:37:14.307 回答