我喜欢用 Doxygen 创建 C 或 PHP 代码的文档。我有一个即将到来的 Python 项目，我想我记得 Python 没有/* .. */注释，并且还有自己的自我文档工具，这似乎是 Python 的文档方式。
由于我熟悉 Doxygen，如何使用它来生成 Python 文档？有什么特别需要我注意的吗？
Hanno
问问题
137066 次
5 回答
90
doxypy输入过滤器允许您以标准 Python 文档字符串格式使用几乎所有 Doxygen 的格式化标签。我用它来记录一个大型的混合 C++ 和 Python 游戏应用程序框架，它运行良好。
于 2009-01-30T21:30:02.833 回答
68
这记录在 doxygen 网站上，但在这里总结一下：
你可以使用 doxygen 来记录你的 Python 代码。您可以使用 Python 文档字符串语法：
"""@package docstring
Documentation for this module.
More details.
"""
def func():
"""Documentation for a function.
More details.
"""
pass
在这种情况下，注释将被 doxygen 提取，但您将无法使用任何特殊的 doxygen 命令。
或者#您可以（类似于 doxygen 下的 C 风格语言）将成员之前第一行的注释标记 ( ) 加倍：
## @package pyexample
# Documentation for this module.
#
# More details.
## Documentation for a function.
#
# More details.
def func():
pass
在这种情况下，您可以使用特殊的 doxygen 命令。没有特定的 Python 输出模式，但您显然可以通过设置OPTMIZE_OUTPUT_JAVA为YES.
老实说，我对这种差异感到有些惊讶——似乎一旦 doxygen 可以检测到 ## 块或“””块中的注释，大部分工作就完成了，你就可以使用特殊命令了无论哪种情况。也许他们希望人们使用“””来遵守更多的 Pythonic 文档实践，这会干扰特殊的 doxygen 命令？
于 2008-09-12T11:11:03.123 回答
26
最后，您只有两个选择：
您使用 Doxygen 生成内容，或者使用 Sphinx* 生成内容。
Doxygen：它不是大多数 Python 项目的首选工具。但是，如果您必须处理用 C 或 C++ 编写的其他相关项目，这可能是有道理的。为此，您可以使用doxypypy改进 Doxygen 和 Python 之间的集成。
Sphinx：用于记录 Python 项目的事实上的工具。您在这里有三个选项：手动、半自动（存根生成）和全自动（类似 Doxygen）。
- 对于手动 API 文档，您有 Sphinx autodoc。编写带有嵌入式 API 生成元素的用户指南非常棒。
- 对于半自动，您有 Sphinx autosummary。您可以将构建系统设置为调用 sphinx-autogen 或使用
autosummary_generate配置设置 Sphinx。您将需要使用自动摘要设置页面，然后手动编辑页面。你有选择，但我对这种方法的经验是它需要太多的配置，最后即使在创建新模板之后，我也发现了错误并且无法准确地确定哪些公开为公共 API，哪些不公开。我的观点是这个工具非常适合需要手动编辑的存根生成，仅此而已。就像是手动结束的捷径。 - 全自动。这已经被批评了很多次，很长一段时间以来，我们都没有一个很好的与 Sphinx 集成的全自动 Python API 生成器，直到AutoAPI出现，这是一个新手。这是迄今为止 Python 中自动生成 API 的最佳方式（注意：无耻的自我推销）。
还有其他选项需要注意：
于 2016-02-13T08:16:17.877 回答
14