Documenting Python with NaturalDocs

Question

I am curious about NaturalDocs, and want to autodocument some Python files. The files are documented using docstrings. The files are parsed perfectly using epydoc.

The sample file (/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)

I've tried:

$ 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.

But got empty results (html directory only has some .js files).

Is there a way to tell NaturalDocs to document my Python files without rewriting all comments?

sth · Accepted Answer · 2012-02-26 18:41:28Z

5

It appears that NaturalDocs supports single line comments only in Python sources by default (lines prefixed by #).

If you don't want to rewrite your comments you can configure NaturalDocs to accept block comments that look like your example. You start with """/* and end with */""". Add the following line to the section Language: Python in Config/Languages.txt:

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

edited Feb 26, 2012 at 18:41

sth

231k56 gold badges288 silver badges370 bronze badges

answered Feb 26, 2012 at 9:45

Ferdinand Prantl

5,8171 gold badge38 silver badges37 bronze badges

Sign up to request clarification or add additional context in comments.

Comments

djperalta · Accepted Answer · 2017-04-23 15:19:24Z

Show example comments in python for generate Naturaldosc. The sample file (/tmp/example/example_naturaldocs.py): Comand generate docs file.

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

Link example 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

Out:

https://dperaltab.github.io/naturaldocs

python naturaldocs pythonaturaldocs

Collectives™ on Stack Overflow

Documenting Python with NaturalDocs

2 Answers 2

Comments

Comments

Your Answer

Hot Network Questions

Collectives™ on Stack Overflow

2 Answers 2

Comments

Comments

Your Answer

Sign up or log in

Post as a guest

Related