用NaturalDocs记录Python

Question

我很好奇NaturalDocs，并且想要自动文档化一些Python文件。这些文件使用docstrings进行记录。这些文件使用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

似乎NaturalDocs默认支持单行注释（仅在Python源代码中有#前缀）。

如果你不想重写你的评论，你可以配置NaturalDocs接受块看起来像你的例子。您从"""/*开始，并以*/"""结束。以下行添加到部分Language: Python在Config/Languages.txt：

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

Answer 2

显示例如评论的Python为产生Naturaldosc。示例文件（/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