Provided by: python-epydoc_3.0.1+dfsg-4_all bug

NAME

       epydoc - generate API documentation from Python docstrings

SYNOPSIS

       epydoc [action] [options] names...

DESCRIPTION

       epydoc  generates  API  documentation  for  Python  modules  and  packages, 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
       plaintext.  Currently, epydoc supports two basic output formats: HTML and LaTeX.

       The  HTML API documentation produced by epydoc consists of a set of HTML files, including:
       an API documentation page for each class and module; a syntax-highlighted source code page
       for  each  module;  an  identifier  index  page;  a help page; and a frames-based table of
       contents.  When appropriate, epydoc will also  generate  index  pages  for  bugs,  defined
       terms, and to-do items; a class hierarchy page; and a package hierarchy page.

       The  LaTeX API documentation produced by epydoc consists of a main LaTeX file, and a LaTeX
       file for each module.  If you use --dvi, --ps, or --pdf , then epydoc will invoke external
       commands  to  convert the LaTeX output to the requested format.  Note that the LaTeX files
       containing the documentation for  individual  modules  can  be  included  as  chapters  or
       sections  of  other  LaTeX  documents,  using  the LaTeX \include command.  If you wish to
       include individual classes in other  LaTeX  documents,  then  use  the  --separate-classes
       option to produce a separate LaTeX file for each class.

       epydoc  can  also be used to check the completeness of the API documentation.  By default,
       it checks that every public package, module, class, method, and function has  a  docstring
       description.  The --tests option can be used to specify additional tests to perform.

OPTIONS

       Epydoc's  options  are  divided  into  six  categories: basic options, actions, generation
       options, output options, graph options, and return value options.

       BASIC OPTIONS

           names...
                  The list of objects that should be documented.  Objects can be specified  using
                  Python  dotted  names (such as os.path), filenames (such as epydoc/epytext.py),
                  or directory names (such as epydoc/).  Directory names  specify  packages,  and
                  are  expanded  to  include  all  sub-modules  and sub-packages.  If you wish to
                  exclude  certain  sub-modules  or  sub-packages,  use  the   --exclude   option
                  (described below).

           --config file
                  A  configuration  file,  specifying additional optionsand/ornames.  This option
                  may be repeated.

           --q, --quiet, --v, --verbose
                  Produce quite (or  verbose)  output.   If  used  multiple  times,  this  option
                  produces successively more quiet (or verbose) output.

           --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.  [default]

           --latex   Write LaTeX output.

           --dvi     Write DVI output.

           --ps      Write Postscript output.

           --pdf     Write Adobe Acrobat (pdf) output.

           --check   Perform completeness checks on the documentation.

           --pickle  Write the documentation to a pickle file.

       GENERATION OPTIONS

           --docformat format
                  Set the default value for __docformat__ to format.  __docformat__ is  a  module
                  variable  that  specifies  the  markup language for the docstrings in a module.
                  Its value consists of the name of a markup language, optionally followed  by  a
                  language  code  (such  as  en for English).  For a list of the markup languages
                  currently recognized by epydoc, run epydoc --help docformat.

           --parse-only
                  Gather all information about the documented objects  by  parsing  the  relevant
                  Python  source  code;  in  particular,  do  not  use  introspection  to  gather
                  information about the documented objects.  This  option  should  be  used  when
                  epydoc  is  run  on  untrusted  code;  or  on code that can not be introspected
                  because of missing dependencies, or because importing it would cause  undesired
                  side-effects.

           --introspect-only
                  Gather  all  information  about  the  documented  objects  by introspection; in
                  particular, do not gather information by parsing  the  object's  Python  source
                  code.

           --exclude PATTERN
                  Do  not  document  any  object  whose name matches the given regular expression
                  pattern.

           --exclude-introspect PATTERN
                  Do not use introspection to gather information  about  any  object  whose  name
                  matches the given regular expression.

           --exclude-parse PATTERN
                  Do  not  use  Python source code parsing to gather information about any object
                  whose name matches the given regular expression.

           --inheritance format
                  The format that should be used to display  inherited  methods,  variables,  and
                  properties  in  the  generated  "summary" tables.  If format is "grouped," then
                  inherited objects are gathered into groups, based on which class that they  are
                  inherited  from.  If format is "listed," then inherited objects are listed in a
                  short list at the end of the summary table.   If  format  is  "included,"  then
                  inherited  objects are mixed in with non-inherited objects.  The default format
                  for HTML output is "grouped."

           --show-private, --no-private
                  These options control whether documentation is generated for  private  objects.
                  By default, the generated documentation includes private objects, and users can
                  choose whether to view private objects or not, by clicking  on  "show  private"
                  and  "hide  private"  links.  But if you want to discourage users from directly
                  accessing private objects, then you may prefer not  to  generate  documentation
                  for private objects.

           --show-imports, --no-imports
                  These  options  control  whether  module  imports are included in the generated
                  documentation.  By default, imports are not included.

           --show-sourcecode, --no-sourcecode
                  These options control whether or not epydoc should generate  syntax-highlighted
                  pages containing the souce code of each module in the HTML output.  By default,
                  the sourcecode pages are generated.

           --include-log
                  Generate an HTML page epydoc-log.html containing all error and warning messages
                  that are generated by epydoc, and include it in the generated output.

       OUTPUT OPTIONS

           -o dir, --output dir
                  The  output  directory.  If dir does not exist, then it will be created.  If no
                  output directory is specified, then the action name (e.g., html or pdf).  html

           -c sheet, --css sheet
                  CSS stylesheet for HTML output files.  If sheet is a file, then the  stylesheet
                  is  copied  from  that  file;  otherwise,  sheet  is  taken to be the name of a
                  built-in stylesheet.  For a list of the built-in stylesheets, run epydoc --help
                  css.   If  a  CSS  stylesheet  is not specified, then the default stylesheet is
                  used.

           -n name, --name name
                  The name of the project whose documentation is being generated.

           -u url, --url url
                  The URL of the project's homepage.

           --navlink html
                  HTML code for the homepage link on the HTML navigation bar.  If this HTML  code
                  contains  any hyperlinks (<a href=...>), then it will be inserted verbatim.  If
                  it does not contain any hyperlinks,  and  a  project  url  is  specified  (with
                  --url), then a hyperlink to the specified URL is added to the link.

           --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, --no-frames
                  These options control whether HMTL output will include a frames-based table  of
                  contents page.  By default, the frames-based table of contents is included.

           --separate-classes
                  In  the  LaTeX  output,  describe  each  class  in  a  separate  section of the
                  documentation, instead  of  including  them  in  the  documentation  for  their
                  modules.   This creates a separate LaTeX file for each class, so it can also be
                  useful if you want to include the documentation  for  one  or  two  classes  as
                  sections of your own LaTeX document.

       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, or umlclasstree.

           --dotpath path
                  The path to the Graphviz dot executable.

           --graph-font font
                  The  name  of  the  font used to generate Graphviz graphs.  (e.g., helvetica or
                  times).

           --graph-font-size size
                  The size of the font 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).

HTML FILES

       The HTML API documentation produced by epydoc consists of the following files:

       OBJECT DOCUMENTATION PAGES

           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  syntax-highlighted  page containing the Python source code for module.  This
                  page includes links back to the API documentation pages.

           module-tree.html
                  The module hierarchy.

           class-tree.html
                  The class hierarchy.  This page is only generated if  at  least  one  class  is
                  documented.

       INDICES

           identifier-index.html
                  An  index of all documented identifiers.  If the identifier index contains more
                  than 3,000 entries, then it will be split into separate pages for each  letter,
                  named identifier-index-a.html, identifier-index-b.html, etc.

           term-index.html
                  An  index  of  all  explicitly  marked  definitional  terms.  This page is only
                  generated if at least one definition term is marked in a formatted docstring.

           bug-index.html
                  An index of all explicitly marked @bug fields.  This page is only generated  if
                  at least one @bug field is listed in a formatted docstring.

           todo-index.html
                  An index of all explicitly marked @todo fields.  This page is only generated if
                  at least one @todo field is listed in a formatted docstring.

           changed-index.html
                  An index of all explicitly marked @changed fields.  This page is only generated
                  if at least one @changed field is listed in a formatted docstring.

           deprecated-index.html
                  An  index  of  all  explicitly  marked  @deprecated  fields.  This page is only
                  generated if at least one @deprecated field is listed in a formatted docstring.

           since-index.html
                  An index of all explicitly marked @since fields.  This page is  only  generated
                  if at least one @since field is listed in a formatted docstring.

       FRAMES-BASED TABLE OF CONTENTS

           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.

       OTHER PAGES

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

           redirect.html
                  This  page  uses  javascript  to  translate dotted names to their corresponding
                  URLs.    For   example,   in   epydoc's   documentation,   loading   the   page
                  <redirect.html#epydoc.apidoc.DottedName>   will   automatically   redirect  the
                  browser to <epydoc.apidoc-module.html#DottedName>.

           epydoc.css
                  The CSS stylesheet used to display all HTML pages.

           epydoc.js
                  A javascript file used to define javascript functions used by epydoc.

           epydoc-log.html
                  A page containing a log of all warnings  and  errors  that  were  generated  by
                  epydoc, along with a table listing all of the options that were used.

LATEX FILES

       The LaTeX API documentation produced by epydoc consists of the following files:

           api.pdf
                  An  Adobe  Acrobat  (pdf) file containing the complete API documentation.  This
                  file is only generated if you use the --pdf option.

           api.tex
                  The top-level LaTeX file.  This file imports the other LaTeX files, to create a
                  single unified document.

           api.dvi
                  A  dvi  file  containing  the  complete  API  documentation.  This file is only
                  generated if you use the --dvi option, the --ps option, or the --pdf option.

           api.ps A postscript file containing the complete API documentation.  This file is only
                  generated if you use the --ps option or the --pdf option.

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

           class-class.tex
                  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.
                  These class documentation files are  only  created  if  the  --separate-classes
                  option  is used; otherwise, the documentation for each class is included in its
                  module's documentation file.

DIAGNOSTICS

       EPYTEXT MARKUP WARNING MESSAGES
           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.  Epydoc can generate the following 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.
                  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.

           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
           Field warnings are caused by docstrings containing invalid fields.   The  contents  of
           the  invalid  field  are  generally  ignored.  Epydoc can generate the following 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.

EXAMPLES

       epydoc -n epydoc -u http://epydoc.sf.net epydoc/
              Generate  the  HTML  API  documentation  for  the  epydoc  package  and  all of its
              submodules, and write the output  to  the  html  directory.   In  the  headers  and
              footers,  use  epydoc  as the project name, and http://epydoc.sf.net as the project
              URL.

       epydoc --pdf -n epydoc epydoc/
              Generate the LaTeX API  documentation  for  the  epydoc  package  and  all  of  its
              submodules, and write the output to the latex directory.

EXIT STATUS

       0      Successful program execution.

       1      Usage error.

       2      Epydoc  generated  an  error  or  warning,  and one of the options --fail-on-error,
              --fail-on-warning, or --fail-on-docstring-warning was specified.

       other  Internal error (Python exception).

AUTHOR

       Epydoc was written by Edward Loper.  This man page was originally written by Moshe  Zadka,
       and is currently maintained by Edward Loper.

BUGS

       Report bugs to <edloper@users.sourceforge.net>.

SEE ALSO

       epydocgui(1)

       The epydoc webpage
              <http://epydoc.sourceforge.net>

       The epytext markup language manual
              <http://epydoc.sourceforge.net/epytext.html>

                                                                                        EPYDOC(1)