README for pythondoc

Daniel Larsson, Daniel.Larsson@vasteras.mail.telia.com
Version 0.7
Latest release: http://starship.skyport.net/crew/danilo/pythondoc

Contents

Short description

Pythondoc is a tool that extracts information from Python objects, and generates reference manuals and indices. For best results use StructuredText markup in your docstrings. A quick guide to StructuredText may be found at http://www.zope.org/Members/millejoh/structuredText.

IMPORTANT! Many people seems to have problems running pythondoc. It is very important to know pythondoc is mostly implemented as a package. There's one file, 'pythondoc' (no extension). On the Windows platform it is probably best to rename this to 'pdoc.py' and move it to a directory in your path. On Unix, the Makefile install rule should take care of setting up everything for you.

The tool is extensible in at least two different ways:

Command line interface

Currently pythondoc only has a command line interface. To see the available arguments, and a description, run pythondoc with the --help option.

Extension module options

A writer of an extension module (formatter/crossreferencing module) can add its own options. Those options are given by the command line user as 'pythondoc <option name>=<option value>'. The option name may be qualified with the extension name, if two extensions register the same option name: <ext name>_<option name>

Options may also be set up in an option file. Two different option files are read, the global, residing in the directory containing the pythondoc package, and the local, residing in your home directory (os.environ['HOME']). Both must be called pythondoc.opts.

Output running with --help

Usage: pythondoc [-a] [-D] [-d dir] [-f format] [-h] [-i] [-l] [-m file] [-o option_file] [-s dir] [-v] [key=value ...] files ...
-a, --all
Generate documentation for all modules in sys.path.
-D, --nodoc
Don't generate document pages.
-d dir, --directory dir
Save generated files in the dir directory.
-f format, --format format
Generate files using the formatter format.
-h, --help
Print help text.
-i, --index
Generate index pages.
-l, --load
Load previously saved doctrees.
-m file, --module file
Read modules from file
-o option file, --options option file
Load options from given file.
-s dir, --savedir dir
Save/read doctrees from given directory.
-v, --verbose
Verbose mode
key=value
Pass formatter options.

DESCRIPTION

pythondoc scans one or several python modules for documentation strings. From the documentation strings, manual pages are generated in any of various format (see below) Note that you can give multiple format options at once. It is a lot faster, since the the source files are only parsed/imported and traversed once. The key=value options are used to send arguments to formatters. These definitions can be put in the environment as well, where 'key' is an environment variable. The 'key' can either be '_', or just ''. Options can also be read from option files. Option files are read from the installation directory and your home directory (named pythondoc.opts), or by giving a filename with the **-o** option. The 'files' argument may either be module names or file names. Be careful if you use filenames. Internally, filenames are translated to module names, and the directory holding the file is added to sys.path. It is possible that a different module with the same name is loaded. Optionally, you can have a file containing the modules you want to document. Use the -m file option, where the file contains a python tuple of module names (i.e. comma separated list of module names).
all
main: Traverse sys.path and document everything (type: bool, default: 0)
options
main: Pythondoc option file (type: file path, default: )
document
main: Generate document pages (type: bool, default: 1)
directory
main: Directory to store output (type: file path, default: .)
savedir
main: Save doctrees (type: directory path, default: )
head
main: Generate head page (type: bool, default: 0)
index
main: Generate index pages (type: bool, default: 0)
load
main: Load previously saved doctrees (type: bool, default: 0)
frame
HTML4: Generate pages using frames. (type: bool, default: 0)
footer_file
HTML4: File containing HTML code inserted right before the body end tag. (type: file path, default: )
header_file
HTML4: File containing HTML code inserted right after the body start tag. (type: file path, default: )
stylesheet
HTML4: URL to stylesheet (CSS) to use. (type: URL, default: pythondoc.css)

FORMATTERS

Currently the following formatters are supported:
  • HTML4
  • XML

To do

These are things I plan to do:

  • Make a Tkinter interface.
  • Take a look at Microsoft HTMLHelp, and possibly generate such files. Possibly generate them from the XML output.
  • Other suggestions from users... (hint, hint)

Release notes

Version 0.7 - 2000-01-25

Version 0.6 - 1999-04-30

Corrected some minor bugs.

  • Now makes an 'eval' on command line option values, so you don't get a 'type mismatch' error on integer options.

    • Version 0.5 (alpha) - 1998-12-14

    • Removed the 'path' attribute in the generated XML (and the internal tree), replacing it with the 'id' tree. The 'id' attribute should now be globally unique.
    • Now makes an 'eval' on command line option values, so you don't get a 'type mismatch' error on integer options.

    Version 0.4 (alpha) - 1998-10-06

    Hmmm, never do a hasty release... Joe van Andel found some annoying bugs, like DOS newlines in 'pythondoc', and some other stuff...

    Version 0.3 (alpha) - 1998-10-04

    This release contains bugfixes and very little new functionality:

    • Fixed stupid mistakes in Makefile (the xref directory wasn't created, and the pythondoc file wasn't in the distribution).
    • Changed the help option from -? to -h.
    • Added long option names.
    • Removed elements from XML output (names are stored in 'id' attributes).

    Version 0.2 (alpha) - 1998-08-11

    This release contains bugfixes and some new functionality:

    • Generation of "Table of contents" added
    • Saving and loading of doctrees (-s and -l) now works. This is useful if you want to parse modules one at a time, but make the index and table of contents pages to retain old information.
    • Option files are added to store common options, such as HTML headers and footers.

    Version 0.1 (alpha) - 1998-08-06

    This is the first release, which is missing a lot, certainly contains bugs, but is released to the Python DOC-SIG in hope of feedback. It can generate HTML 4.0 code, but I haven't spent too much time making them look good. The style sheet uses all kinds of colors to verify things are working as they should...