如何使用Doxygen记录Python代码 [英] How to document Python code using Doxygen

问题描述

我喜欢Doxygen创建C或PHP代码的文档。我有一个即将到来的Python项目，我想我还记得Python没有 / * .. * / 注释，并且也有自己的自我文档工具，

I like Doxygen to create documentation of C or PHP code. I have an upcoming Python project and I think I remember that Python doesn't have /* .. */ comments, and also has its own self-documentation facility which seems to be the pythonic way to document.

由于我熟悉Doxygen，如何使用它来生成Python文档？

Since I'm familiar with Doxygen, how can I use it to produce my Python documentation? Is there anything in particular that I need to be aware of?

推荐答案

这是记录在doxygen网站上，但此处总结如下：

This is documented on the doxygen website, but to summarize here:

您可以使用doxygen来记录您的Python代码。您可以使用Python文档字符串语法：

You can use doxygen to document your Python code. You can either use the Python documentation string syntax:

"""@package docstring
Documentation for this module.

More details.
"""

def func():
    """Documentation for a function.

    More details.
    """
    pass

在这种情况下，注释将被doxygen提取，但您将无法使用任何特殊的doxygen命令。

In which case the comments will be extracted by doxygen, but you won't be able to use any of the special doxygen commands.

或者，您可以（类似于doxygen下的C风格语言）将注释标记加倍（＃）成员之前的第一行：

Or you can (similar to C-style languages under doxygen) double up the comment marker (#) on the first line before the member:

## @package pyexample
#  Documentation for this module.
#
#  More details.

## Documentation for a function.
#
#  More details.
def func():
    pass

在这种情况下，您可以使用特殊的doxygen命令。没有特殊的Python输出模式，但是您可以通过将 OPTMIZE_OUTPUT_JAVA 设置为 YES 来改善结果。

In that case, you can use the special doxygen commands. There's no particular Python output mode, but you can apparently improve the results by setting OPTMIZE_OUTPUT_JAVA to YES.

老实说，我对两者之间的差异感到有些惊讶-似乎一旦doxygen可以检测到##块或块中的注释，大部分工作就会完成，并且无论哪种情况，您都可以使用特殊命令。也许他们希望使用的人遵守更多的Python文档实践，而这会干扰特殊的doxygen命令？

Honestly, I'm a little surprised at the difference - it seems like once doxygen can detect the comments in ## blocks or """ blocks, most of the work would be done and you'd be able to use the special commands in either case. Maybe they expect people using """ to adhere to more Pythonic documentation practices and that would interfere with the special doxygen commands?

这篇关于如何使用Doxygen记录Python代码的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！