GANGA Release Strategy Documentation Tools GANGA Workshop, 20-22 April 2004, CERN Chun Lik Tan (Alvin) - Birmingham [email protected] GANGA Workshop,

GANGARelease Strategy

Documentation Tools

GANGARelease Strategy

Documentation Tools

GANGA Workshop, 20-22 April 2004, CERNChun Lik Tan (Alvin) - Birmingham

[email protected]

GANGA Workshop, 20-22 April 2004, CERNChun Lik Tan (Alvin) - Birmingham

[email protected]

AgendaAgendaAuto code documentation tools

Epydochttp://epydoc.sourceforge.net/

Happydochttp://happydoc.sourceforge.net/

Making use of Python optparse

Accompanying documentation

Auto code documentation tools

Epydochttp://epydoc.sourceforge.net/

Happydochttp://happydoc.sourceforge.net/

Making use of Python optparse

Accompanying documentation

Automatic code documentation tools

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

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

Epytext: exampleEpytext: example

...extracted from the Epydoc webpage....extracted from the Epydoc webpage.

Automatic code documentation tools

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

Automatic code documentation tools

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

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

Automatic code documentation tools

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

OptparseOptparse

“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.”

“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.”

Optparse:Simple example

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

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

Optparse:Typical usage

Optparse:Typical usage

$ <yourscript> -f outfile --quiet$ <yourscript> -qfoutfile$ <yourscript> --file=outfile -q$ <yourscript> --quiet --file outfile$ <yourscript> -h

$ <yourscript> -f outfile --quiet$ <yourscript> -qfoutfile$ <yourscript> --file=outfile -q$ <yourscript> --quiet --file outfile$ <yourscript> -h

Optparse: outputOptparse: output

usage: <yourscript> [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

usage: <yourscript> [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

Accompanying documentationAccompanying 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.

ConclusionConclusion

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