如何使用Doxygen文档化Python代码

Question

我喜欢用Doxygen来为C或PHP代码生成文档。我有一个即将开始的Python项目，我记得Python好像没有那种/* .. */的注释方式，而且它还有自己的一套文档生成方式，这似乎是Python推荐的文档写法。

因为我对Doxygen很熟悉，我想知道怎么用它来生成我的Python文档？有没有什么特别需要注意的地方？

Answer 1

最后，你只有两个选择：

你可以用 Doxygen 来生成内容，或者用 Sphinx 来生成内容。

1. Doxygen：这不是大多数 Python 项目的首选工具。不过，如果你需要处理一些用 C 或 C++ 写的相关项目，那用 Doxygen 可能会有意义。为了更好地把 Doxygen 和 Python 结合起来，你可以使用 doxypypy。

2. Sphinx：这是记录 Python 项目的标准工具。这里你有三种选择：手动、半自动（生成模板）和完全自动（像 Doxygen 一样）。

   1. 对于手动 API 文档，你可以使用 Sphinx 的 autodoc。这个工具非常适合写用户指南，并且可以嵌入生成的 API 元素。
   2. 对于半自动，你可以使用 Sphinx 的 autosummary。你可以设置你的构建系统来调用 sphinx-autogen，或者在 Sphinx 中配置 autosummary_generate。你需要设置一个包含自动摘要的页面，然后手动编辑这些页面。虽然有很多选择，但我个人的经验是，这种方法需要太多配置，最后即使创建了新的模板，我也发现了很多bug，无法准确判断哪些是公开的 API，哪些不是。我认为这个工具适合生成需要手动编辑的模板，仅此而已。就像是一个捷径，结果还是得手动处理。
   3. 完全自动。这种方式曾多次受到批评，之前我们没有一个好的完全自动的 Python API 生成器与 Sphinx 集成，直到 AutoAPI 出现，它是个新玩意儿。这是目前为止在 Python 中自动生成 API 的最佳选择（注意：这是我自己的推广）。

还有其他值得注意的选项：

• Breathe：这个项目开始时是个很好的想法，当你在处理多个使用 Doxygen 的相关项目时，它是有意义的。这个想法是使用 Doxygen 的 XML 输出，然后把它输入到 Sphinx 中来生成你的 API。这样，你可以保留 Doxygen 的优点，并在 Sphinx 中统一文档系统。理论上听起来很棒。不过在实际操作中，我上次检查时发现这个项目还没有准备好投入生产。
• pydoctor*：这个工具很特别。它生成自己的输出，和 Sphinx 有一些基本的集成，还有一些不错的功能。

Answer 2

doxypy 是一个输入过滤器，它让你可以在标准的 Python 文档字符串中使用几乎所有 Doxygen 的格式标签。我用它来给一个包含大量 C++ 和 Python 的游戏应用框架写文档，效果很好。

Answer 3

这段内容在 doxygen 网站上有详细说明，不过我在这里简单总结一下：

你可以用 doxygen 来给你的 Python 代码写文档。你可以使用 Python 的文档字符串语法：

"""@package docstring
Documentation for this module.

More details.
"""

def func():
    """Documentation for a function.

    More details.
    """
    pass

这样的话，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 能够识别 ## 块或 """ 块中的注释，大部分工作就完成了，应该可以在这两种情况下都使用特殊命令。也许他们认为使用 """ 的人会遵循更符合 Python 风格的文档写作方式，这样会影响到特殊的 doxygen 命令？