如何用doxygen记录Python代码

Question

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

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

Answer 1

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

Answer 2

这在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可以检测##块或""块中的注释,大部分工作都会完成,你可以使用特殊命令也许他们希望人们使用"""来遵守更多的Pythonic文档实践并且会干扰特殊的doxygen命令？

Answer 3

最后,您只有两个选择:

您可以使用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. 全自动.这已被批评多次,很长一段时间我们没有一个好的全自动Python API生成器与Sphinx集成,直到AutoAPI来了,这是一个新的孩子.到目前为止,这是Python中自动API生成的最佳选择(注意:无耻的自我推销).

还有其他选择需要注意:

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

Answer 4

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

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

当然,如果你只是想看看文档字符串,而你的东西的工作,还有的" 是pydoc "命令行工具,以及将help()在交互式解释可用的功能.

Answer 5

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

来自sphinx网站:

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