| HappyDoc Source Documentation | |
|---|---|
HappyDoc Documentation Extraction ToolHappyDoc 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. DownloadDownload the latest version of HappyDoc from SourceForge . Thanks to <A href="http://sourceforge.net"> <IMG src="http://sourceforge.net/sflogo.php?group_id=9678" width="88" height="31" border="0" alt="SourceForge"></A> for hosting HappyDoc development. InstallationHappyDoc uses the Distutils package for installation. Unpack the tarball downloaded from SourceForge in a temporary directory. Then run:
% python ./setup.py install
to install the package in a central location. Alternatively,
HappyDoc can be run directly from its unpacked distribution archive.
Use this method if you do not have write access to the
For the Impatient After installation, the HappyDoc command-line application should
be in your path. Simply run General Information HappyDoc uses the Python parser to extract information from
To use HappyDoc, simply run it against your source files or
directory. Use the Controlling the OutputHappyDoc uses two different pluggable classes for controlling output. A formatter class is responsible for producing the syntax of the actual output (e.g. HTML, XML, SGML, or PDF). A docset class is responsible for controlling the formatter and managing the logical flow of the information (e.g., writing to multiple files or a single file, putting class documentation in a different file from the module, etc.). Formatters and DocSets should be implemented so that any two can be combined. It will not always be desirable to do this, but it should be possible. Documentation not in Doc-strings It is not always desirable to put all documentation in Comment documentation can contain all of the same formatting as
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 Flexible BehaviorHappyDoc provides several different abstractions to allow the same engine to process different types of inputs and convert them to different types of output. Docstring ConvertersHow does an author write documentation so that it will be marked up and look fancy? This is a perennial question for Python users, and seems to have introduced a roadblock into the development of more robust and useful documentation tools. HappyDoc stands firmly on the fence and does not attempt to resolve the issue. Refer to the FormattersFormatters are responsible for tranlating the higher level docset concepts into specific structures for an output type. For example, the specific way a descriptive list might be rendered in HTML could vary between different HTML formatters. The API for a formatter depends on the docset types which is is meant to support. Refer to the DocSet typesThe docset, or documentation set, defines the structure of the collected documentation being generated. All aspects of the structure are left up to the docset. Whether to use multiple or a single file, a file or a database, and what specific metadata to include in the output is left up to the docset. The docset drives the documentation generation using controls available from the formatter. Refer to the Using HappyDocCommand Line Options HappyDoc uses standard Parser, DocSet and Formatter ParametersMany DocSets and Formatters will take parameters. The Parser also accepts global options using this method (see below for another way to control the parser). To pass parameters past the command line argument processing of HappyDoc and in to the Parser, DocSet or Formatter being used, the variable is passed as an argument rather than option (no dashes) to HappyDoc. To allow the Parser, DocSets and Formatters to share variable
namespace, the options passed are prefixed with a value indicating
whether the variable is for the For example:
% ./happydoc -d MySources/doc MySources \
formatter_bgcolor1='#ffccaa'
Or on Windows:
> .\happydocwin.py -d MySources\doc MySources \
formatter_bgcolor1="#ffccaa"
Use the File-specific Parser Configuration ValuesParameters to the HappyDoc Parser can also be embedded within the first comment block of the module. The parameter values recognized and their meanings are listed below. To provide file-specific parser configuration settings, any Python code can be embedded in the comments of the file. For example:
#!/usr/bin/env python
#
# HappyDoc:# These variables should be discovered.
# HappyDoc:TestInt=1
# HappyDoc:TestString="String"
# HappyDoc:TestStringModule=string.strip(' this has spaces in front and back ')
# HappyDoc:url=urlencode({'a':'A', 'b':'B'})
# HappyDoc:docStringFormat='StructuredText'
All lines beginning with the pattern " Refer to the happydoclib.parseinfo module for more details. Input TypesHappyDoc accepts 3 basic input types for documentation.
Examples of HappyDoc DocumentationTwo example output documentation sets are available.
Who else is using HappyDoc?
BugsPlease use the bug tracker on the SourceForge project page for HappyDoc to report bugs and the feature tracker to request new features. SupportThere are also public forums and mailing lists available on SourceForge for questions regarding the use of HappyDoc, or plans for its future. |