1 / 15

GANGA Release Strategy Documentation Tools

GANGA Release Strategy Documentation Tools. GANGA Workshop, 20-22 April 2004, CERN Chun Lik Tan (Alvin) - Birmingham clat@hep.ph.bham.ac.uk. Agenda. Auto code documentation tools Epydoc http://epydoc.sourceforge.net/ Happydoc http://happydoc.sourceforge.net/ Making use of Python optparse

terah
Download Presentation

GANGA Release Strategy Documentation Tools

An Image/Link below is provided (as is) to download presentation Download Policy: Content on the Website is provided to you AS IS for your information and personal use and may not be sold / licensed / shared on other websites without getting consent from its author. Content is provided to you AS IS for your information and personal use only. Download presentation by click this link. While downloading, if for some reason you are not able to download a presentation, the publisher may have deleted the file from their server. During download, if you can't get a presentation, the file might be deleted by the publisher.

E N D

Presentation Transcript

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

  2. Agenda • Auto code documentation tools • Epydochttp://epydoc.sourceforge.net/ • Happydochttp://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.

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

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

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

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

  9. Optparse:Simple example • from optparse import OptionParserparser = 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()

  10. Optparse:Typical usage • $ <yourscript> -f outfile --quiet$ <yourscript> -qfoutfile$ <yourscript> --file=outfile -q$ <yourscript> --quiet --file outfile$ <yourscript> -h

  11. Optparse: 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

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

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

More Related