如何用doxygen记录Python代码

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

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

1> 小智..：

---

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

---

您可能还想查看[doxypypy](https://pypi.python.org/pypi/doxypypy),因为它会将Pythonic docstrings转换为Doxygen可以使用的东西.

---

Doxypy似乎已经死了。

---

遗憾的是，这个答案是该问题的正确答案，它也位于底部:(

2> Blair Conrad..：

---

这在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命令？

---

Python中的文档注释很糟糕.注释是针对模块维护者的(为什么以及如何实现).所有文档都应该在docstrings中(如何使用).

---

看一下[doxypy](http://code.foosel.org/doxypy),它可以在普通文档字符串中使用_special commands_.

---

Python将引入注释并将它们用作文档字符串,因此这两种格式都适用于pydoc.

3> Havok..：

---

最后,您只有两个选择:

您可以使用Doxygen生成内容,或使用Sphinx*生成内容.

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

Sphinx:用于记录Python项目的事实工具.这里有三个选项:手动,半自动(存根生成)和全自动(Doxygen).

对于手动API文档,您有Sphinx autodoc.编写带有嵌入式API生成元素的用户指南非常棒.

对于半自动,你有Sphinx autosummary.您可以设置构建系统以调用sphinx-autogen或使用autosummary_generate配置设置Sphinx .您需要使用自动连接设置页面,然后手动编辑页面.你有选择,但我对这种方法的经验是,它需要太多的配置,最后甚至在创建新模板后,我发现了错误,并且不可能确定公开API的内容以及不公开的内容.我的观点是这个工具适用于需要手动编辑的存根生成,仅此而已.就像一个以手册结尾的捷径.

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

还有其他选择需要注意:

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

pydoctor*:非常特别.生成自己的输出.它与Sphinx有一些基本的集成,还有一些不错的功能.

4> Allen..：

---

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

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

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

---

当你在一些难以记录的项目中试图理解类之间的结构和关系时,"手写"文档是不可用的.

---

确实,sphinx使用独立于源代码编写的文档作为基础,但使用autodoc扩展可以很容易地包含来自python模块的文档字符串.由于它的动态特性,我发现python模块的手写文档比生成的api文档更有用.

5> Peter Hoffma..：

---

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

来自sphinx网站:

输出格式:HTML(包括Windows HTML帮助)和LaTeX,用于可打印的PDF版本

广泛的交叉引用:语义标记和功能,类,术语表术语和类似信息的自动链接

分层结构:轻松定义文档树,自动链接到兄弟姐妹,父母和孩子

自动索引:一般索引以及模块索引

代码处理:使用Pygments荧光笔自动突出显示

扩展:自动测试代码片段,包含Python模块中的文档字符串等

---

试过了.虽然狮身人面像本身就是一个非常有趣的工具,但它并不是我所期望的来自doxygen.更多的是一个真正优秀的最终客户文档的工具,对于那些希望以可打印的格式看到API概述的SW设计者来说,doxygen更好.

---

@Zane我同意.作为Doxygen爱好者,我错过了全自动API参考指南生成.检查我的答案,因为现在有其他选项可用.