我可以使用doxygen编写Python代码吗（这是否合理）？

我喜欢doxygen来创buildC或PHP代码的文档。 我有一个即将到来的Python项目，我想我记得Python没有/ * .. * /注释，也有自己的自我文档设施，这似乎是Python文档的方式。

我可以只使用doxygen吗？ 有什么特别需要注意的？

我已经在Python中做了一些编码，但到目前为止，只在我懒得logging的小项目上（是的，我知道…但现在我们假装没问题）。

Answer 1

这是在doxygen网站上logging ，但总结在这里：

你可以使用doxygen来logging你的Python代码。 您可以使用Python文档string语法：

"""@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 2

doxypyinputfilter允许您以标准的Python文档string格式使用几乎所有的Doxygen格式化标签。 我用它来logging一个大型混合的C ++和Python游戏应用程序框架，并且运行良好。

Answer 3

据我所知，狮身人面像主要是一个格式化独立于源代码的文档的工具。

为了从Python docstrings生成API文档，领先的工具是pdoc和pydoctor 。 这里是pydoctor为Twisted和Bazaar生成的API文档。

当然，如果你只是想在处理文档时查看文档string，可以使用“ pydoc ”命令行工具以及交互式解释器中提供的help()函数。

Answer 4

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

从狮身人面像网站：

• 输出格式 ：HTML（包括Windows HTML帮助）和LaTeX，用于可打印的PDF版本
• 广泛的交叉引用 ：语义标记和function，类，术语表和类似信息的自动链接
• 分层结构 ：文档树的简单定义，自动链接到兄弟姐妹，父母和孩子
• 自动索引 ：通用索引以及模块索引
• 代码处理 ：使用Pygments荧光笔自动突出显示
• 扩展 ：自动testing代码片段，包含来自Python模块的文档string等等

Answer 5

最后，你只有两个select：

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

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

2. Sphinx ：用于loggingPython项目的实际工具。 这里有三个选项：手动，半自动（存根生成）和全自动（Doxygen like）。

   1. 对于手动API文档，您有Sphinx autodoc 。 用embedded式API生成的元素编写用户指南是非常好的。
   2. 对于半自动你有狮身人面像自动摘要 。 你可以设置你的autosummary_generate系统来调用sphinx-autogen或者用autosummary_generateconfiguration来设置你的Sphinx。 您将需要设置自动存档页面，然后手动编辑页面。 你有select，但是我对这种方法的经验是，它需要太多的configuration，甚至在创build新的模板之后，我发现了错误和不可能确切地确定公开的API是什么，什么不是。 我的意见是这个工具是很好的存根生成，这将需要手动编辑，仅此而已。 就像是手动结束的捷径。
   3. 全自动。 这已经被批评了很多次，并且长久以来，我们没有一个与Sphinx集成的好的全自动Python API生成器，直到AutoAPI出现，这是一个新的孩子。 这是Python中自动生成API的最好方式（注意：无耻的自我推销）。

还有其他选项需要注意：

• 呼吸 ：这是一个非常好的主意，当您使用Doxygen的其他语言的几个相关项目工作时，这是非常有意义的。 这个想法是使用Doxygen的XML输出，并将其提供给Sphinx来生成您的API。 所以，你可以保留Doxygen的所有善良，并统一狮身人面像的文件系统。 理论上真棒。 现在，实际上，我上次检查项目还没有准备好生产。
• pydoctor *：非常特别。 生成自己的输出。 它与Sphinx有一些基本的整合，还有一些不错的function。