1. GANGA Release Strategy Documentation Tools GANGA Workshop, 20-22 April 2004, CERN Chun Lik Tan (Alvin) - Birmingham clat@hep.ph.bham.ac.uk GANGA Workshop, 20-22 April 2004, CERN Chun Lik Tan (Alvin) - Birmingham clat@hep.ph.bham.ac.uk

2. Agenda Auto code documentation tools Epydoc http://epydoc.sourceforge.net/ Happydoc http://happydoc.sourceforge.net/ Making use of Python optparse Accompanying documentation Auto code documentation tools Epydoc http://epydoc.sourceforge.net/ Happydoc http://happydoc.sourceforge.net/ Making use of Python optparse Accompanying documentation

3. Automatic code documentation tools Epydoc “Epydoc is a tool for generating API documentation for Python modules, based on their docstrings. A lightweight markup language called Epytext can be used to format docstrings, and to add information about specific fields, such as parameters and instance variables. Epydoc also understands docstrings written in ReStructuredText, Javadoc, and plain text.”

4. Epytext: example...extracted from the Epydoc webpage.

6. Automatic code documentation tools Running Epydoc on your module(s): $ epydoc [--html|--pdf] [-o DIR] [-n NAME] [-v|-q] [-u URL] [-t PAGE] [-c SHEET] [--private-css SHEET] [--private|--no-private] [--inheritance STYLE] MODULE... Running Epydoc on your module(s): $ epydoc [--html|--pdf] [-o DIR] [-n NAME] [-v|-q] [-u URL] [-t PAGE] [-c SHEET] [--private-css SHEET] [--private|--no-private] [--inheritance STYLE] MODULE...

7. Automatic code documentation tools Happydoc “HappyDoc is a tool for extracting documentation from Python source code. It differs from other such applications (e.g. Epydoc) 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.”

9. Automatic code documentation tools Running Happydoc on your module(s): $./happydoc [-hqv] [--help] [--no-cache] [--no-comments] [-T DOCSET_TYPE] [-d OUTPUT_DIRECTORY] [-i IGNORE_DIRECTORY] [-t TEMPLATE_NAME] [--no-private-names] [--cache-prefix=CACHE_FILE_PREFIX] [--mimetype=EXTENSION_AND_MIME_TYPE] [--template-path=TEMPLATE_PATH_DIRECTORY] [--title=TITLE] MODULE... Running Happydoc on your module(s): $./happydoc [-hqv] [--help] [--no-cache] [--no-comments] [-T DOCSET_TYPE] [-d OUTPUT_DIRECTORY] [-i IGNORE_DIRECTORY] [-t TEMPLATE_NAME] [--no-private-names] [--cache-prefix=CACHE_FILE_PREFIX] [--mimetype=EXTENSION_AND_MIME_TYPE] [--template-path=TEMPLATE_PATH_DIRECTORY] [--title=TITLE] MODULE...

10. Optparse “The optparse module is a powerful, flexible, extensible, easy-to-use command-line parsing library for Python (new in Python 2.3). Using optparse, you can add intelligent, sophisticated handling of command-line options to your scripts with very little overhead.”

11. Optparse: Simple example from optparse import OptionParser parser = OptionParser() parser.add_option("-f", "--file", dest="filename", help="write report to FILE", metavar="FILE") parser.add_option("-q", "--quiet", action="store_false", dest="verbose", default=True, help="don't print status to stdout") (options, args) = parser.parse_args()

12. Optparse: Typical usage $ -f outfile --quiet $ -qfoutfile $ --file=outfile -q $ --quiet --file outfile $ -h

13. Optparse: output usage: [options] options: -h, --help show this help message and exit -fFILE, --file=FILE write report to FILE -q, --quiet don't print status to stdout

14. Accompanying documentation Additional text files should be provided: CHANGELOG - Changes must be recorded (date-stamped) when a non-trivial change in the code is done. README - e.g. MAN-style documentation. INSTALL - Installation procedure. Depends on install mechanism. Additional text files should be provided: CHANGELOG - Changes must be recorded (date-stamped) when a non-trivial change in the code is done. README - e.g. MAN-style documentation. INSTALL - Installation procedure. Depends on install mechanism.

15. Conclusion Epydoc and Happydoc will both suit our purpose. Aesthetically, the option is obvious. If static parsing of the code is need, Happydoc will be our choice. Depending on the installation procedure, documentation may be influenced. E.g. distutils Epydoc and Happydoc will both suit our purpose. Aesthetically, the option is obvious. If static parsing of the code is need, Happydoc will be our choice. Depending on the installation procedure, documentation may be influenced. E.g. distutils