如何用doxygen记录Python代码

Question

我喜欢doxygen来创建C或PHP代码的文档。我有一个即将到来的Python项目，我想我记得Python没有/* .. */注释，还有它自己的自文档功能，这似乎是Python编写文档的方式。

因为我熟悉doxygen，所以如何使用它来生成Python文档？有什么特别需要我注意的吗？

Answer 1

doxypy输入过滤器允许您以标准Python docstring格式使用几乎所有Doxygen的格式化标记。我用它来记录一个大型的混合C++和Python游戏应用框架，并且它运行良好。

Answer 2

这里是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

在这种情况下，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能够检测到blocks或“blocks”中的注释，大部分工作就会完成，而且在这两种情况下都可以使用特殊命令。也许他们希望使用“”的人遵守更多的Pythonic文档实践，这会干扰特殊的doxygen命令？

Answer 3

最后，你只有两个选择：

您可以使用Doxygen生成内容，也可以使用Sphinx*生成内容。

1. Doxygen：它不是大多数Python项目的首选工具。但是如果你必须处理其他用C或C++写的相关项目，这是有意义的。为此，可以使用doxypypy改进Doxygen和Python之间的集成。

2. Sphinx：记录Python项目的实际工具。这里有三个选项：手动、半自动（存根生成）和全自动（类似于Doxygen）。

   1. 对于手动API文档，您有Sphinxautodoc。这对于编写包含嵌入式API生成元素的用户指南非常有用。
   2. 对于半自动，你有狮身人面像autosummary。可以将生成系统设置为调用sphinx autogen，也可以使用autosummary_generate配置设置sphinx。您需要使用自动摘要设置页面，然后手动编辑页面。您可以选择，但我的经验是，这种方法需要过多的配置，最后，即使创建了新模板，我也发现了一些错误，无法确定哪些是公开的公共API，哪些不是。我的意见是，这个工具对于需要手动编辑的存根生成是很好的。就像是一个以手动方式结束的捷径。
   3. 全自动。这已经被批评过很多次了，很长一段时间以来，我们都没有一个好的与Sphinx集成的全自动Python API生成器，直到AutoAPI出现，这是块中的一个新孩子。这是目前为止Python中自动生成API的最佳方法（注意：无耻的自我提升）。

还有其他选项需要注意：

• Breathe：这是一个非常好的主意，当您使用其他使用Doxygen的语言处理几个相关的项目时，这是有意义的。其思想是使用Doxygen XML输出并将其提供给Sphinx以生成API。因此，您可以保留Doxygen的所有优点，并将文档系统统一到Sphinx中。理论上很不错。现在，实际上，我最后一次检查这个项目还没有准备好生产。
• pydoctor*：非常特别。生成自己的输出。它与狮身人面像有一些基本的集成，还有一些不错的特性。