关于文档：如何使用doxygen记录Python代码

How to document Python code with doxygen

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

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

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

这在doxygen网站上有记录，但在此处进行总结：

您可以使用doxygen来记录您的Python代码。您可以使用Python文档字符串语法：

1
2
3
4
5
6
7
8
9
10
11
12

"""@package docstring
Documentation for this module.

More details.
"""

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

More details.
"""
pass

在这种情况下，注释将由doxygen提取，但是您将无法使用任何特殊的doxygen命令。

或者，您可以(类似于doxygen下的C样式语言)在成员之前的第一行将注释标记(#)加倍：

1
2
3
4
5
6
7
8
9
10

## @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命令？

最后，您只有两个选择：

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

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

Sphinx：用于记录Python项目的事实上的工具。这里有三个选项：手动，半自动(桩生成)和全自动(类似于Doxygen)。

对于手动API文档，您可以使用Sphinx autodoc。编写带有嵌入式API生成的元素的用户指南非常好。

对于半自动，您可以使用Sphinx自动摘要。您可以设置构建系统以调用sphinx-autogen，也可以使用autosummary_generate配置来设置Sphinx。您将需要使用自动摘要设置页面，然后手动编辑页面。您可以选择，但是我对这种方法的经验是，它需要太多的配置，最后，即使在创建了新模板之后，我也发现了错误，并且无法确切地确定公开为公共API的内容，而不是确定什么。我的意见是，此工具非常适合需要手动编辑的存根生成，仅此而已。就像以手动方式结束的捷径。

全自动。这已经被无数次批评，并且很长时间以来，直到AutoAPI出现之前，我们一直没有一个与Sphinx集成的好的全自动Python API生成器，这是一个新手。到目前为止，这是在Python中自动生成API的最佳方法(请注意：无耻的自我推广)。

还有其他选项要注意：

呼吸：这是一个非常好的主意，当您使用其他使用Doxygen的语言处理多个相关项目时，这是很有意义的。这个想法是使用Doxygen XML输出并将其提供给Sphinx以生成您的API。因此，您可以保留Doxygen的所有优点，并统一Sphinx中的文档系统。理论上很棒。现在，实际上，我最后一次检查项目尚未准备好进行生产。
pydoctor *：非常特别。生成自己的输出。它与Sphinx有一些基本的集成，并具有一些不错的功能。

据我了解，Sphinx主要是用于格式化独立于源代码编写的文档的工具。

为了从Python文档字符串生成API文档，主要的工具是pdoc和pydoctor。这是pydoctor为Twisted和Bazaar生成的API文档。

当然，如果您只是想在处理工作时查看文档字符串，则可以使用" pydoc"命令行工具以及交互式解释器中的help()函数。

另一个非常好的文档工具是狮身人面像。它将用于即将发布的python 2.6文档，并由django和许多其他python项目使用。

从狮身人面像网站：