如何使用Doxygen记录Python代码

Question

我喜欢Doxygen创建C或PHP代码的文档。我有一个即将到来的Python项目，我想我还记得Python没有/* .. */评论，也有自己的自我文档编制功能，这似乎是pythonic的文档编制方式。

既然我熟悉Doxygen，如何使用它来生成我的Python文档？有什么特别需要我注意的吗？

Answer 1

这在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可以在##块或“”“块中检测到注释时，大部分工作就可以完成，并且您可以在其中使用特殊命令也许他们希望使用“”“的人遵守更多的Python文档实践，而这会干扰特殊的doxygen命令？