GANGA Release Strategy Documentation Tools GANGA Workshop, 20-22 April 2004, CERN Chun Lik Tan...
15
GANGA Release Strategy Documentation Tools GANGA Workshop, 20-22 April 2004, CERN Chun Lik Tan (Alvin) - Birmingham [email protected]
-
Upload
oscar-washington -
Category
Documents
-
view
218 -
download
0
Transcript of GANGA Release Strategy Documentation Tools GANGA Workshop, 20-22 April 2004, CERN Chun Lik Tan...
GANGARelease Strategy
Documentation Tools
GANGARelease Strategy
Documentation Tools
GANGA Workshop, 20-22 April 2004, CERNChun Lik Tan (Alvin) - Birmingham
GANGA Workshop, 20-22 April 2004, CERNChun Lik Tan (Alvin) - Birmingham
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
