[Zope-Annce] ANN: HappyDoc 0.7.1
Sun, 10 Sep 2000 10:04:01 -0400
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.7.1 contains several fixes for reported bugs. Special
thanks to Jesper Hertel and many others for reporting them so
quickly and clearly.
With this update, I have also updated the Zope source documentation
files on Zope.org at http://www.zope.org/Members/hellmann/ZopeSrcDocs.
Download the latest version of HappyDoc from the home page on
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
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
"Using __doc__ strings overrides comment documentation."
def method1(self, params):
"This method uses a __doc__ string."
# Method2 does not use a __doc__ string.
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."