Документирование Python с помощью NaturalDocs

Question

Документирование Python с помощью NaturalDocs

1

Мне интересно, 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 без переписывания всех комментариев?

Adam Matan 03 март 2011, в 10:40

Источник

Теги:

python

2 ответа

0

Показать пример комментариев в python для генерации Naturaldosc. Файл образца (/tmp/example/example_naturaldocs.py): Comand сгенерирует файл документов.

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

Из:

https://dperaltab.github.io/naturaldocs

python naturaldocs pythonaturaldocs

djperalta 23 апр. 2017, в 12:58

Ещё вопросы

Ferdinand Prantl · Accepted Answer · 2012-02-26T08-44-00.000Z

Похоже, что NaturalDocs поддерживает однострочные комментарии только в источниках Python по умолчанию (строки с префиксом #).

Если вы не хотите переписывать свои комментарии, вы можете настроить NaturalDocs на принятие комментариев блоков, которые выглядят как ваш пример. Вы начинаете с """/* и заканчиваете на */""". Добавьте следующую строку в раздел Language: Python в Config/Languages.txt:

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