如何使用Doxygen记录Python代码

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

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

这在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可以在##块或“”“块中检测到注释时，大部分工作就可以完成，并且您可以在其中使用特殊命令也许他们希望使用“”“的人遵守更多的Python文档实践，而这会干扰特殊的doxygen命令？

该doxypy输入过滤器允许你在一个标准的Python文档字符串格式几乎所有的Doxygen的格式化标签的使用。我用它来记录大型的C ++和Python混合游戏应用程序框架，并且运行良好。

最后，您只有两个选择：

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

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

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

   1. 对于手动API文档，您具有Sphinx autodoc。编写包含嵌入式API生成的元素的用户指南非常好。
   2. 对于半自动，您需要Sphinx autosummary。您可以设置构建系统以调用sphinx-autogen或使用autosummary_generate配置设置Sphinx 。您将需要使用自动摘要设置页面，然后手动编辑页面。您可以选择，但是我对这种方法的经验是，它需要太多的配置，最后，即使在创建新模板之后，我也发现了错误，并且无法确切地确定公开为公共API的内容，而不是确定什么。我认为此工具非常适合需要手动编辑的存根生成，仅此而已。就像以手动方式结束的捷径。
   3. 全自动。这已经被无数次批评，并且很长时间以来，直到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()交互式解释器中提供的功能。

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

从狮身人面像网站：

• 输出格式：HTML（包括Windows HTML帮助）和LaTeX，用于可打印的PDF版本
• 广泛的交叉引用：功能，类，词汇术语和类似信息的语义标记和自动链接
• 层次结构：轻松定义文档树，并自动链接到兄弟姐妹，父母和孩子
• 自动索引：常规索引以及模块索引
• 代码处理：使用Pygments荧光笔自动突出显示
• 扩展：自动测试代码段，包含来自Python模块的文档字符串等