[ANN] HappyDoc 1.4 released

[Doug Hellmann]

Announcing the latest version of 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 1.4 -- 

      - Handle Packages separately from Modules.  This behavior is
        optional and consists mostly of creating intermediate level
        TOC pages and not showing subdirectories of a Package on the
        Package's parent TOC page.

      - Changed default title to include instructions about how to
        change the title

      - Show exceptions in plugins when there is a problem loading a
        module

      - Added a command line argument to support ignoring specific
        subdirectories.

      - Fixed problem with ignoring directories by correcting name
        comparison logic.

      - Change "link":URL style references which were HTML
        quoted back to StructuredText so that hyperlinks can be embedded
        within docstrings. (reported by Mihalopoulos Evangelos)

      - Changed base class arrangement for docset so the basic interface
        is documented as part of the docset base class.

      - Moved some formatter functions into the docset, since they match
        that API better and more properly belong there.

      - Fixed bug 131751, problem with string dereference in
parseinfo.py

      - Set the DOCTYPE in hdformatter_htmlfile.py.  (Thanks to
        Shannon -jj Behrens for the patch.)

      - Fixed problem with references to extra files when using output
        prefixes.

      - Changed test harness to use the HappyDoc class directly instead
        of calling out to a separate program.

      - Output a oneliner for referenced pre-formatted documents.

      - Modified parseinfo.py to improve speed

      - Expanded information extracted about exceptions thrown by
        functions

      - Simplified the regressino test to make it faster by removing
        Zope docs from the default regression test suite

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