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）： Comand生成docs文件。

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

python naturaldocs pythonaturaldocs

使用NaturalDocs记录Python

2 个答案: