$Id: README 1956 2004-09-01 20:13:25Z fredrik $

The PythonDoc tool parses source files and generates API descriptions
in XML and HTML.

This release runs on Python 1.5.2 or later.  To use this tool, you
need the effbot.org ElementTree library (version 1.1 or later is
recommended), available from:

    http://effbot.org/downloads#elementtree


To install pythondoc, use
        
    $ python setup.py install

or just copy the 'pythondoc.py' script to a suitable location.


To use, run pythondoc on one or more Python scripts or module, or on
package directories.  The current version writes output files (named
pythondoc*.html) to the current directory.

    $ pythondoc mymodule.py
    pythondoc-mymodule.html ok

    $ pythondoc mypackage
    pythondoc-mypackage.mymodule.html ok
    pythondoc-mypackage.mylibrary.html ok
    pythondoc-mypackage.mytoys.html ok

    $ pythondoc mydir/*.py
    pythondoc-mymodule.html ok
    pythondoc-mytoys.html ok

To generate XML output as well, run pythondoc with the -x option.

For a list of additional options, run the tool without arguments.

For an example of a marked-up module, see the pythondoc.py script
itself.

For more information on the PythonDoc tool, including a detailed
description of the markup format and the plugin interface, see:

    http://effbot.org/zone/pythondoc.htm

For more tips and tricks, see Sun's JavaDoc site:

    http://java.sun.com/j2se/javadoc/

enjoy /F

--------------------------------------------------------------------
Changes (latest first)
--------------------------------------------------------------------

(2.1b2 released)

- handle decorators with multi-line arguments

(2.1b1 released)

- ignore decorators, if present (Python 2.4)

(2.1a3 released)

- process directory contents in lexical order

- fixed parsing of repeated single-line methods.

(2.1a2 released)

- fixed parsing of the first class attribute in a class.

(2.1a1 released)

- added support for inline {@link} and {@linkplain} tags.

(2.0b4 released; 2.0 final released)

- added support for RISC OS (from Simon Callan)

- added experimental support for module-level comments:

    ##
    # This is a module comment.  It must be placed before
    # any other PythonDoc comment.
    ##

(2.0b3 released)

- XML output is now disabled by default; use -x to enable.

- in the XML output, moved metadata elements (def, summary, param,
  return, description, etc) to a separate info element:

    <subject name= lineno=>
      <info>
        <name />
        <def />
        <summary />
        ...
      </info>
      <subject />
      <subject />
      ...
    </subject>

- added @author, @version, @deprecated, and @since to list of known
  tags (none of these are used by the standard HTML renderer).

(2.0b2 released)

- fixed HTML character encoding in the standard HTML renderer.

- added -Dzone and -Dstyle=stylesheet options to the default renderer.
  -Dzone is used to render effbot.org zone documents, -Dstyle is used
  to specify a stylesheet URL for the HTML document.

- added experimental @defreturn support.  if present, the defreturn
  value is displayed after the "def" statement, for functions and
  methods.  for example:

    @def myfunction(arg)
    @defreturn string

  can be rendered as

    myfunction(arg) => string

- generate strict XHTML 1.0 output

- tweaked the HTML output; most notably, show the class summary in the
  toplevel section, and show a full description in the class section.

- added support for pluggable output generators, including generator
  variables (-O, -D).

(2.0b1 released)

- only generate output if there's at least one toplevel description
  (use -f to force output anyway).

- added default HTML generator ("compact style")

- added support for PEP-263 style "coding" directives

- added optional name prefix argument to ModuleParser; added -p
  option to set the prefix from the command line

- fixed a 1.5.2 glitch

(2.0a2 released)

- convert HTML in descriptors and tags to XHTML, and embed XHTML
  in the generated XML.

- fixed the "def" element; for methods, the instance argument
  (usually "self") is no longer included.  for methods, functions,
  and classes, the leading "def" or "class" is no longer included.

- minor tweaks to make PythonDoc run under Python 1.5.2; this release
  has been tested with 1.5.2, 2.0, 2.1, 2.2, and 2.3.

- assorted parsing fixes; most notably, make sure to include the first
  method in a class also if it does not have a PythonDoc comment.

(2.0a1 released)

Initial version.

--------------------------------------------------------------------
Software License
--------------------------------------------------------------------

Copyright (c) 2002-2004 by Fredrik Lundh

By obtaining, using, and/or copying this software and/or its
associated documentation, you agree that you have read, understood,
and will comply with the following terms and conditions:

Permission to use, copy, modify, and distribute this software and
its associated documentation for any purpose and without fee is
hereby granted, provided that the above copyright notice appears in
all copies, and that both that copyright notice and this permission
notice appear in supporting documentation, and that the name of
Secret Labs AB or the author not be used in advertising or publicity
pertaining to distribution of the software without specific, written
prior permission.

SECRET LABS AB AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD
TO THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANT-
ABILITY AND FITNESS.  IN NO EVENT SHALL SECRET LABS AB OR THE AUTHOR
BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY
DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS,
WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS
ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE
OF THIS SOFTWARE.

--------------------------------------------------------------------