我喜欢doxygen来创建C或PHP代码的文档.我有一个即将推出的Python项目,我想我记得Python没有/ * .. * / comments,并且还有自己的自我文档工具,这似乎是pythonic的文档方式.

由于我熟悉doxygen,我如何使用它来生成我的Python文档？有什么特别需要注意的吗？

解决方法:

这是documented on the doxygen website,但总结一下：

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

"""@package docstring
Documentation for this module.

More details.
"""

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

    More details.
    """
    pass

在这种情况下,注释将由doxygen提取,但您将无法使用任何special doxygen commands.

或者你可以(在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命令？