Announcing HappyDoc, a Python 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.

Version 0.6

Version 0.6 is the first public release. It is described completely on the home page (see just below). It isn't ready for a 1.0 release number yet because I want to add a few more core features before getting to that point. It is stable, however, and is somewhere between a beta and full-release level.

Download

Download the latest version of HappyDoc from the home page on SourceForge:

 http://sourceforge.net/projects/happydoc

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

Feedback on HappyDoc is welcome to doughellmann@bigfoot.com.

Doug Hellmann