1.1   Downloading Epydoc

Epydoc can be downloaded from the SourceForge download page. Epydoc is available in five formats:

• RPM (.noarch.rpm)
• Windows installer (.win32.exe)
• Source install (.tar.gz)
• Source install (.zip)
• Source RPM (.src.rpm)

If you are installing on RedHat, I recommend that you use the RPM file. If you are installing on Windows, I recommended that you use the windows installer. Otherwise, you should use one of the source install files.

1.2   Getting Epydoc from Subversion

If you wish to keep up on the latest developments, you can get the latest version of epydoc from the subversion repository:

[/home/edloper]$ svn co https://epydoc.svn.sourceforge.net/svnroot/epydoc/trunk/epydoc epydoc
[/home/edloper]$ ls epydoc
Makefile  doc  man  sandbox  src

This will create a directory named epydoc containing the latest version of epydoc. The epydoc package itself is in epydoc/src/epydoc (so adding epydoc/src to your PYTHONPATH will let you use it). You should periodically update your copy of the subversion repository, to make sure you have all the latest changes:

[/home/edloper/epydoc]$ svn up

You can browse the subversion repository here.

1.3   Installing from the RPM File

1. Download the RPM file to a directory of your choice.

2. Use rpm to install the new package.

   [/tmp]$ su
   Password:
   [/tmp]# rpm -i epydoc-3.0.1.noarch.rpm
   

3. Once epydoc is installed, you can delete the RPM file.

   [/tmp]# rm epydoc-3.0.1.rpm
   

1.4   Installing from the Windows Installer

1. Download and run epydoc-3.0.1.win32.exe.
2. Follow the on-screen instructions. Epydoc will be installed in the epydoc subdirectory of your Python installation directory (typically C:\Python24\).
3. The Windows installer creates two scripts in the Scripts subdirectory of your Python installation directory: epydoc.pyw opens the graphical user interface, and epydoc.py calls the command line interface. If you'd like, you can create shortcuts from these scripts to more convenient locations (such as your desktop or start menu).
4. Once epydoc is installed, you can delete epydoc-3.0.1.win32.exe.

1.5   Installing from the Source Distribution (using make)

1. Download an epydoc source distribution to a directory of your choice, and uncompress it.

   [/tmp]$ wget -q http://prdownloads.sourceforge.net/epydoc/epydoc-3.0.1.tar.gz
   [/tmp]$ gunzip epydoc-3.0.1.tar.gz
   [/tmp]$ tar -xvf epydoc-3.0.1.tar
   

2. Use make install in the eydoc-3.0.1/ directory to install epydoc.

   [/tmp]$ cd epydoc-3.0.1/
   [/tmp/epydoc-3.0.1]$ su
   Password:
   [/tmp/epydoc-3.0.1]# make install
   running install
   running build
   [...]
   copying build/scripts/epydoc -> /usr/bin
   changing mode of /usr/bin/epydoc to 100775
   

3. If you'd like to keep a local copy of the documentation, then use make installdocs. By default, this will install the documentation to /usr/share/doc/ and the man pages to /usr/share/man/. If you would prefer to install documentation to different directories (such as /usr/lib/doc), then edit the MAN and DOC variables at the top of Makefile before running make installdocs.

   [/tmp/epydoc-3.0.1]# make installdocs
   

4. Once epydoc is installed, you can delete the installation directory and the source distribution file.

   [/tmp/epydoc-3.0.1]# cd ..
   [/tmp]# rm -r epydoc-3.0.1
   [/tmp]# rm epydoc-3.0.1.tar
   

1.6   Installing from the Source Distribution (without make)

1. Download an epydoc source distribution to a directory of your choice, and uncompress it.

   [/tmp]$ wget -q http://prdownloads.sourceforge.net/epydoc/epydoc-3.0.1.tar.gz
   [/tmp]$ gunzip epydoc-3.0.1.tar.gz
   [/tmp]$ tar -xvf epydoc-3.0.1.tar
   

2. Use the setup.py script in the eydoc-3.0.1/ directory to install epydoc.

   [/tmp]$ cd epydoc-3.0.1/
   [/tmp/epydoc-3.0.1]$ su
   Password:
   [/tmp/epydoc-3.0.1]# python setup.py install
   running install
   running build
   [...]
   copying build/scripts/epydoc -> /usr/bin
   changing mode of /usr/bin/epydoc to 100775
   [/tmp/epydoc-3.0.1]# cd ..
   [/tmp]#
   

3. If you'd like to keep a local copy of the documentation, then copy it to a permanant location, such as /usr/share/doc/. You may also want to copy the man pages to a permanant location, such as /usr/share/man/.

   [/tmp]# cp -r epydoc-3.0.1/doc/ /usr/share/doc/epydoc/
   [/tmp]# cp epydoc-3.0.1/man/* /usr/share/man/
   

4. Once epydoc is installed, you can delete the installation directory and the source distribution file.

   [/tmp]# rm -r epydoc-3.0.1
   [/tmp]# rm epydoc-3.0.1.tar
   

1.7   Installing on Debian

Epydoc 2.1 is available as a testing debian package (python-epydoc). The epydoc documentation is also available as a package (epydoc-doc).

2.1   The Command Line Interface

The epydoc script extracts API documentation for a set of Python objects, and writes it using a selected output format. Objects can be named using dotted names, module filenames, or package directory names. (On Windows, this script is named epydoc.py.)

epydoc [--html|--pdf] [-o DIR] [--parse-only|--introspect-only] [-v|-q]
       [--name NAME] [--url URL] [--docformat NAME] [--graph GRAPHTYPE]
       [--inheritance STYLE] [--config FILE] OBJECTS...

[epydoc]$ epydoc --html sys -o sys_docs

[epydoc]$ epydoc -v -o html/api --name epydoc --css white \
                 --url http://epydoc.sourceforge.net \
                 --inheritance listed --graph all src/epydoc
[epydoc]$ epydoc -v -o latex/api --pdf --name "Epydoc" src/epydoc

[epydoc] # Epydoc section marker (required by ConfigParser)

# Information about the project.
name: My Cool Project
url: http://cool.project/

# The list of modules to document.  Modules can be named using
# dotted names, module filenames, or package directory names.
# This option may be repeated.
modules: sys, os.path, re
modules: my/project/driver.py

# Write html output to the directory "apidocs"
output: html
target: apidocs/

# Include all automatically generated graphs.  These graphs are
# generated using Graphviz dot.
graph: all
dotpath: /usr/local/bin/dot

2.2   The Graphical Interface

Epydoc also includes a graphical interface, for systems where command line interfaces are not convenient (such as Windows). The graphical interface can be invoked with the epydocgui command, or with epydoc.pyw in the Scripts subdirectory of the Python installation directory under Windows. Currently, the graphical interface can only generate HTML output.

Use the Add box to specify what objects you wish to document. Objects can be specified using dotted names (such as os.path), module filenames (such as epydoc/epytext.py), or package directory names (such as epydoc/). Packages are expanded to include all sub-modules and sub-packages. Once you have added all of the modules that you wish to document, press the Start button. Epydoc's progress will be displayed on the progress bar.

To customize the output, click on the Options arrow at the bottom of the window. This opens the options pane, which contains fields corresponding to each command line option.

The epydoc graphical interface can save and load project files, which record the set of modules and the options that you have selected. Select File->Save to save the current modules and options to a project file; and File->Open to open a previously saved project file. (These project files do not currently use the same format as the configuration files used by the command line interface.)

For more information, see the epydocgui(1) man page.

2.3   Documentation Completeness Checks

The epydoc script can be used to check the completeness of the reference documentation. In particular, it will check that every module, class, method, and function has a description; that every parameter has a description and a type; and that every variable has a type. If the -p option is used, then these checks are run on both public and private objects; otherwise, the checks are only run on public objects.

epydoc --check [-p] MODULES...

MODULES...

A list of the modules that should be checked. Modules may be specified using either filenames (such as epydoc/epytext.py) or module names (such as os.path). The filename for a package is its __init__.py file.

For each object that fails a check, epydoc will print a warning. For example, some of the warnings generated when checking the completeness of the documentation for epydoc's private objects are:

epydoc.html.HTML_Doc._dom_link_to_html........No docs
epydoc.html.HTML_Doc._module..................No type
epydoc.html.HTML_Doc._link_to_html.link.......No descr
epydoc.html.HTML_Doc._author.return...........No type
epydoc.html.HTML_Doc._author.authors..........No descr, No type
epydoc.html.HTML_Doc._author.container........No descr, No type
epydoc.html.HTML_Doc._base_tree.uid...........No descr, No type
epydoc.html.HTML_Doc._base_tree.width.........No descr, No type
epydoc.html.HTML_Doc._base_tree.postfix.......No descr, No type

If you'd like more fine-grained control over what gets checked, or you would like to check other fields (such as the author or version), then you should use the DocChecker class directly.

2.4   HTML Files

Every Python module and class is documented in its own file. Index files, tree files, a help file, and a frames-based table of contents are also created. The following list describes each of the files generated by epydoc:

index.html

The standard entry point for the documentation. Normally, index.html is a copy of the frames file (frames.html). But if the --no-frames option is used, then index.html is a copy of the API documentation home page, which is normally the documentation page for the top-level package or module (or the trees page if there is no top-level package or module).

module-module.html

The API documentation for a module. module is the complete dotted name of the module, such as sys or epydoc.epytext.

class-class.html

The API documentation for a class, exception, or type. class is the complete dotted name of the class, such as epydoc.epytext.Token or array.ArrayType.

module-pysrc.html

A page with the module colorized source code, with links back to the objects main documentation pages. The creation of the colorized source pages can be controlled using the options --show-sourcecode and --no-sourcecode.

module-tree.html

The documented module hierarchy.

class-tree.html

The documented classes hierarchy.

identifier-index.html

The index of all the identifiers found in the documented items.

term-index.html

The index of all the term definition found in the docstrings. Term definitions are created using the Indexed Terms markup.

bug-index.html

The index of all the known bug in the documented sources. Bugs are marked using the @bug tag.

todo-index.html

The index of all the to-do items in the documented sources. They are marked using the @todo tag.

help.html

The help page for the project. This page explains how to use and navigate the webpage produced by epydoc.

epydoc-log.html

A page with the log of the epydoc execution. It is available clicking on the timestamp below each page, if the documentation was created using the --include-log option. The page also contains the list of the options enabled when the documentation was created.

api-objects.txt

A text file containing each available item and the URL where it is documented. Each item takes a file line and it is separated by the URL by a tab charecter. Such file can be used to create external API links.

redirect.html

A page containing Javascript code that redirect the browser to the documentation page indicated by the accessed fragment. For example opening the page redirect.html#epydoc.apidoc.DottedName the browser will be redirected to the page epydoc.apidoc.DottedName-class.html.

frames.html

The main frames file. Two frames on the left side of the window contain a table of contents, and the main frame on the right side of the window contains API documentation pages.

toc.html

The top-level table of contents page. This page is displayed in the upper-left frame of frames.html, and provides links to the toc-everything.html and toc-module-module.html pages.

toc-everything.html

The table of contents for the entire project. This page is displayed in the lower-left frame of frames.html, and provides links to every class, type, exception, function, and variable defined by the project.

toc-module-module.html

The table of contents for a module. This page is displayed in the lower-left frame of frames.html, and provides links to every class, type, exception, function, and variable defined by the module. module is the complete dotted name of the module, such as sys or epydoc.epytext.

epydoc.css

The CSS stylesheet used to display all HTML pages.

2.5   CSS Stylesheets

Epydoc creates a CSS stylesheet (epydoc.css) when it builds the API documentation for a project. You can specify which stylesheet should be used using the --css command-line option. If you do not specify a stylesheet, and one is already present, epydoc will use that stylesheet; otherwise, it will use the default stylesheet.

3.1   Variable docstrings

Python don't support directly docstrings on variables: there is no attribute that can be attached to variables and retrieved interactively like the __doc__ attribute on modules, classes and functions.

While the language doesn't directly provides for them, Epydoc supports variable docstrings: if a variable assignment statement is immediately followed by a bare string literal, then that assignment is treated as a docstring for that variable. In classes, variable assignments at the class definition level are considered class variables; and assignments to instance variables in the constructor (__init__) are considered instance variables:

class A:
    x = 22
    """Docstring for class variable A.x"""

    def __init__(self, a):
        self.y = a
        """Docstring for instance variable A.y

Variables may also be documented using comment docstrings. If a variable assignment is immediately preceeded by a comment whose lines begin with the special marker '#:', or is followed on the same line by such a comment, then it is treated as a docstring for that variable:

#: docstring for x
x = 22
x = 22 #: docstring for x

Notice that variable docstrings are only available for documentation when the source code is available for parsing: it is not possible to retrieve variable

3.2   Items visibility

Any Python object (modules, classes, functions, variables...) can be public or private. Usually the object name decides the object visibility: objects whose name starts with an underscore and doesn't end with an underscore are considered private. All the other objects (including the "magic functions" such as __add__) are public.

For each module and class, Epydoc generates pages with both public and private methods. A Javascript snippet allows you to toggle the visibility of private objects.

If a module wants to hide some of the objects it contains (either defined in the module itself or imported from other modules), it can explicitly list the names if its public names in the __all__ variable.

If a module defines the __all__ variable, Epydoc uses its content to decide if the module objects are public or private.

4.1   A Brief Introduction

Epytext is a simple lightweight markup language that lets you add formatting and structue to docstrings. Epydoc uses that formatting and structure to produce nicely formatted API documentation. The following example (which has an unusually high ratio of documentaiton to code) illustrates some of the basic features of epytext:

def x_intercept(m, b):
    """
    Return the x intercept of the line M{y=m*x+b}.  The X{x intercept}
    of a line is the point at which it crosses the x axis (M{y=0}).

    This function can be used in conjuction with L{z_transform} to
    find an arbitrary function's zeros.

    @type  m: number
    @param m: The slope of the line.
    @type  b: number
    @param b: The y intercept of the line.  The X{y intercept} of a
              line is the point at which it crosses the y axis (M{x=0}).
    @rtype:   number
    @return:  the x intercept of the line M{y=m*x+b}.
    """
    return -b/m

You can compare this function definition with the API documentation generated by epydoc. Note that:

• Paragraphs are separated by blank lines.
• Inline markup has the form "x{...}", where "x" is a single capital letter. This example uses inline markup to mark mathematical expressions ("M{...}"); terms that should be indexed ("X{...}"); and links to the documentation of other objects ("L{...}").
• Descriptions of parameters, return values, and types are marked with "@field:" or "@field arg:", where "field" identifies the kind of description, and "arg" specifies what object is described.

Epytext is intentionally very lightweight. If you wish to use a more expressive markup language, I recommend reStructuredText.

4.2   Epytext Language Overview

Epytext is a lightweight markup language for Python docstrings. The epytext markup language is used by epydoc to parse docstrings and create structured API documentation. Epytext markup is broken up into the following categories:

• Block Structure divides the docstring into nested blocks of text, such as paragraphs and lists.

  o Basic Blocks are the basic unit of block structure.

  o Hierarchical blocks represent the nesting structure of the docstring.

• Inline Markup marks regions of text within a basic block with properties, such as italics and hyperlinks.

4.3   Block Structure

Block structure is encoded using indentation, blank lines, and a handful of special character sequences.

• Indentation is used to encode the nesting structure of hierarchical blocks. The indentation of a line is defined as the number of leading spaces on that line; and the indentation of a block is typically the indentation of its first line.
• Blank lines are used to separate blocks. A blank line is a line that only contains whitespace.
• Special character sequences are used to mark the beginnings of some blocks. For example, '-' is used as a bullet for unordered list items, and '>>>' is used to mark doctest blocks.

The following sections describe how to use each type of block structure.

def example():
    """
    This is a paragraph.  Paragraphs can
    span multiple lines, and can contain
    I{inline markup}.

    This is another paragraph.  Paragraphs
    are separated by blank lines.
    """
    *[...]*

def example():
    """
    1. This is an ordered list item.

    2. This is a another ordered list
    item.

    3. This is a third list item.  Note that
       the paragraph may be indented more
       than the bullet.
    """
    *[...]*

def example():
    """
    This is a paragraph.
      1. This is a list item.
      2. This a second list
         item.
           - This is a sublist
    """
    [...]

def example():
    """
    1. This is a list item.  Its
    paragraph is indented 7 spaces.
    - This is a sublist.  It is
      indented 7 spaces.
    """
    #[...]

def example():
    """
    This is a paragraph.
      1. This is a list item.
        - This is a sublist.
        - The sublist contains two
          items.
            - The second item of the
              sublist has its own sublist.

      2. This list item contains two
         paragraphs and a doctest block.

         >>> print 'This is a doctest block'
         This is a doctest block

         This is the second paragraph.
    """
    #[...]

def example():
    """
    This sentence ends with the number
    1.  Epytext can't tell if the "1."
    is a bullet or part of the paragraph,
    so it generates an error.
    """
    #[...]

def example():
    """
    This sentence ends with the number 1.

    This sentence ends with the number
    E{1}.
    """
    #[...]

def example():
    """
    This paragraph is not in any section.

    Section 1
    =========
      This is a paragraph in section 1.

      Section 1.1
      -----------
      This is a paragraph in section 1.1.

    Section 2
    =========
      This is a paragraph in section 2.
    """
    #[...]

def example():
    """
    The following is a literal block::

        Literal /
               / Block

    This is a paragraph following the
    literal block.
    """
    #[...]

Literal /
       / Block

def example():
    """
    The following is a doctest block:

        >>> print (1+3,
        ...        3+5)
        (4, 8)
        >>> 'a-b-c-d-e'.split('-')
        ['a', 'b', 'c', 'd', 'e']

    This is a paragraph following the
    doctest block.
    """
    #[...]

>>> print (1+3,
...        3+5)
(4, 8)
>>> 'a-b-c-d-e'.split('-')
['a', 'b', 'c', 'd', 'e']

def example():
    """
    @param x: This is a description of
        the parameter x to a function.
        Note that the description is
        indented four spaces.
    @type x: This is a description of
        x's type.
    @return: This is a description of
        the function's return value.

        It contains two paragraphs.
    """
    #[...]

4.4   Inline Markup

Inline markup has the form 'x{...}', where x is a single capital letter that specifies how the text between the braces should be rendered. Inline markup is recognized within paragraphs and section headings. It is not recognized within literal and doctest blocks. Inline markup can contain multiple words, and can span multiple lines. Inline markup may be nested.

A matching pair of curly braces is only interpreted as inline markup if the left brace is immediately preceeded by a capital letter. So in most cases, you can use curly braces in your text without any form of escaping. However, you do need to escape curly braces when:

1. You want to include a single (un-matched) curly brace.
2. You want to preceed a matched pair of curly braces with a capital letter.

Note that there is no valid Python expression where a pair of matched curly braces is immediately preceeded by a capital letter (except within string literals). In particular, you never need to escape braces when writing Python dictionaries. See also escaping.

def example():
    """
    I{B{Inline markup} may be nested; and
    it may span} multiple lines.

      - I{Italicized text}
      - B{Bold-faced text}
      - C{Source code}
      - M{Math}

    Without the capital letter, matching
    braces are not interpreted as markup:
    C{my_dict={1:2, 3:4}}.
    """
    #[...]

def example():
    """
    - U{www.python.org}
    - U{http://www.python.org}
    - U{The epydoc homepage<http://
    epydoc.sourceforge.net>}
    - U{The B{Python} homepage
    <www.python.org>}
    - U{Edward Loper<mailto:edloper@
    gradient.cis.upenn.edu>}
    """
    #[...]

def example():
    """
    - L{x_transform}
    - L{search<re.search>}
    - L{The I{x-transform} function
    <x_transform>}
    """
    #[...]

def example():
    """
    An X{index term} is a term that
    should be included in the index.
    """
    #[...]

def example():
    """
    Symbols can be used in equations:

      - S{sum}S{alpha}/x S{<=} S{beta}

    S{<-} and S{larr} both give left
    arrows.  Some other arrows are
    S{rarr}, S{uarr}, and S{darr}.
    """
    #[...]

def example():
    """
    This paragraph ends with two
    colons, but does not introduce
    a literal blockE{:}E{:}

    E{-} This is not a list item.

    Escapes can be used to write
    unmatched curly braces:
    E{rb}E{lb}
    """
    #[...]

4.5   Characters

def example():
    """
    <B>test</B>
    """
    #[...]

5.1   Field Markup

Each docstring markup langauge marks fields differently. The following table shows the basic fields syntax for each markup language. For more information, see the definition of field syntax for each markup language.

@tag: body...
@tag arg: body...

:tag: body...
:tag arg: body...

@tag body...
@tag arg body...

5.2   Supported Fields

The following table lists the fields that epydoc currently recognizes. Field tags are written using epytext markup; if you are using a different markup language, then you should adjust the markup accordingly.

def plant(seed, *tools, **options):
    """
    @param seed: The seed that should be planted.
    @param tools: Tools that should be used to plant the seed.
    @param options: Any extra options for the planting.

    @keyword dig_deep: Plant the seed deep under ground.
    @keyword soak: Soak the seed before planting it.
    """
    #[...]

def ponder(person, time):
    """
    @param person: Who should think.
    @type person: L{Person} or L{Animal}
    @param time: How long they should think.
    @type time: C{int} or C{float}
    """
    #[...]

class B:
    y = 42
    """@ivar: This is an instance variable."""

class widget(size, weight, age):
    """
    @group Tools: zip, zap, *_tool
    @group Accessors: get_*
    @sort: get_*, set_*, unpack_*, cut
    """
    #[...]

#{ Database access functions

def read(id):
    #[...]

def store(item):
    #[...]

def delete(id):
    #[...]

# groups can't be nested, so a closing marker is not required here.

#{ Web publish functions

def get(request):
    #[...]

def post(request):
    #[...]

#}

5.3   Fields synonyms

Several fields have synonyms, or alternate tags. The following table lists all field synonyms. Field tags are written using epytext markup; if you are using a different markup language, then you should adjust the markup accordingly.

5.4   Module metadata variables

Some module variables are commonly used as module metadata. Epydoc can use the value provided by these variables as alternate form for tags. The following table lists the recognized variables and the tag they replace. Customized metadata variables can be added using the method described in Adding New Fields.

5.5   Adding New Fields

New fields can be defined for the docstrings in a module using the special @newfield tag (or its synonym, @deffield). This tag has the following syntax:

@newfield tag: label [, plural ]

Where tag is the new tag that's being defined; label is a string that will be used to mark this field in the generated output; and plural is the plural form of label, if different.

New fields can be defined in any Python module. If they are defined in a package, it will be possible to use the newly defined tag from every package submodule.

Each new field will also define a metadata variable which can be used to set the field value instead of the tag. For example, if a revision tag has been defined with:

@newfield revision: Revision

then it will be possible to set a value for the field using a module variable:

__revision__ = "1234"

The following example illustrates how the @newfield can be used: Docstring Input Rendered Output

"""
@newfield corpus: Corpus, Corpora
"""

def example():
    """
    @corpus: Bob's wordlist.
    @corpus: The British National Corpus.
    """
    [...]

6.1   reStructuredText

reStructuredText is a markup language that was developed in conjunction with Docutils. In order to parse reStructuredText docstrings, Docutils 0.3 or higher must be installed. If Docutils is not installed, then reStructuredText docstrings will be rendered as plaintext. Docutils can be downloaded from the Docutils SourceForge page.

`somemod.Example`

def fox_speed(size, weight, age):
    """
    Return the maximum speed for a fox.

    :Parameters:
    - `size`: The size of the fox (in meters)
    - `weight`: The weight of the fox (in stones)
    - `age`: The age of the fox (in years)
    """
    #[...]

def fox_speed(size, weight, age):
    """
    Return the maximum speed for a fox.

    :Parameters:
      size
        The size of the fox (in meters)
      weight : float
        The weight of the fox (in stones)
      age : int
        The age of the fox (in years)
    """
    #[...]

.. classtree:: [classes...]
    :dir: up|down|left|right

.. packagetree:: [modules...]
    :dir: up|down|left|right
    :style: uml|tree

.. importgraph:: [modules...]
    :dir: up|down|left|right

.. callgraph:: [functions...]
    :dir: up|down|left|right

.. dotgraph:: [title...]
    :caption: text...
    graph...

>>> def double(x):
...     return x * 2
...
>>> print double(8)
16

.. python::

    def fib(n):
        """Print a Fibonacci series."""
        a, b = 0, 1
        while b < n:
            print b,
            a, b = b, a+b

def fib(n):
    """Print a Fibonacci series."""
    a, b = 0, 1
    while b < n:
        print b,
        a, b = b, a+b

If you want to print a value, you can use
the :epydoc:`apidoc.pp_apidoc()` function.

epydoc                          ->  epydoc-module.html
epydoc.apidoc                   ->  epydoc.apidoc-module.html
epydoc.apidoc.UNKNOWN           ->  epydoc.apidoc-module.html#UNKNOWN
epydoc.apidoc._pp_val           ->  epydoc.apidoc-module.html#_pp_val
epydoc.apidoc.py_src_filename   ->  epydoc.util-module.html#py_src_filename
epydoc.apidoc.pp_apidoc         ->  epydoc.apidoc-module.html#pp_apidoc
epydoc.apidoc._pp_list          ->  epydoc.apidoc-module.html#_pp_list
...                                 ...
...                                 ...

--external-api-file=epydoc:api-objects.txt

--external-api-root=epydoc:http://epydoc.sourceforge.net/api/

def example():
    """
    An :term:`index term` is a term that
    should be included in the index.
    """
    #[...]

6.2   Javadoc

Javadoc is a markup language developed by Sun Microsystems for documenting Java APIs. The epydoc implementation of Javadoc is based on the Javadoc 1.4.2 reference documentation. However, there are likely to be some minor incompatibilities between Sun's implementation and epydoc's. Known incompatibilities include:

• Epydoc does not support the Javadoc block tag @serial.
• Epydoc does not support the following Javadoc inline tags: {@docroot}, {@inheritdoc}, {@value}.
• Epydoc adds many field tags that Sun does not include, such as @var, @type, and @group.

7.1   Command Line Usage

Usage: epydoc.py [ACTION] [options] NAMES...

NAMES...

A list of the Python objects that should be documented. Objects can be specified using dotted names (such as os.path), module filenames (such as epydoc/epytext.py), or package directory names (such as epydoc/). Packages are expanded to include all sub-modules and sub-packages.

options

--config=FILE         A configuration file, specifying additional OPTIONS
                      and/or NAMES.  This option may be repeated.
-o PATH, --output=PATH
                      The output directory.  If PATH does not exist, then it
                      will be created.
-q, --quiet           Decrease the verbosity.
-v, --verbose         Increase the verbosity.
--debug               Show full tracebacks for internal errors.
--simple-term         Do not try to use color or cursor control when
                      displaying the progress bar, warnings, or errors.

Actions:
  --html              Write HTML output.
  --text              Write plaintext output. (not implemented yet)
  --latex             Write LaTeX output.
  --dvi               Write DVI output.
  --ps                Write Postscript output.
  --pdf               Write PDF output.
  --check             Check completeness of docs.
  --pickle            Write the documentation to a pickle file.
  --version           Show epydoc's version number and exit.
  -h, --help          Show this message and exit.  For help on specific
                      topics, use "--help TOPIC".  Use "--help topics" for a
                      list of available help topics

Generation Options:
  --docformat=NAME    The default markup language for docstrings.  Defaults
                      to "epytext".
  --parse-only        Get all information from parsing (don't introspect)
  --introspect-only   Get all information from introspecting (don't parse)
  --exclude=PATTERN   Exclude modules whose dotted name matches the regular
                      expression PATTERN
  --exclude-introspect=PATTERN
                      Exclude introspection of modules whose dotted name
                      matches the regular expression PATTERN
  --exclude-parse=PATTERN
                      Exclude parsing of modules whose dotted name matches
                      the regular expression PATTERN
  --inheritance=STYLE
                      The format for showing inheritance objects.  STYLE
                      should be one of: grouped, listed, included.
  --show-private      Include private variables in the output. (default)
  --no-private        Do not include private variables in the output.
  --show-imports      List each module's imports.
  --no-imports        Do not list each module's imports. (default)
  --show-sourcecode   Include source code with syntax highlighting in the
                      HTML output. (default)
  --no-sourcecode     Do not include source code with syntax highlighting in
                      the HTML output.
  --include-log       Include a page with the process log (epydoc-log.html)

Output Options:
  --name=NAME         The documented project's name (for the navigation
                      bar).
  --css=STYLESHEET    The CSS stylesheet.  STYLESHEET can be either a
                      builtin stylesheet or the name of a CSS file.
  --url=URL           The documented project's URL (for the navigation bar).
  --navlink=HTML      HTML code for a navigation link to place in the
                      navigation bar.
  --top=PAGE          The "top" page for the HTML documentation.  PAGE can
                      be a URL, the name of a module or class, or one of the
                      special names "trees.html", "indices.html", or
                      "help.html"
  --help-file=FILE    An alternate help file.  FILE should contain the body
                      of an HTML file -- navigation bars will be added to
                      it.
  --show-frames       Include frames in the HTML output. (default)
  --no-frames         Do not include frames in the HTML output.
  --separate-classes  When generating LaTeX or PDF output, list each class
                      in its own section, instead of listing them under
                      their containing module.

API Linking Options:
  --external-api=NAME
                      Define a new API document.  A new interpreted text
                      role NAME will be added.
  --external-api-file=NAME:FILENAME
                      Use records in FILENAME to resolve objects in the API
                      named NAME.
  --external-api-root=NAME:STRING
                      Use STRING as prefix for the URL generated from the
                      API NAME.

Graph Options:
  --graph=GRAPHTYPE   Include graphs of type GRAPHTYPE in the generated
                      output.  Graphs are generated using the Graphviz dot
                      executable.  If this executable is not on the path,
                      then use --dotpath to specify its location.  This
                      option may be repeated to include multiple graph types
                      in the output.  GRAPHTYPE should be one of: all,
                      classtree, callgraph, umlclasstree.
  --dotpath=PATH      The path to the Graphviz 'dot' executable.
  --graph-font=FONT   Specify the font used to generate Graphviz graphs.
                      (e.g., helvetica or times).
  --graph-font-size=SIZE
                      Specify the font size used to generate Graphviz
                      graphs, in points.
  --pstat=FILE        A pstat output file, to be used in generating call
                      graphs.

Return Value Options:
  --fail-on-error     Return a non-zero exit status, indicating failure, if
                      any errors are encountered.
  --fail-on-warning   Return a non-zero exit status, indicating failure, if
                      any errors or warnings are encountered (not including
                      docstring warnings).
  --fail-on-docstring-warning
                      Return a non-zero exit status, indicating failure, if
                      any errors or warnings are encountered (including
                      docstring warnings).

7.2   Sample Configuration File

Configuration files, specified using the --config option, may be used to specify both the list of objects to document, and the options that should be used to document them. Configuration files are read using the standard ConfigParser module. The following example configuration file demonstrates the various options that you can set. Lines beginning with # or ; are treated as comments.

[epydoc] # Epydoc section marker (required by ConfigParser)

# The list of objects to document.  Objects can be named using
# dotted names, module filenames, or package directory names.
# Alases for this option include "objects" and "values".
modules: sys, os.path, re

# The type of output that should be generated.  Should be one
# of: html, text, latex, dvi, ps, pdf.
output: html

# The path to the output directory.  May be relative or absolute.
target: html/

# An integer indicating how verbose epydoc should be.  The default
# value is 0; negative values will supress warnings and errors;
# positive values will give more verbose output.
verbosity: 0

# A boolean value indicating that Epydoc should show a tracaback
# in case of unexpected error. By default don't show tracebacks
debug: 0

# If True, don't try to use colors or cursor control when doing
# textual output. The default False assumes a rich text prompt
simple-term: 0


### Generation options

# The default markup language for docstrings, for modules that do
# not define __docformat__.  Defaults to epytext.
docformat: epytext

# Whether or not parsing should be used to examine objects.
parse: yes

# Whether or not introspection should be used to examine objects.
introspect: yes

# Don't examine in any way the modules whose dotted name match this
# regular expression pattern.
#exclude

# Don't perform introspection on the modules whose dotted name match this
# regular expression pattern.
#exclude-introspect

# Don't perform parsing on the modules whose dotted name match this
# regular expression pattern.
#exclude-parse

# The format for showing inheritance objects.
# It should be one of: 'grouped', 'listed', 'included'.
inheritance: listed

# Whether or not to inclue private variables.  (Even if included,
# private variables will be hidden by default.)
private: yes

# Whether or not to list each module's imports.
imports: no

# Whether or not to include syntax highlighted source code in
# the output (HTML only).
sourcecode: yes

# Whether or not to includea a page with Epydoc log, containing
# effective option at the time of generation and the reported logs.
include-log: no


### Output options

# The documented project's name.
#name: Example

# The CSS stylesheet for HTML output.  Can be the name of a builtin
# stylesheet, or the name of a file.
css: white

# The documented project's URL.
#url: http://some.project/

# HTML code for the project link in the navigation bar.  If left
# unspecified, the project link will be generated based on the
# project's name and URL.
#link: <a href="somewhere">My Cool Project</a>

# The "top" page for the documentation.  Can be a URL, the name
# of a module or class, or one of the special names "trees.html",
# "indices.html", or "help.html"
#top: os.path

# An alternative help file.  The named file should contain the
# body of an HTML file; navigation bars will be added to it.
#help: my_helpfile.html

# Whether or not to include a frames-based table of contents.
frames: yes

# Whether each class should be listed in its own section when
# generating LaTeX or PDF output.
separate-classes: no


### API linking options

# Define a new API document.  A new interpreted text role
# will be created
#external-api: epydoc

# Use the records in this file to resolve objects in the API named NAME.
#external-api-file: epydoc:api-objects.txt

# Use this URL prefix to configure the string returned for external API.
#external-api-root: epydoc:http://epydoc.sourceforge.net/api


### Graph options

# The list of graph types that should be automatically included
# in the output.  Graphs are generated using the Graphviz "dot"
# executable.  Graph types include: "classtree", "callgraph",
# "umlclass".  Use "all" to include all graph types
graph: all

# The path to the Graphviz "dot" executable, used to generate
# graphs.
dotpath: /usr/local/bin/dot

# The name of one or more pstat files (generated by the profile
# or hotshot module).  These are used to generate call graphs.
pstat: profile.out

# Specify the font used to generate Graphviz graphs.
# (e.g., helvetica or times).
graph-font: Helvetica

# Specify the font size used to generate Graphviz graphs.
graph-font-size: 10


### Return value options

# The condition upon which Epydoc should exit with a non-zero
# exit status. Possible values are error, warning, docstring_warning
#fail-on: error

7.3   Customizing LaTeX and PDF Output

Epydoc's LaTeX output, and the outputs that are derived from it (dvi, ps, and pdf), can be customized by creating a custom LaTeX style file. To help you create custom stylesheets, a complete description of the specialized LaTeX commands that epydoc uses to generate its output is available here:

• Epydoc LaTeX Style Reference

Additionaly, you may find it useful to look at the builtin style files that epydoc provides:

• LaTeX Style File: epydoc-base.sty
• LaTeX Style File: epydoc-blue.sty
• LaTeX Style File: epydoc-boxes.sty
• LaTeX Style File: epydoc-default.sty
• LaTeX Style File: epydoc-shaded.sty
• LaTeX Style File: epydoc-template.sty

7.4   Warnings and Errors

If epydoc encounters an error while processing a docstring, it issues a warning message that describes the error, and attempts to continue generating documentation. Errors related to epytext are divided into three categories:

Epytext Warnings

are caused by epytext docstrings that contain questionable or suspicious markup. Epytext warnings do not prevent the docstring in question from being parsed.

Field Warnings

are caused by epytext docstrings containing invalid fields. The contents of the invalid field are generally ignored.

Epytext Errors

are caused by epytext docstrings that contain invalid markup. Whenever an epytext error is detected, the docstring in question is treated as a plaintext docstring.

The following sections list and describe the warning messages that epydoc can generate. They are intended as a reference resource, which you can search for more information and possible causes if you encounter an error and do not understand it. These descriptions are also available in the epydoc(1) man page.