用NaturalDocs文档记录Python

Question

我对NaturalDocs很感兴趣，想要自动生成一些Python文件的文档。这些文件是通过文档字符串来进行说明的。使用epydoc解析这些文件时效果很好。

这是一个示例文件（/tmp/test/test.py）：

def m(a, b):
   """/*
      Function: m     
      Multiplies two integers.
   
      Parameters:
         a - The first integer.
         b - The second integer.
   
      Returns:
         The two integers multiplied together.
   */"""
   print a*b
   return a*b   
m(3,5)

我尝试过：

$ mkdir nd
$ mkdir html
$ naturaldocs -i /tmp/test -o HTML html -p nd
Finding files and detecting changes...
Parsing 1 file...
Updating menu...
Updating CSS file...
Done.

但是得到的结果是空的（html目录里只有一些.js文件）。

有没有办法让NaturalDocs为我的Python文件生成文档，而不需要重写所有的注释呢？

Answer 1

这里有一个关于如何在Python中生成自然文档的示例评论。示例文件的位置是(/tmp/example/example_naturaldocs.py)：这个命令可以用来生成文档文件。

naturaldocs $ perl NaturalDocs -i /tmp/example/ -o HTML /home/($USER)/naturaldocs/docs -p /tmp/natural_docs

你可以查看这个示例的链接：https://gist.github.com/dperaltab/67a5551b0b1374abeb957c46e029894a

# -*- coding: utf-8 -*-

# Variable: var_name
# Describe variable.
var_name = True


# Class: MyClass
# Describe the class here.
#
# Attributes:
#    attr1 - First attribute of the class
#    attr2 - Second one
class MyClass(models.Model):
    attr1 = []
    attr2 = ""
    # Constructor: __init__
    # Describe the constructor.
    #
    # Parameters:
    #   arg1 - The first argument.
    def __init__(self, arg1):
        self.attr1 = arg1
        self.attr2 = "attr2"

    # Method: method1
    # Describe the method here.
    #
    # Parameters:
    #   arg1 - The first argument.
    #   arg2 - The second argument.
    def method1(self, arg1, arg2):
        # Variable: var_name_02
        # Describe variable.
        #
        # Returns:
        # True
        var_name_02 = ""
        pass


# Function: test_test
# Description
#
# Returns:
# List
def test_test():
    pass

# Function: test_test_02
# describe
# - Bullet one.
# - Bullet two.
#  Bullet two continued.
# - Bullet three.
#
# Some text after the bullet list.
#
# Returns:
# [Tuple]
#
# See Also:
# <MyClass>
def test_test_02():
    pass

# Function: test_test_03
# describe
# *Bold text*
#
# _Underlined text_
#
# Paragraphs are broken by skipping lines.  So the two
# lines above each have their own paragraph, but these
# three lines are all part of the same one.
# (start code)
# 
# if (x == 0) {
#    DoSomething();
# }
# 
# return x;
# 
# (end)
#
# : a = b + c;
#
# >   +-----+     +-----+
# >   |  A  | --> |  B  |
# >   +-----+     +-----+
# >                  |
# >               +-----+
# >               |  C  |
# >               +-----+
#
# Visit <http://www.website.com> or send messages to
# email@address.com.
#
# Some text after the bullet list.
#
# Returns:
# [Tuple]
#
# : a = b + c;
def test_test_03():
    pass

输出结果：

你可以访问这个链接查看结果：https://dperaltab.github.io/naturaldocs

相关标签有：pythonnaturaldocspythonaturaldocs

Answer 2

看起来，NaturalDocs 默认只支持 Python 源代码中的单行注释，也就是以 # 开头的那种注释。

如果你不想重新写你的注释，可以设置 NaturalDocs 让它接受像你例子中的那种块注释。你可以用 """/* 开始，用 */""" 结束。在 Config/Languages.txt 文件中 Language: Python 这一部分添加以下内容：

Block Comment: """/* */"""