如何使用 doxygen 记录 Python 代码 [关闭]
-
09-06-2019 - |
题
我喜欢 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 生成的最佳方式(注意:无耻的自我推销)。
还有其他选项需要注意: