[Application] HappyDoc 1.1

[Doug Hellmann]

                              HappyDoc 1.1                              
                              ------------                              

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 1.1 - Enhanced boolean command line switch handling to support
values like 'yes', 'no', 'on', 'off', 'true', and 'false'. - Added an
initial DocBook formatter implementation from Balazs Scheidler <bazsi@balabit.hu>.
- Per-directory README.txt detection. (Useful for Zope products and
Python packages.) - Support LICENSE.txt, CHANGES.txt, ANNOUNCE.txt and
other StructuredText files referenced from README.txt. Support external
files which do not have .txt extension. - Now installs using distutils.
- Include code related to Patch 103054 to fix problems with tables in
HTML and to make the HTML output smaller by reducing extra whitespace. -
Cleaned up some progress reporting output. - Added option to docset to
set a prefix to every file or directory created as output. This is
important for creating output with safe names in case module names end
up being parsed to something which does not make a valid filename. It
can also be useful when storing output in a web application server such
as Zope, where some names might be reserved. - Added docset and
formatter parmeter info to the output. - Formatter option to disable
html quoting of docstring text. 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."

       URL:  http://happydoc.sourceforge.net

   License:  Python Style

  Categories:  Python Utilities

Doug Hellmann (doughellmann@bigfoot.com)

--
<a href="http://happydoc.sourceforge.net">HappyDoc 1.1</a> -- Python
documentation extraction tool.