B.2 Tools for Documenting Python Software
B.2.2 Tools for Automatic Documentation
HappyDoc. The HappyDoc tool extracts class and function declarations, with their doc strings, and formats the information in HTML or XML. To allow for some structure in the text, like paragraphs, ordered/unordered lists, code segments, emphasized text, etc., HappyDoc makes use ofStructuredText, which is an almost implicit way of tagging ASCII text to impose a structure of the text.
The StructuredText format is defined in the StructuredText.py file that comes with the HappyDoc source. The format is gaining increased popularity in the Python community. Some of the most basic formatting rules are listed below.
– Paragraphs are separated by blank lines.
– Items in a list start with an asterix*, and items are separated by blank lines. Bullet list, enumerated lists, and descriptive lists are supported, as well as nested lists.
– Code segments in running text are written inside single quotes, for in- stance, ’s = sin(r)’, which will then be typeset in a fixed-width font (typically as s = sin(r)). Larger parts of code, to be typeset “as is” in a fixed-width font, can appear as a separate paragraph, if the preceding paragraph ends with the words “example” or “examples”, or a double colon.
– Text enclosed in asterix, like*emphasize*, isemphasized.
HappyDoc generates an overview of classes and functions in a module or collection of modules. Each function or class is presented with their doc strings. Using the StructuredText format intelligently in doc strings makes it quite easy to quickly generate nice online documentation of your Python codes. The filesrc/misc/docex_happydoc.pycontains an example of how a sim- ple Python file can be documented with HappyDoc and the StructuredText format. The reader is encouraged to read this file as it contains demonstra- tions of many of the most widely used StructuredText constructs. Provided HappyDoc is installed at your system, simply run
happydoc docex_happydoc.py
B.2. Tools for Documenting Python Software 699 to produce a subdirectory doc with HTML files for documentation of the moduledocex_happydoc. Spending five minutes on thedocex_happydoc.py ex- ample is probably sufficient to get you started with applying HappyDoc and StructuredText to your own Python files.
We refer to StructuredText.py for more detailed information about the StructuredText format. A comprehensive example of using the format is the README.txt file in the HappyDoc source distribution, especially when you compare this text file with the corresponding HTML file generated by Hap- pyDoc3.
Epydoc. A recent development, Epydoc, shows quite some similarities with HappyDoc. Epydoc produces nicely formatted HTML or (LATEX-based) PDF output both for pure Python modules and extension modules written in C, C++, or Fortran. Documentation of the sample module docex_epydoc.py in src/misc can be automatically generated by
epydoc --html -o tmp -n ’My First Epydoc Test’ docex_epydoc.py The generated HTML files are stored in the subdirectory tmp. To see the result, loadtmp/index.htmlinto a web browser. Figure B.1 displays a snapshot of the first page.
Fig. B.1.Snapshot of HTML documentation automatically generated by Epydoc.
3 Just runhappydoc README.txt and view the generated HTML documentation filedoc/index.htmlin a web browser.
The documentation is organized in layers with increasing amount of de- tails. From a table of contents on the left you can navigate between packages and modules. For each module you can see an overview of functions and classes, and follow links to more detailed information. Modules and classes are accompanied by doc strings, while functions and class methods are listed with the associated argument list and the doc string.
Epydoc can also generate PDF or pure LATEX source, just replace the --html option to epydoc by--pdf or --latex. I prefer making LATEX source and adjusting this source, if necessary, before producing the final PostScript or PDF document. Links in the HTML documentation are reflected as links in the PDF file as well.
Epydoc has its own light-weight markup language, called Epytext, for formatting doc strings. This language is quite similar to StructuredText, but Epytext has more visible tagging. To exemplify Epytext we look at a sample function:
def func1(self, a, b, c):
"""
Demonstrate how to document a function using doc strings and Epytext formatting.
@param a: first parameter.
@type a: float or int
@param b: second parameter.
@type b: arbitrary
@param c: third parameter.
@type c: arbitrary
@return: a list of the three input parameteres C{[2*a,b,c]}.
X{Bullet lists} start with dash (-) and are indented:
- a is the first parameter
- b is the second parameter. An item can occupy multiple lines
- c is the third parameter
"""
return [2*a, b, c]
Paragraphs are separated by blank lines. In running text we can emphasize words, use boldface or typewriter font, via special tags:
I{some text typeset in italic}
B{some boldface text}
C{source code typeset in fixed-width typewriter style}
M{a mathematical expression}
Words to enter an index of the documentation can be marked by theX tag as shown above with “Bullet lists”. Code segments are typeset in fixed-width typewriter style if the preceding sentence ends with a double colon and the code text is indented.
A special feature of Epytext is the notion offields. Fields can be used to document input parameters and return values. A field starts with@followed
B.2. Tools for Documenting Python Software 701 by a field name, like param for parameter in argument lists, and then an optional field argument, typically the name of a variable. Fields are nicely formatted by Epydoc and constitute one of the package’s most attractive features.
The documentation of Epydoc is comprehensive and comes with the source code. You should definitely read it and try Epydoc out before you make any decision on what type of tool to use for documenting your Python code. In my view, the advantage of Epydoc is the layout and quality of the automatically generated files. The downside is that much of the nice functionality in Epy- doc requires explicit tagging of the text in doc strings. This is not attractive if you want to read the source as is or process it with other documentation tools such as HappyDoc and Pydoc.
Pydoc. The Pydoc tool comes with the basic Python distribution and is used to produce man pages in HTML or Unix nroff format from doc strings.
Suppose you have a piece of Python code in a filemod.py. Writing pydoc -w ./mod.py
results in a filemod.htmlcontaining the man page in HTML format. Omitting the-wmakespydocgenerate and show a Unix-style man page.
Writingpydoc modprints out a documentation of the modulemod. Try, for instance, to write out the documentation of the numpyutils module in the scitools package:
pydoc scitools.numpyutils
You can also look up individual functions, e.g., pydoc scitools.numpyutils.seq
As long as the module is found in any of the directories in sys.path, Pydoc will extract the structure of the code, its embedded documentation, and print the information.
A reason for the widespread use of Pydoc is probably that it does not enable or require special formatting tags in the doc strings. Any Python code with doc strings is immediately ready for processing. On the other hand, the lack of more sophisticated formatting of the doc string text is also reason to explore tools like HappyDoc and Epydoc.
Documentation of Pydoc can be found by following thepydoclinks in the index of the Python Library Reference.
Docutils. Docutils is a further development of structured text (into what is called the reStructuredText format) and parsing of doc strings to form the next generation tool for producing various type of documentation (source code, tutorials, manuals, etc.). Seedoc.htmlfor a link to further information.