HappyDoc Change History

Version 2.1

The primary reason for this release is to resolve the infamous -d bug.

• New Features

  • #514237 - The PluginLoader no longer requires a .py extension on plugins. This should allow plugins to be written in any language for which Python can load a module, and as long as the file is named with the right convention they will be picked up and loaded. (The source of this change request was the maintainers of the PLD Linux Distribution.)

• Bug Fixes

  • Resolved defect #513850, where output was written to the wrong place when the -d option was used.

    NOTE The solution to this problem resulted in changes to the file names being used for output. It is recommended that a new directory be used to generate documentation for existing code, rather than trying to write over the top of existing files.

  • Resolved defect #510447, a problem with escaping special characters in HTML output. Text enclosed in single quotes is now not escaped in output so that HTML text can be passed directly to the output file.

  • Fixed a problem with Windows installation using setup.py.

• Other Changes

  • Minor tweaks to the build and test tools.

Version 2.0.1

• New Features

  • Added limited support for CGI programs by expanding the docset processing to look for files ending in .cgi as well as .py.

• Bug Fixes

  • Resolved defect #505456 and 498204, a problem with happydocwin.py that prevented it from working properly on Win32 systems.

  • Resolved defect #501240 so that path handling under Win32 systems works properly and HappyDoc can generate output.

  • Resolved defect #505188 so that using the -o option will properly send output to stdout.

• Other Changes

  • Added more unit tests for formatters, especially fileformatterbase.py and formatter_HTMLFile.py.

  • Updated the StructuredTextNG docstring converter so that if an exception is generated during parsing of the ST, we fall back to ClassicStructuredText. The two syntaxes appear to be incompatible, and this should protect backwards compatibility for most users.

Version 2.0

• New Features

  • Rearranged much of the code base to create happydoclib package. This package protects the namespace for HappyDoc related code, and makes it easier to reuse HappyDoc components in other projects.

  • Package descriptions can now come from the docstring of the __init__.py module, instead of always having to be in a README file.

• Bug Fixes

  • Resolved bug #478659 so that import statements with comments following on the same line are picked up.

  • Fixed a problem with the HTMLTable formatter that caused pages to look odd in browsers which don't handle width attributes the same way as Netscape.

  • Upgraded to newer version of StructuredText package from Zope CVS, resolving several rendering issues for the HTML formatter.

• Other Changes

  • Changed command line argument handling to use - character in names in addtition to underscore. That is, defining an optionHandler_long_opt will allow the app to accept --long-opt or --long_opt. The help text uses the - form, but both are allowed on the command line for backwards compatability.

  • Updated test cases to streamline regression testing.

  • Rearranged some of the documentation from the root README.txt into sub-packages.

Version 1.6

• New Features

  • Implemented a variety of modifications to support Python 2.0 syntax updates.

  • Implemented plug-in system for docstring converters to allow module authors to write documentation using different markup styles. External files are recognized by their extension. The global default setting for docstrings can be passed on the command line, or a file-specific setting can be embedded in the input file (see below).

  • Updated the default markup syntax to StructuredTextNG, replacing the original StructuredText. Most users will not notice any difference.

    If the old StructuredText rules are desired, add a line to the first comment block in the module with these contents:

                # HappyDoc:docStringFormat="ClassicStructuredText"
    

  • Added parser argument handling to match that of docsets and formatters.

  • Implemented a system to allow file-specific parser control variables to be embedded in the input source files.

  • Made the parser function an attribute of HappyDoc application instance (parser_function) so subclasses can override it.

• Many contributed patches

  • Patch #403039 from Rob W.W. Hooft (hooft) to allow better support for Python 2.x import statement syntax changes.

  • Patch #403790 from an unknown contributor to allow the base URL for documentation of Python standard libraries to be passed as a command line argument to HappyDoc.

  • Patch #413416 from Rob W.W. Hooft (hooft) to eliminate invalid links to private classes which are not described.

  • Patch #445846 from Jörg Henrichs (jhenrichs) to elminate "decoration" lines in comment documentation. Now comment lines consisting solely of the characters '#', -, and = (possibly combined with whitespace) are ignored when extracting documentation from comments in a source file.

  • Added output formatter and docset for creating UML diagrams in Dia format. Thanks to Jörg Henrichs (jhenrichs) for the patches!

• Several resolved bugs

  • Resolved defect #434946 so that files with DOS line endings are handled properly.

  • Resolved defect #442811, reported by Jason R. Mastaler (jasonrm), in which the use of the old regex module by the StructuredText parser generated deprecation warnings.

  • Resolved defect #429308 from an unknown user in which less than and greater than symbols in preformatted (example) sections of text were rendered incorrectly.

• Other Changes

  • Cosmetic changes to the way unit tests are run.

  • Fixed a problem with identifying "system modules" under versions of Python other than 1.5.

  • Sort the table of contents by the module name, not the file name. These can be different, and sorting this way mixes packages and modules together so that it is easier to find the desired documentation.

Version 1.5

• Changed handling of parser.ParserError exceptions so they are converted to SyntaxErrors. This allows HappyDoc to show the file and line which caused the problem. Files with parse errors will be skipped with an error message.

• Made a few Windows-related changes to the README file.

• Corrected defect 428844 so that documentation in comments is associated with the appropriate object. The symptom of the corrected defect was if a single module had 2 classes with methods of the same name, and both were documented using comments, HappyDoc associated the last comment found with both methods.

Version 1.4.1

• If no input files are specified, a help message and error message are displayed.

• Added happydocwin.py as a command line script for Windows.

• Added formatter option to allow user to override the Python libdoc directory.

• Changed attribution note at bottom of HTML pages to be in a smaller font.

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, mihalop@yahoo.com)

• 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, jjinux@yahoo.com 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

Version 1.3

• Fixed problem with relative URL references in HTML output.

Version 1.2

• ( packaging errors )

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

Version 1.0

• This version was not actually released.

• 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 parameter info to the output.

• Formatter option to disable html quoting of docstring text.

Version 0.9.3

• Fixed the single file docset so that HTML and text mode works.

Version 0.9.2

• Fixed a problem with the import statement handler. Also changed HTML formatter output for import statements to include keywords in bold.

Version 0.9.1

• Minor packaging changes.

Version 0.9

• Patch 101758 - (From mikem42) Added a new command line argument --no_comments to tell the parser to ignore comments when looking for documentation text.

• Patch 103017 - (From hooft) Fixed --no_private_names so that names beginning with two _ are displayed even when private names are not.

• Bug126855 - (From hooft) Improvements to expression handling for argument defaults.

• Bug126187 - (From hooft) Fixed up the way import statements are handled so that information is not lost.

• Bug114517 - Corrected a problem with extracting the one line summary of some docstrings.

• Renamed the formatter directory and contents to avoid clashing with the standard Python module formatter.py.

• Now supports installation via distutils.

Version 0.8

• Patch 101602 - Closing class output files in multi-file docsets. This should remove the "too many open files" errors that several users reported on some platforms.

• Passing "-" to the -p option now disables the package description file handling.

• Updated the location of the source documentation files on Zope.org.

• Bug115451 fixed so that only the correct comments are output.

• Added new option --no_private_names which hides names beginning with _, thus resolving feature request 114877.

• Bug114872 fixed so that using raise with no arguments is ignored.

Version 0.7.1

• Fix 113738 - Keeping up with all of the open file handles in order to know the relative path to the "first" root file causes some systems to run out of open file handles. This change fixes the problem by only remembering the first file opened.

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 (JH@CDDK.DK).

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

• Minor changes to functionality

• Rearranged Makefile and some other files to make them SourceForge-friendly.

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.