我喜欢用 Doxygen 创建 C 或 PHP 代码的文档。我有一个即将到来的 Python 项目，我想我记得 Python 没有 /* .. */ cmets，而且还有它自己的自我文档工具，这似乎是 Python 式的文档方式。
由于我熟悉 Doxygen，如何使用它来生成 Python 文档？有什么特别需要我注意的吗？
【问题讨论】：
标签： python documentation python-sphinx doxygen docstring
这里是documented on the doxygen website，但在这里总结一下：
您可以使用 doxygen 来记录您的 Python 代码。您可以使用 Python 文档字符串语法：
"""@package docstring
Documentation for this module.
More details.
"""
def func():
"""Documentation for a function.
More details.
"""
pass
在这种情况下，cmet 将被 doxygen 提取，但您将无法使用任何 special doxygen commands。
或者您可以（类似于 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 可以检测到 ## 块或“””块中的 cmets，大部分工作都将完成，您就可以使用两种情况下的特殊命令。也许他们希望使用“”的人遵守更多 Pythonic 文档实践，这会干扰特殊的 doxygen 命令？
最后，你只有两个选择：
您使用 Doxygen 生成内容，或者使用 Sphinx* 生成内容。
Doxygen：它不是大多数 Python 项目的首选工具。但是，如果您必须处理用 C 或 C++ 编写的其他相关项目，这可能是有道理的。为此，您可以使用 doxypypy 改进 Doxygen 和 Python 之间的集成。
Sphinx：用于记录 Python 项目的事实工具。您在这里有三个选项：手动、半自动（存根生成）和全自动（类似 Doxygen）。
autosummary_generate 配置设置 Sphinx。您将需要使用自动摘要设置页面，然后手动编辑页面。你有选择，但我对这种方法的经验是它需要太多的配置，最后即使在创建新模板之后，我也发现了错误，并且无法准确地确定哪些公开为公共 API，哪些不公开。我的观点是这个工具非常适合需要手动编辑的存根生成，仅此而已。就像是手动结束的捷径。还有其他选项需要注意：
【讨论】：
__all__ 变量显式中时，我看不出 AutoAPI 是如何“全自动”的。
【讨论】：
另一个非常好的文档工具是sphinx。它将用于即将推出的 python 2.6 documentation，并被 django 和许多其他 python 项目使用。
来自狮身人面像网站：
【讨论】：