Question

我喜欢doxygen来创建C或PHP代码的文档。我有一个即将推出的Python项目，我想我记得Python没有/* .. */条评论，并且还有自己的自我文档工具，这似乎是文档的pythonic方式。

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

Answer 1

doxypy输入过滤器允许您以标准Python文档字符串格式使用几乎所有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可以检测##块或“”块中的注释，大部分工作都会完成，你就可以使用在任何一种情况下的特殊命令。也许他们希望使用“”“的人坚持更多的Pythonic文档实践，这会干扰特殊的doxygen命令？

Answer 3

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

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

当然，如果您只想在处理内容时查看文档字符串，可以使用“pydoc”命令行工具以及help()函数。互动翻译。

Answer 4

最后，您只有两个选择：

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

Doxygen ：它不是大多数Python项目的首选工具。但是，如果你必须处理用C或C ++编写的其他相关项目，它可能是有道理的。为此，您可以使用doxypypy改善Doxygen和Python之间的集成。
Sphinx ：用于记录Python项目的事实工具。这里有三个选项：手动，半自动（存根生成）和全自动（Doxygen）。
1. 对于手动API文档，您有Sphinx autodoc。编写带有嵌入式API生成元素的用户指南非常棒。
2. 对于半自动，你有狮身人面像autosummary。您可以设置构建系统以调用sphinx-autogen或使用autosummary_generate配置设置Sphinx。您需要使用自动连接设置页面，然后手动编辑页面。你有选择，但我对这种方法的经验是，它需要太多的配置，最后甚至在创建新模板后，我发现了错误，并且无法确定公开API的内容以及不公开的内容。我的观点是这个工具适用于需要手动编辑的存根生成，仅此而已。就像是以手册结尾的捷径。
3. 全自动。这已被批评多次，很长一段时间我们没有一个好的全自动Python API生成器与Sphinx集成，直到AutoAPI来了，这是一个新的孩子。到目前为止，这是Python中自动API生成的最佳选择（注意：无耻的自我推销）。

还有其他选择需要注意：

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

Answer 5

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

来自sphinx网站：

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

如何用doxygen记录Python代码

5 个答案: