如何在 Jython 项目中创建基于 Sphinx 的文档？答案

【问题标题】：How to create Sphinx-based documentation in a Jython project?如何在 Jython 项目中创建基于 Sphinx 的文档？
【发布时间】：2011-02-08 11:14:51
【问题描述】：

我正在使用用 Java 编写的库处理多个 Jython 项目。感谢 autodoc 扩展，我想用 Sphinx 创建一些好的文档。但是，当我尝试创建 html 时，出现错误，因为 autodoc 找不到用 Java 编写的库：

sphinx-build -b html -d _build/doctrees   . _build/html
Running Sphinx v1.0.5
loading pickled environment... done
building [html]: targets for 1 source files that are out of date
updating environment: 0 added, 1 changed, 0 removed
reading sources... [100%] index

/Users/myName/myJythonProject/doc/index.rst:14: (WARNING/2) 
autodoc can't import/find module 'myJythonProject', it reported error: 
"global name 'PoolManager' is not defined",
please check your spelling and sys.path

其中 PoolManager 是一个 Java 类。

谁能帮我解决这个问题？

【问题讨论】：

对不起，以前没有使用过 Jython，但是您是否尝试过创建一个包装器来捕获“python”调用，这样当 Sphinx 调用 python 时，它最终会调用调用 jython 的包装器？另一件事是，对于我的项目，我必须包装我的一些 imports 和专门为 Sphinx 编写的代码。您可以在导入 jython 库之前检查环境变量或其他一些全局变量吗？或者，您可以创建与您正在使用的 jython 库具有相同接口的虚拟 python 库，并且仅在运行 Sphinx 时导入这些虚拟库 [cont]
操作环境变量PYTHON_PATH或sys.path。
感谢您的回答。我会试试你的建议。
我在尝试为我的 C++ 代码（导出到 python）创建文档时遇到了类似的问题。我用于创建 python 绑定的工具 - sip 也有一些用于导出文档的选项。您用于 java 的那个可能也有。

标签： java python jython python-sphinx

【解决方案1】：

Sphinx 可用于记录 Jython 项目，但 autodoc 不适用于用 Java 编写的代码。自动文档功能导入和检查 Python 模块。不支持对 Java 类执行相同操作。

为 Java 实现 autodoc（或类似的东西）似乎是可行的，但必须有人自愿去做。请参阅 Sphinx 作者 Georg Brandl 的评论：https://www.mail-archive.com/sphinx-dev@googlegroups.com/msg03162.html。

我找到了一些关于a proposed GSoC 2010 project 的信息，旨在实现对autodoc 的多语言支持。但根据this blog post 的说法，该项目尚未完成。开发人员选择从事另一个 GSoC 项目。

sphinx-contrib repository 不包含任何与 autodoc 相关的内容。

更新

有一个名为javasphinx 的新Sphinx 扩展，看起来很有趣。我没有用过这个扩展，但是根据the documentation，它可以从Java代码生成reST源：

javasphinx-apidoc 工具是 sphinx-apidoc 工具的对位在 Java 域中。它可用于从现有的生成 reST 源已使用 Javadoc 样式的 cmets 标记的 Java 源代码。这生成的 reST 然后由 Sphinx 与手写文档一起处理。

javasphinx 使用另一个名为 javalang 的库。

PyPI 包：

【讨论】：

感谢您的详细回答。这证实了我的想法。在实现之前，我将不得不处理没有自动文档的问题。
javasphinx 项目不再活动。请参阅github.com/bronto/javasphinx 和github.com/sphinx-doc/sphinx/issues/10054。