References
==========

.. $Id: manual-reference.txt 1772 2008-02-24 03:43:33Z edloper $

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
 .. parsed-literal::

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


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.

.. _ConfigParser: http://docs.python.org/lib/module-ConfigParser.html

.. parsed-literal::

    **[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**


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 <epydoc-latex-demo.html>`__

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

.. include:: epydoc-style-list.txt

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.


Epytext Warnings
''''''''''''''''

Possible mal-formatted field item.
    Epytext detected a line that looks like a field item, but is not correctly
    formatted. This typically occurs when the trailing colon (``:``) is not
    included in the field tag.

Possible heading typo.
    Epytext detected a pair of lines that looks like a heading, but the number
    of underline characters does not match the number of characters in the
    heading. The number of characters in these two lines must match exactly for
    them to be considered a heading.


Field Warnings
''''''''''''''

``@param`` for unknown parameter *param*.
    A ``@param`` field was used to specify the type for a parameter that is not
    included in the function's signature. This is typically caused by a typo in
    the parameter name.

*tag* did not expect an argument.
    The field tag *tag* was used with an argument, but it does not take one.

*tag* expected an argument.
    The field tag *tag* was used without an argument, but it requires one.

``@type`` for unknown parameter *param*.
    A ``@type`` field was used to specify the type for a parameter that is not
    included in the function's signature. This is typically caused by a typo in
    the parameter name.

``@type`` for unknown variable *var*.
    A ``@type`` field was used to specify the type for a variable, but no
    other information is known about the variable. This is typically caused
    by a typo in the variable name.

Unknown field tag *tag*.
    A docstring contains a field with the unknown tag *tag*.

Redefinition of *field*.
    Multiple field tags define the value of field in the same docstring, but
    field can only take a single value.


Epytext Errors
''''''''''''''

Bad link target.
    The target specified for an inline link contruction (L{...}) is not
    well-formed. Link targets must be valid Python identifiers.

Bad uri target.
    The target specified for an inline uri contruction (``U{...}``) is not
    well-formed. This typically occurs if inline markup is nested inside the
    URI target.

Fields must be at the top level.
    The list of fields (``@param``, etc.) is contained by some other block
    structure (such as a list or a section).

Fields must be the final elements in an epytext string.
    The list of fields (``@param``, etc.) is not at the end of a docstring.

Headings must occur at top level.
    The heading is contianed in some other block structure (such as a list).

Improper doctest block indentation.
    The doctest block dedents past the indentation of its initial prompt line.

Improper heading indentation.
    The heading for a section is not left-aligned with the paragraphs in the
    section that contains it.

Improper paragraph indentation.
    The paragraphs within a block are not left-aligned. This error is often
    generated when plaintext docstrings are parsed using epytext.

Invalid escape.
    An unknown escape sequence was used with the inline escape construction
    (``E{...}``).

Lists must be indented.
    An unindented line immediately following a paragraph starts with a list
    bullet. Epydoc is not sure whether you meant to start a new list item, or
    meant for a paragraph to include a word that looks like a bullet. If you
    intended the former, then indent the list. If you intended the latter, then
    change the word-wrapping of the paragraph, or escape the first character of
    the word that looks like a bullet.

Unbalanced '``{``'.
    The docstring contains unbalanced braces. Epytext requires that all braces
    must be balanced. To include a single unbalanced brace, use the escape
    sequences ``E{lb}`` (left brace) and ``E{rb}`` (right brace).
    
Unbalanced '``}``'.
    The docstring contains unbalanced braces. Epytext requires that all braces
    must be balanced. To include a single unbalanced brace, use the escape
    sequences ``E{lb}`` (left brace) and ``E{rb}`` (right brace).

Unknown inline markup tag.
      An unknown tag was used with the inline markup construction (``x{...}``).

Wrong underline character for heading.
    The underline character used for this section heading does not indicate an
    appopriate section level. The '``=``' character should be used to underline
    sections; '``-``' for subsections; and '``~``' for subsubsections.
