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

由于我熟悉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能够检测到#block或者"""块中的注释的差异感到有些惊讶，无论哪种情况，我们都可以使用特殊命令。也许他们希望使用"""的人遵守更多的Python文档实践，而这会干扰特殊的doxygen命令？

回答

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

从狮身人面像网站：

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

回答

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

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

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

回答

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