HappyDoc Documentation Extraction Tool
HappyDoc is a tool for extracting documentation from Python source
code. It differs from other such applications by the fact that it
uses the parse tree for a module to derive the information used in
its output, rather that importing the module directly. This allows
the user to generate documentation for modules which need special
context to be imported.
Download
Download the latest version of
HappyDoc from
SourceForge .
Instructions
HappyDoc uses the Python parser to extract information from
__doc__ strings. It also examines the signatures of functions and
methods to include function prototypes in the output.
To use HappyDoc, simply run it against your source directory. Use
the -h or --help arguments to learn about the arguments and
options accepted. See below for more detailed directions about
configuring your source for documentation purposes.
Controlling the Output
HappyDoc uses two different pluggable classes for controlling
output. A formatter class is responsible for producing the
syntax of the actual output (e.g. HTML, XML, SGML, or PDF). A
docset class is responsible for controlling the formatter and
managing the logical flow of the information (e.g., writing to
multiple files or a single file, putting class documentation in a
different file from the module, etc.). Formatters and DocSets
should be implemented so that any two can be combined. It will
not always be desirable to do this, but it should be possible.
Doc-string Format
How does an author write documentation so that it will be marked
up and look fancy? This is a perennial question for
Python and seems to have introduced a
roadblock into the development of more robust and useful
documentation tools. By separating the formatter classes from the
docset classes, HappyDoc allows a user to create their own
formatter to interpret comments in any way they see fit.
The default for the HTMLTableFormatter (the default formatter
for HappyDoc) is to treat __doc__ strings as
StructuredText.
See also the StructuredText
module for a description of the
rules for using StructuredText.
Don't like StructuredText? Write your own formatter that does
something different and drop it into place.
Documentation not in Doc-strings
It is not always desirable to put all documentation in __doc__
strings. Sometime, notably when working with
Zope , special meaning is attached to the
presence of __doc__ strings. For this reason, and to support
existing code which might not have __doc__ strings, HappyDoc
will find and extract documentation in Python comments.
Comment documentation can contain all of the same formatting as
__doc__ strings. The preceding comment marker will be stripped
off and the lines will be assembled and treated as a block of
StructuredText.
To use this feature, it is important to place the comments
before the named object which they describe. In this example:
#
# Class documentation goes here
#
class ClassWithNoDocStrings:
"Using __doc__ strings overrides comment documentation."
def method1(self, params):
"This method uses a __doc__ string."
pass
#
# Method2 does not use a __doc__ string.
#
def method2(self):
pass
The output would include the __doc__ strings for the class and
for method1 . It would also make it appear that method2 had a
__doc__ string with the contents "Method2 does not use a
__doc__ string."
Formatters
- htmltable
The HTMLTableFormatter generates HTML output
using tables to arrange and align the text.
- text
The TextFormatter generates plain text output with
little reformatting of the input comments.
DocSet types
- file
The DocSet sends the output of the formatter to
multiple files. Each module and class is documented in its own
file. Functions are documented along with the module to which
they belong. Methods are documented with the class.
- single_file
The SingleFileDocSet sends the output of the
formatter to a single output file.
- stdout
The StdOutDocSet sends the output of the formatter
to stdout.
Using HappyDoc
Command Line Options
HappyDoc uses the
CommandLineApp
class to process command line arguments. To see the syntax help
for the command line program, use the -h or --help options.
The specific options supported are not documented here since they
might change.
DocSet and Formatter Parameters
Many DocSets and Formatters will take parameters. To pass
parameters past the command line argument processing of HappyDoc
and in to the DocSet or Formatter being used, the variable is
passed as an argument rather than option (no dashes) to HappyDoc.
To allow DocSets and Formatters to share variable namespace, the
options passed are prefixed with a value indicating whether the
variable is for the docset_ or formatter_ .
For example:
% ./happydoc.py -d MySources/doc MySources \
docset_title='The title' \
formatter_bgcolor1='#ffccaa'
Input Types
HappyDoc accepts 3 basic input types for documentation.
Any file name passed will be treated as a Python source file.
The file will be parsed (but not imported) and the
documentation text will be extracted from the resulting parse
tree.
Any directory passed will be interpreted to mean to document
all of the files in that directory, so HappyDoc will recurse
into the directory to find files.
A single, regular, text file can be passed as the "package
description file." This file, defaulting to README.txt , will
be interepreted as StructuredText and included in the place of
a doc string in the generated index.html file.
Examples
Two example output documentation sets are available.
HappyDoc
Of course HappyDoc is used to produce its own documentation. The
most current version is available on the
HappyDoc home page.
Zope
A set of
Zope source documentation
based on a recent CVS checkout available on Zope.org.
To Do
SourceForge setup
-
Features to be Implemented
- New Formatters
-
- New DocSets
-
DocBook (?)
PDF (?)
MIF (?)
- Changes to Output
-
Use pprint to format arguments to functions and methods. Use
a new class to represent argument default values. Support
__str__ and pprint methods.
Use StructuredTextNG instead of current version to achieve
better output.
Support LICENSE.txt, ANNOUNCE.txt and other StructuredText
files referenced from README.txt.
Support external files which do not have .txt extension.
Output a list of the inherited methods for a class as links to
their definition along with the base classes.
Recognize references to methods, classes, etc. within
__doc__ strings and make them links where possible or
otherwise highlighted when not.
Support variable substitution in the package description file.
Define some variables, and allow the user to pass in their own.
Per-directory README.txt detection. (Useful for Zope
products.) Where to include results?
Correctly recognize that two modules can define objects with
the same name, but those objects are different things. Use
the dotted path specified when something is reference to
determine the right object. Other ways?
Recognize CommandLineApp subclasses and generate the usage
help automatically. This will require changing the
CommandLineApp to support generating help without an
instance, and would require importing the module.
Use separate import lists for standard library and local
modules.
Add an index file with all objects listed in different ways.
Fix singlefile docset so that in HTML mode class names are
output. Is this problem part of the formatter?
- Distribution
-
Need better distribution tools.
Look into distutils?
Work on cvstagdiff.py to generate change reports for versions.
Add ZEO code to Zope CVS checkout.
- General
-
- Bugs
See the SourceForge project page.
Version History
- Version 0.7
-
Fix formatter or docset getting unrecognized named parameters.
Fix change detection with regression tests.
Moved the test code into a special subdirectory to clean up the
root area of the app.
Fix mkdir() method of HappyDoc to support win32
systems. The fix is based on a patch submitted by Jesper
Hertel .
Fix Bug Reported by Jesper Hertel: Default arguments of
negative numbers break.
For example:
def func(x=-1):
pass
Fix 113954 HTML encode function parameter values (and all
writeCode content for HTML formatter).
Changed exception list in HTML formatter so that it is output
as code.
Added some new methods to the text formatter to support
changes in how the exception list is now written.
- Version 0.6
First public release
Added regression test checks to Makefile. This makes it easy to
run a complete regression test and verify that the results are
correct.
Added checking of actual output files, not just stdout, to
regression test rules in Makefile.
Changed HTMLTable formatter so that it accepts an argument to
disable the timestamp feature. This is mostly useful for the
regression testing, but might also be desirable for some output
circumstances. The default is to leave the feature enabled.
Changed test framework to allow an output directory to be
specified on the command line.
Changed test framework to make creation of tests easier to
scale.
Verified support passing arguments to formatters from the
command line.
- Version 0.5
Moved code to SourceForge.
- Version 0.4
Import, testing, and formatter changes.
Handles imported names in the from X import Y style import
statements. Makes them links where possible.
Improved unit test framework (requires
PyUnit ).
Fixed some problems with the formatter_textfile.py module which
caused it to generate spurrious content.
- Version 0.3
Allow lists to have multiple columns.
- Version 0.2.1
Fixed a problem with references between modules and
back to the root level toc file in the HTML Table formatter. Also
changed happydoc.py to use the CVS variable Name to determine its
version.
- Version 0.2
Created dynamic plugin loader class to manage docset
and formatter pluggins. See pluginloader.py.
- Version 0.1.1
Minor improvements on 0.1, mostly in the
htmltable formatter.
- Version 0.1
Initial private release given to a few people to beta
test.
Known Bugs
-
Modules
|
|
HappyDoc-r0_7_1/
CommandLineApp | Base class for building command line applications.
|
MML | $Id: MML.py,v 1.1.1.1 2000/08/21 11:48:45 doughellmann Exp $'''
|
StructuredText | Structured Text Manipulation
|
cvsversion | Get the CVS version information based on the $Name: r0_7_1 $ token.
|
emptytest | Empty test file. No classes or functions defined.
|
__init__ | Formatter collection initialization module.
|
happydoc | Documentation generator.
|
happydoc_class | HappyDoc Class for HappyDoc Application.
|
happyformatter | Base class for formatting info generated by parseinfo classes.
|
indentstring | Function to indent the lines of a string using a standard indent spacing.
|
parseinfo | Extract information from a Python code parse tree.
|
pluginloader | Define a class to handle pluggable module loading.
|
prettyast | Pretty print the AST for a .py file."
|
test_happydoc | Unit test cases for HappyDoc.
|
ts_regex | Provide a thread-safe interface to regex
|
HappyDoc-r0_7_1/TestCases/
HappyDoc-r0_7_1/docset/
HappyDoc-r0_7_1/formatter/
|
|