用NaturalDocs记录Python
问题描述:
我很好奇NaturalDocs,并且想要自动文档化一些Python文件。这些文件使用docstrings进行记录。这些文件使用epydoc完美解析。用NaturalDocs记录Python
示例文件(/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文件而不用重写所有注释?
答
似乎NaturalDocs默认支持单行注释(仅在Python源代码中有#
前缀)。
如果你不想重写你的评论,你可以配置NaturalDocs接受块看起来像你的例子。您从"""/*
开始,并以*/"""
结束。以下行添加到部分Language: Python
在Config/Languages.txt
:
Block Comment: """/* */"""
答
显示例如评论的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 protected]
#
# Some text after the bullet list.
#
# Returns:
# [Tuple]
#
# : a = b + c;
def test_test_03():
pass
输出: