如何使用 doxygen 记录 Python 代码 [关闭]
https://stackoverflow.com/questions/58622
-
09-06-2019 - |
italiano
english
français
española
中国
日本の
العربية
Deutsch
한국어
Português
Russian题
我喜欢 doxygen 来创建 C 或 PHP 代码的文档。我有一个即将到来的 Python 项目，我想我记得 Python 没有 /* .. */ 注释，并且还有自己的自我文档工具，这似乎是Python式的文档方式。
既然我熟悉 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 可以检测到 ## 块或“””块中的注释，大部分工作就会完成，您就可以使用其中的特殊命令无论哪种情况。也许他们希望使用“””的人遵守更多Pythonic文档实践，这会干扰特殊的doxygen命令？
其他提示
这 多西比 输入过滤器允许您以标准 Python 文档字符串格式使用几乎所有 Doxygen 格式标记。我用它来记录一个大型混合 C++ 和 Python 游戏应用程序框架，并且运行良好。
最后，你只有两个选择：
您可以使用 Doxygen 生成内容，或者使用 Sphinx* 生成内容。
强力氧:它不是大多数 Python 项目的首选工具。但如果您必须处理用 C 或 C++ 编写的其他相关项目，那么它可能是有意义的。为此，您可以使用以下方法改进 Doxygen 和 Python 之间的集成 多西比比.
狮身人面像:用于记录 Python 项目的事实上的工具。您在这里有三个选择：手动、半自动（存根生成）和全自动（类似 Doxygen）。
- 对于手动 API 文档，您可以使用 Sphinx 自动文档. 。编写包含嵌入式 API 生成元素的用户指南非常有用。
- 对于半自动，你有 Sphinx 自动摘要. 。您可以设置构建系统来调用 sphinx-autogen 或使用以下命令设置 Sphinx
autosummary_generate配置。您将需要设置带有自动摘要的页面，然后手动编辑页面。你有选择，但我对这种方法的经验是，它需要太多的配置，最后即使在创建新模板之后，我也发现了错误，并且无法准确确定哪些内容公开为公共 API，哪些内容不公开。我的观点是，这个工具非常适合需要手动编辑的存根生成，仅此而已。就像最终进入手册的快捷方式一样。 - 全自动。这已经被批评了很多次，而且很长一段时间我们都没有一个很好的与 Sphinx 集成的全自动 Python API 生成器，直到 自动API 来了，这是街区里的新孩子。这是迄今为止 Python 中自动 API 生成的最佳方式（注意：无耻的自我推销）。
还有其他选项需要注意：
