[Epydoc-commits] SF.net SVN: epydoc: [1516] trunk/epydoc/man/epydoc.1

[<ed...@us...>]

Revision: 1516
          http://svn.sourceforge.net/epydoc/?rev=1516&view=rev
Author:   edloper
Date:     2007-02-15 21:37:14 -0800 (Thu, 15 Feb 2007)

Log Message:
-----------
- Updated the epydoc man page

Modified Paths:
--------------
    trunk/epydoc/man/epydoc.1

Modified: trunk/epydoc/man/epydoc.1
===================================================================
--- trunk/epydoc/man/epydoc.1	2007-02-16 05:36:58 UTC (rev 1515)
+++ trunk/epydoc/man/epydoc.1	2007-02-16 05:37:14 UTC (rev 1516)
@@ -9,56 +9,11 @@
 .SH SYNOPSIS
 .HP 7
 .B epydoc
-.RB [ \-\-html " | " \-\-latex " | " \-\-dvi " | " \-\-ps " | " \-\-pdf ]
-.RB [ \-o
-.IR dir ]
-.RB [ \-\-docformat
-.IR format ]
-.RB [ \-\-name
-.IR name ]
-.RB [ \-u
-.IR url ]
-.RB [ \-t
-.IR  page ]
-.RB [ \-c
-.IR sheet ]
-.RB [ \-\-private\-css
-.IR sheet ]
-.RB [ \-\-navlink
-.IR html ]
-.RB [ \-\-help\-file
-.IR file ]
-.RB [ \-\-show\-private ]
-.RB [ \-\-no\-private ]
-.RB [ \-\-inheritance
-.IR style ]
-.RB [ \-\-show\-imports ]
-.RB [ \-\-ignore\-param\-mismatch ]
-.RB [ \-\-separate-classes ]
-.RB [ \-q ]
-.RB [ \-v ]
-.IB modules ...
-.HP 7
-.B epydoc
-.B \-\-check
-.RB [ \-\-tests
-.BR tests ]
-.RB [ \-\-show\-private ]
-.RB [ \-\-ignore\-param\-mismatch ]
-.RB [ \-q ]
-.RB [ \-v ]
-.IB modules ...
-.PP
-.B epydoc \-h
-.RI [ topic ]
-.PP
-.B epydoc \-V
+.RB [ action ]
+.RB [ options ]
+.IB names...
 .\" ================== DESCRIPTION ====================
 .SH DESCRIPTION
-.B This man page is somewhat outdated while epydoc is in alpha; run
-"epydoc --help"
-.B for a complete option list.
-.PP
 .B epydoc
 generates API documentation for Python modules and packages, based on
 their docstrings.  A lightweight markup language called
@@ -71,21 +26,24 @@
 .PP
 The HTML API documentation produced by 
 .B epydoc
-consists of a set of HTML files.  Two subdirectories are created for
-the public and private documentation.  Within each subdirectory,
-every class and module is documented in its own file.  An index file,
-a trees file, a help file, and a frames-based table of contents are
-also created.
+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,
+.B epydoc
+will also generate
+index pages for bugs, defined terms, and to-do items; 
+a class hierarchy page; and a package hierarchy page.
 .PP
 The LaTeX API documentation produced by
 .B epydoc
 consists of a main LaTeX file, and a LaTeX file for each module.  If
-you use the
+you use 
 .BR \-\-dvi ,
 .BR \-\-ps ,
 or
-.B \-\-pdf
-options, then
+.B \-\-pdf ,
+then
 .B epydoc
 will invoke external commands to convert the LaTeX output to the
 requested format.  Note that the LaTeX files containing the
@@ -97,8 +55,6 @@
 .B \-\-separate\-classes
 option to produce a separate LaTeX file for each class.
 .PP
-.B LaTeX API output is not yet implemented in this alpha release.
-.PP
 .B epydoc
 can also be used to check the completeness of the API documentation.
 By default, it checks that every public package, module, class,
@@ -106,89 +62,83 @@
 .B \-\-tests
 option can be used to specify additional tests to perform.
 .PP
-.B Completeness checking is not yet implemented in this alpha release.
 .\" ================== OPTIONS ====================
 .SH OPTIONS
-Options are divided into five categories: action selection options;
-HTML documentation generation options; LaTeX documentation generation
-options; documentation checking options; and other options.  All
-options must preceed the list of modules.
+Epydoc's options are divided into six categories: basic options,
+actions, generation options, output options, graph options, and return
+value options.
 .PP
-.B ACTION SELECTION OPTIONS
+.\"--------------------------------------------------
+.B BASIC OPTIONS
 .RS 4
 .TP
-.B \-\-html
-Generate HTML output. (default)
+.IR names ...
+The list of objects that should be documented.  Objects can be
+specified using Python dotted names (such as
+.BR os.path ),
+filenames (such as
+.BR epydoc/epytext.py ),
+or directory names (such as
+.BR 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 
+.B --exclude
+option (described below).
+.\" --config
 .TP
-.B \-\-latex
-Generate LaTeX output.
-.B (Not yet implemented in this alpha release)
+.BI "\-\-config " file
+A configuration file, specifying additional
+.BR options "and/or" names "."
+This option may be repeated.
+.\" --quiet
 .TP
-.B \-\-dvi
-Generate dvi output.  This option first creates LaTeX output, and then
-uses
-.B latex
-and
-.B makeindex
-to convert the LaTeX files into a single
-.B dvi
-file.
-.B (Not yet implemented in this alpha release)
+.B \-\-q, \-\-quiet, \-\-v, \-\-verbose
+Produce quite (or verbose) output.  If used multiple times, this
+option produces successively more quiet (or verbose) output.
+.\" --debug
 .TP
-.B \-\-ps
-Generate postscript output.  This option first creates LaTeX output,
-and then uses
-.BR latex ,
-.BR makeindex ,
-and
-.BR dvips
-to convert the LaTeX files into a single postscript file.
-.B (Not yet implemented in this alpha release)
+.B \-\-debug
+Show full tracebacks for internal errors.
+.\" --simple-term
 .TP
+.B \-\-simple\-term
+Do not try to use color or cursor control when displaying the progress
+bar, warnings, or errors.
+.RE
+.PP
+.\"--------------------------------------------------
+.B ACTIONS
+.RS 4
+.TP 10
+.B \-\-html
+Write HTML output.
+.B [default]
+.TP 10
+.B \-\-latex
+Write LaTeX output.
+.TP 10
+.B \-\-dvi
+Write DVI output.
+.TP 10
+.B \-\-ps
+Write Postscript output.
+.TP 10
 .B \-\-pdf
-Generate Adobe Acrobat
-.RB ( pdf )
-output.  This option first creates LaTeX output, and then uses
-.BR latex ,
-.BR makeindex ,
-.BR dvips ,
-and
-.BR ps2pdf
-to convert the LaTeX files into a single
-.B pdf
-file.
-.B (Not yet implemented in this alpha release)
-.TP
+Write Adobe Acrobat (pdf) output. 
+.TP 10
 .B \-\-check
 Perform completeness checks on the documentation.
-.B (Not yet implemented in this alpha release)
+.TP 10
+.B \-\-pickle
+Write the documentation to a pickle file.
 .RE
 .PP
-.B HTML DOCUMENTATION GENERATION OPTIONS 
+.\"--------------------------------------------------
+.B GENERATION OPTIONS
 .RS 4
+.\" --docformat
 .TP
-.IR modules ...
-The list of the modules that should be documented.  Modules can be
-specified using module names (such as
-.BR os.path ),
-filenames (such as
-.BR epydoc/epytext.py ),
-or directory names (such as
-.BR epydoc/ ).
-Directory names specify packages, and are expanded to include
-all sub-modules and sub-packages.
-.TP
-.BI "\-c " sheet ", \-\-css " sheet
-CSS stylesheet for HTML files containing public API documentation.  If
-.I sheet
-is a file, then the stylesheet is copied from that file; otherwise,
-.I sheet
-is taken to be the name of a built\-in stylesheet.  For a list of
-the built\-in stylesheets, run
-.BR "epydoc \-\-help css" .
-If a CSS stylesheet is not specified, then the default stylesheet is
-used.
-.TP
 .BI "\-\-docformat " format
 Set the default value for
 .B __docformat__
@@ -202,19 +152,43 @@
 for English).  For a list of the markup languages currently recognized
 by epydoc, run
 .BR "epydoc \-\-help docformat" .
+.\" --parse-only
 .TP
-.BI "\-\-help\-file " file
-A file containing the body of the help page for the HTML output.
-Navigation bars will be added at the top and bottom of this help file.
-If no file is specified, then a default help file is used.
+.BI "\-\-parse-only"
+Gather all information about the documented objects by parsing the
+relevant Python source code; in particular, do
+.I 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
 .TP
-.B \-\-ignore\-param\-mismatch
-Do not issue warnings when a method's parameters do not match the
-parameters of the base class method that it overrides.
+.BI "\-\-introspect-only"
+Gather all information about the documented objects by introspection;
+in particular, do
+.I not
+gather information by parsing the object's Python source code.
+.\" --exclude=PATTERN
 .TP
+.BI "\-\-exclude " PATTERN
+Do not document any object whose name matches the given regular
+expression pattern.
+.\" --exclude-introspect=PATTERN
+.TP
+.BI "\-\-exclude-introspect " PATTERN
+Do not use introspection to gather information about any object whose
+name matches the given regular expression.  
+.\" --exclude-parse=PATTERN
+.TP
+.BI "\-\-exclude-parse " PATTERN
+Do not use Python source code parsing to gather information about any
+object whose name matches the given regular expression.
+.\" --inheritance
+.TP
 .BI "\-\-inheritance " format
 The format that should be used to display inherited methods,
-variables, and properties in the "summary" tables.
+variables, and properties in the generated "summary" tables.
 If
 .I format
 is "grouped," then inherited objects are gathered into groups, based
@@ -225,274 +199,165 @@
 .I 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
 .TP
-.BI "\-\-name " name
-The name of the project whose documentation is being generated.  This
-is used in the index page's title, and in the help page.  It is also
-used to create the homepage link on the navigation bar, if the
-.B \-\-navlink
-option is not used.
+.B \-\-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
 .TP
-.BI "\-\-navlink " html
-HTML code for the homepage link on the navigation bar.  If this HTML
-code contains any hyperlinks
-.RB ( "<a href=...>" ),
-then it will be inserted verbatim.  If
-it does not contain any hperlinks, and a project url is specified
-(with
-.BR \-\-url ),
-then a hyperlink to the specified URL is added to the link.
+.B \-\-show-imports, \-\-no\-imports
+These options control whether module imports are included in the
+generated documentation.  By default, imports are not included.
+.\" --show-sourcecode
 .TP
-.B \-\-no\-frames
-Do not display the frames-based table of contents on the main
-API documentation page
-.RB ( index.html ).
-This option just changes the default view; the user can still access
-the frames-based table of contents by clicking on
-.B frames
-in the navigation bar.
+.B \-\-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
 .TP
+.B \-\-include\-log
+Generate an HTML page
+.B epydoc\-log.html
+containing all error and warning messages that are generated by
+epydoc, and include it in the generated output.
+.RE
+.PP
+.\"--------------------------------------------------
+.B OUTPUT OPTIONS
+.RS 4
+.\" --output
+.TP
 .BI "\-o " dir ", \-\-output " dir
-The output directory for HTML files.  By default, HTML files are
-written to the
+The output directory.  If
+.B dir
+does not exist, then it will be created.  If no output directory is
+specified, then the action name (e.g.,
+.BR html " or " pdf ).
 .B html
-directory.
+.\" --css
 .TP
-.B \-\-show\-private, \-\-no\-private
-These options control whether documentation is generated for private
-objects.  By default, HTML 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.  The
-.B \-\-no\-private
-option is also useful if you want to generate documentation more
-quickly, since epydoc will only need to produce half as many HTML
-pages.
-.TP
-.BI "\-\-private\-css " sheet
-CSS stylesheet for HTML files containing private API documentation.
-If
+.BI "\-c " sheet ", \-\-css " sheet
+CSS stylesheet for HTML output files.  If
 .I sheet
-is a file, then the stylesheet is copied from that file;
-otherwise, 
+is a file, then the stylesheet is copied from that file; otherwise,
 .I sheet
-is taken to be the name of a built\-in stylesheet.  For a list of the
-built\-in stylesheets, run 
+is taken to be the name of a built\-in stylesheet.  For a list of
+the built\-in stylesheets, run
 .BR "epydoc \-\-help css" .
-If a CSS stylesheet is not specified, then epydoc
-copies the stylesheet for public API documentation (see
-.BR \-\-css ).
+If a CSS stylesheet is not specified, then the default stylesheet is
+used.
+.\" --name
 .TP
-.B \-q, \-\-quiet
-Produce quiet output.  If
-.B \-q
-is used multiple times, it produces successively more quiet output (by
-suppressing warning messages).
+.BI "\-\-name " name
+The name of the project whose documentation is being generated.  
+.\" --url
 .TP
-.B \-\-show\-imports
-Include a list of the classes, functions, and variables that each
-module imports on the module documentation pages.
-.TP
-.BI "\-t " page ", \-\-top " page
-The top page for the documentation. 
-.I page
-can be the name of a documented module or a class; the name of a file
-containing a documented module; an absolute URL (starting
-with "http:"); or one of the special names
-.BR trees.html ,
-.BR indices.html ", or"
-.BR help.html ,
-indicating the corresponding API documentation pages.
-.TP
 .BI "\-u " url ", \-\-url " url
-The URL of the project's homepage.  This URL is used by the homepage
-link on the navigation bar.
+The URL of the project's homepage.
 .TP
-.B \-v, \-\-verbose
-Produce verbose output.  If
-.B \-v
-is used multiple times, it produces successively more verbose output.
-.RE
-.PP
-.B LATEX DOCUMENTATION GENERATION OPTIONS
-.RS 4
-LaTeX documentation generation options are used when producing LaTeX,
-postscript (ps), or pdf output.
+.\" --navlink
 .TP
-.IR modules ...
-The list of the modules that should be documented.  Modules can be
-specified using module names (such as
-.BR os.path ),
-filenames (such as
-.BR epydoc/epytext.py ),
-or directory names (such as
-.BR epydoc/ ).
-Directory names specify packages, and are expanded to include
-all sub-modules and sub-packages.
+.BI "\-\-navlink " html
+HTML code for the homepage link on the HTML navigation bar.  If this
+HTML code contains any hyperlinks
+.RB ( "<a href=...>" ),
+then it will be inserted verbatim.  If
+it does not contain any hyperlinks, and a project url is specified
+(with
+.BR \-\-url ),
+then a hyperlink to the specified URL is added to the link.
+.\" --help-file
 .TP
-.B \-\-builtins
-Add the builtin modules (as defined by sys.builtin_module_names) to
-the list of modules to document.
+.BI "\-\-help\-file " file
+An alternate help file.
+.B file
+should contain the body of an HTML file -- navigation bars will be
+added to it.
+.\" --show-frames, --no-frames
 .TP
-.BI "\-\-docformat " format
-Set the default value for
-.B __docformat__
-to
-.IR format .
-.B __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
-.B en
-for English).  For a list of the markup languages currently recognized
-by epydoc, run
-.BR "epydoc \-\-help docformat" .
+.B \-\-show\-frames, \-\-no\-frames
+These options control whether HMTL output will include a frames-base
+table of contents page.  By default, the frames-based table of
+contents is included.
+.\" --separate-classes
 .TP
-.B \-\-ignore\-param\-mismatch
-Do not issue warnings when a method's parameters do not match the
-parameters of the base class method that it overrides.
-.TP
-.BI "\-\-inheritance " format
-The format that should be used to display inherited methods,
-variables, and properties.
-If
-.I format
-is "grouped," then inherited objects are gathered into groups, based
-on which class that they are inherited from.  If
-.I format
-is "listed," then inherited objects are listed in a short list at the
-end of their section.  If
-.I format
-is "included," then inherited objects are mixed in with non-inherited
-objects.  The default format for LaTeX output is "listed."
-.TP
-.BI "\-\-name " name
-The name of the project whose documentation is being generated.  This
-is used on the title page, in the page header, and in the pdf metadata.
-.TP
-.BI "\-o " dir ", \-\-output " dir
-The output directory.  By default, HTML files are
-written to the
-.B html
-directory, and LaTeX files are written to the
-.B latex
-directory.
-.TP
-.B \-\-show\-private, \-\-no\-private
-These options control whether documentation is generated for private
-objects.  By default, LaTeX output only includes documentation for
-public objects.
-.TP
-.B \-q, \-\-quiet
-Produce quiet output.  If
-.B \-q
-is used multiple times, it produces successively more quiet output (by
-suppressing warning messages).
-.TP
 .B \-\-separate\-classes
-Describe all classes 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.
-.TP
-.B \-v, \-\-verbose
-Produce verbose output.  If
-.B \-v
-is used multiple times, it produces successively more verbose output.
+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.
 .RE
 .PP
-.B DOCUMENTATION COMPLETENESS CHECKING OPTIONS
+.\"--------------------------------------------------
+.B GRAPH OPTIONS
 .RS 4
-The
-.B \-\-check
-option is used to perform completeness checks on the documentation of
-your project.  By default, epydoc checks to make sure that all public
-objects have docstrings.  Additional checks can be added with the
-.B \-\-tests
-option.
+.\" --graph
 .TP
-.IR modules ...
-The list of the modules whose documentation should be checked.
-Modules can  be specified using module names (such as
-.BR os.path ),
-filenames (such as
-.BR epydoc/epytext.py ),
-or directory names (such as
-.BR epydoc/ ).
-Directory names specify packages, and are expanded to include
-all sub-modules and sub-packages.
+.BI "\-\-graph " graphtype
+Include graphs of type
+.B graphtype
+in the generated output.  Graphs are generated using the Graphviz dot
+executable.  If this executable is not on the path, then use
+.B \-\-dotpath
+to specify its location.  This option may be repeated to include
+multiple graph types in the output.
+.B graphtype
+should be one of:
+.BR all ", " classtree ", " callgraph ", or " umlclasstree .
+.\" --dotpath
 .TP
-.B \-\-ignore\-param\-mismatch
-Do not issue warnings when a method's parameters do not match the
-parameters of the base class method that it overrides.
+.BI "\-\-dotpath " path
+The path to the Graphviz
+.BR dot
+executable.
+.\"--graph-font
 .TP
-.B \-\-private
-Perform checks on private objects
+.BI "--graph-font " font
+The name of the font used to generate Graphviz graphs.  (e.g.,
+helvetica or times).
+.\"--graph-font-size
 .TP
-.B \-q, \-\-quiet
-Produce quiet output.  If
-.B \-q
-is used multiple times, it produces successively more quiet output (by
-suppressing warning messages).
+.BI "--graph-font-size " size
+The size of the font used to generate Graphviz graphs, in points.
+.\"--pstat
 .TP
-.BI "\-\-tests " tests  ", \-\-checks " tests
-Perform additional tests on the documentation.  For a list of the
-additional tests that are available, run
-.BR "epydoc --help tests" .
-.TP
-.B \-v, \-\-verbose
-Produce verbose output.  If
-.B \-v
-is used multiple times, it produces successively more verbose output.
+.BI "--pstat " file
+A pstat output file, to be used in generating call graphs.
 .RE
 .PP
-.B OTHER OPTIONS
+.\"--------------------------------------------------
+.B RETURN VALUE OPTIONS
 .RS 4
+.\" --fail-on-error
 .TP
-.B \-h, \-\-help, \-\-usage, \-?
-Display a usage message.
+.B \-\-fail\-on\-error
+Return a non\-zero exit status, indicating failure, if any errors are
+encountered.
+.\" --fail-on-warning
 .TP
-.BI "\-h " topic ", \-\-help " topic
-Display information about a specific topic.  Currently,
-information is available about the following topics:
-.BR css ", " version ", and " usage .
+.B \-\-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
 .TP
-.B \-V, \-\-version
-Print the version of Epydoc.
+.B \-\-fail\-on\-docstring\-warning
+Return a non\-zero exit status, indicating failure, if any errors or
+warnings are encountered (including docstring warnings).
 .RE
-.\" ================== EXAMPLES ====================
-.SH EXAMPLES
-.TP
-.BR "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
-.B html
-directory.  In the headers and footers, use
-.B epydoc
-as the project name, and
-.B http://epydoc.sf.net
-as the project URL.
-.TP
-.BR "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
-.B latex
-directory.
-.TP
-.BR "epydoc \-o "api " \-\-css " blue " \-\-private\-css " "green sys"
-Generate API documentation for the
-.B sys
-module, and write the output to the
-.B api
-directory.  Use different stylesheets for the public and private
-versions of the documentation.
 .\" ================== HTML FILES ====================
 .SH HTML FILES
 The HTML API documentation produced by 
 .B epydoc
 consists of the following files:
+.PP
+.B OBJECT DOCUMENTATION PAGES
 .RS 4
 .TP
 .B index.html
@@ -524,16 +389,78 @@
 or
 .BR array.ArrayType .
 .TP
-.B trees.html
-The module and class hierarchies.
+.IB module \-pysrc.html
+A syntax-highlighted page containing the Python source code for
+.IR module .
+This page includes links back to the API documentation pages.
 .TP
-.B indices.html
-The term and identifier indices.
+.B module-tree.html
+The module hierarchy.
 .TP
-.B help.html
-The help page for the project.  This page explains how to use and
-navigate the webpage produced by epydoc.
+.B class-tree.html
+The class hierarchy.  This page is only generated if at least one
+class is documented.
+.PP
+.RE
+.B INDICES
+.RS 4
 .TP
+.B 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
+.BR identifier-index-a.html ,
+.BR identifier-index-b.html ", etc."
+.TP
+.B 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.
+.TP
+.B bug-index.html
+An index of all explicitly marked
+.B @bug
+fields.  This page is only
+generated if at least one
+.B @bug
+field is listed in a formatted docstring.
+.TP
+.B todo-index.html
+An index of all explicitly marked
+.B @todo
+fields.  This page is only
+generated if at least one
+.B @todo
+field is listed in a formatted docstring.
+.TP
+.B changed-index.html
+An index of all explicitly marked
+.B @changed
+fields.  This page is only
+generated if at least one
+.B @changed
+field is listed in a formatted docstring.
+.TP
+.B deprecated-index.html
+An index of all explicitly marked
+.B @deprecated
+fields.  This page is only
+generated if at least one
+.B @deprecated
+field is listed in a formatted docstring.
+.TP
+.B since-index.html
+An index of all explicitly marked
+.B @since
+fields.  This page is only
+generated if at least one
+.B @since
+field is listed in a formatted docstring.
+.RE
+.PP
+.B FRAMES-BASED TABLE OF CONTENTS
+.RS 4
+.TP
 .B 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
@@ -567,22 +494,33 @@
 .B sys
 or
 .BR epydoc.epytext .
+.RE
+.PP
+.B OTHER PAGES
+.RS 4
 .TP
+.B help.html
+The help page for the project.  This page explains how to use and
+navigate the webpage produced by epydoc.
+.TP
+.B redirect.html
+This page uses javascript to translate dotted names to their
+corresponding URLs.  For example, in epydoc's documentation,
+loading the page
+.B <redirect.html#epydoc.apidoc.DottedName>
+will automatically redirect the browser to
+.BR <epydoc.apidoc-module.html#DottedName> .
+.TP
 .B epydoc.css
 The CSS stylesheet used to display all HTML pages.
-.RE
-.PP
-By default,
-.B epydoc
-creates two subdirectories in the output directory:
-.B public
-and
-.BR private .
-Each directory contains all of the files specified above.
-But if the
-.B \-\-no\-private
-option is used, then no subdirectories are created, and the public
-documentation is written directly to the output directory.
+.TP
+.B epydoc.js
+A javascript file used to define javascript functions used by epydoc.
+.TP
+.B 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 ====================
 .SH LATEX FILES
 The LaTeX API documentation produced by
@@ -638,51 +576,12 @@
 .RE
 .\" ================== DIAGNOSTICS ====================
 .SH DIAGNOSTICS
-Errors are divided into five categories: import errors; epytext
-errors; epytext warnings; field warnings; and inspection errors.
-Whenver epydoc encounters an error, it issues a warning message that
-describes the error, and attempts to continue generating
-documentation.
-.PP
-Import errors indicate that epydoc was unable to import a module.
-Import errors typically prevent epydoc from generating documentation
-for the module in question.  Epydoc can generate the following import
-errors:
+.B EPYTEXT MARKUP WARNING MESSAGES
 .RS 4
-.TP
-.BI "Bad module name " module
-Epydoc attempted to import
-.IR module ,
-but
-.I module
-is not a valid name for a Python module.
-.TP
-.BI "Could not find a UID for " link-target
-Epydoc was unable to find the object referred to by an inline link
-construction
-.RB ( "L{...}" ).
-This is usually caused by a typo in the link.
-.TP
-.BI "Could not import " module
-Epydoc attempted to import
-.IR module ,
-but it failed.  This typically occurs when
-.I module
-raises an exception.
-.TP
-.IB file " does not exist"
-Epydoc attempted to import the module contained in
-.IR file ,
-but
-.I file
-does not exist.
-.RE
-.PP
 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:
-.RS 4
 .TP
 .B Bad link target.
 The target specified for an inline link contruction
@@ -754,14 +653,6 @@
 indicate an appopriate section level.  The "=" character should be
 used to underline sections; "-" for subsections; and "~" for
 subsubsections.
-.RE
-.PP
-Epytext warnings are caused by epytext docstrings that contain
-questionable or suspicious markup.  Epytext warnings do
-.B not
-prevent the docstring in question from being parsed.  Epydoc can
-generate the following epytext warnings:
-.RS 4
 .TP
 .B Possible mal-formatted field item.
 Epytext detected a line that looks like a field item, but is not
@@ -775,10 +666,11 @@
 match exactly for them to be considered a heading.
 .RE
 .PP
-Field warnings are caused by epytext docstrings containing invalid
-fields.  The contents of the invalid field are generally ignored.  
-Epydoc can generate the following field warnings:
+.B FIELD WARNINGS
 .RS 4
+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:
 .TP
 .BI "@param for unknown parameter " param .
 A @param field was used to specify the type for a parameter that is
@@ -816,75 +708,24 @@
 .I field
 can only take a single value.
 .RE
-.PP
-Inspection errors are generated if epydoc encounters problems while
-attempting to inspect the properties of a documented object.  Most of
-inspection errors do not prevent epydoc from documenting the object in
-question.  Epydoc can generate the following inspection errors:
-.RS 4
+.\" ================== EXAMPLES ====================
+.SH EXAMPLES
 .TP
-.BI "The parameters of " inhmethod " do not match " basemethod .
-The parameters of the undocumented method
-.I inhmethod 
-do not match the parameters of the base class method
-.I basemethod
-that it overrides.  As a result,
-.I inhmethod
-does not inherit documentation from
-.IR basemethod .
-If the difference in parameters is intentional, then you can eliminate
-the warning by adding a (possibly empty) docstring to
-.IR inhmethod .
+.BR "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
+.B html
+directory.  In the headers and footers, use
+.B epydoc
+as the project name, and
+.B http://epydoc.sf.net
+as the project URL.
 .TP
-.BI "Docmap cannot add a " type
-Epydoc attempted to document an object with an unknown type.  This
-error is typically generated by packages and modules that manipulate
-the import mechanism, such that importing a module produces some other
-type of object.
-.TP
-.BI "UID conflict detected: " uid
-Two different objects were assigned the same unique identifier by
-epydoc.  This can cause epydoc to substitute the documentation of one
-object with the documentation of another object that is assigned the
-same unique identifier.  However, this will usually only cause
-problems if the two objects with the same unique identifiers are both
-modules or classes, in which case the API documentation page for one
-object will overwrite the API documentation page for the other object.
-.TP
-.IB object " appears in multiple builtin modules"
-While attempting to determine which module defines the builtin object
-.IR object ,
-epydoc encountered multiple candidates, and was unable to decide which
-candidate was correct.  In this case, epydoc arbitrarily chooses the
-first candidate that it finds.
-.TP
-.IB object " appears in multiple .py modules"
-While attempting to determine which module defines the builtin object
-.IR object ,
-epydoc encountered multiple candidates, and was unable to decide which
-candidate was correct.  In this case, epydoc arbitrarily chooses the
-first candidate that it finds.
-.TP
-.IB object " appears in multiple .so modules"
-While attempting to determine which module defines the builtin object
-.IR object ,
-epydoc encountered multiple candidates, and was unable to decide which
-candidate was correct.  In this case, epydoc arbitrarily chooses the
-first candidate that it finds.
-.TP
-.BI "Could not find a module for " object
-Epydoc was unable to determine which module defines 
-.IR object .
-If
-.I object
-is a function, then this will prevent epydoc from generating any
-documentation for
-.IR object ,
-since it does not know what page to put the documentation on.
-Otherwise, this will prevent the documentation for
-.I object
-from including a link to its containing module.
-.RE
+.BR "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
+.B latex
+directory.
 .\" ================== EXIT STATUS ====================
 .SH EXIT STATUS
 .TP
@@ -894,6 +735,13 @@
 .B 1
 Usage error.
 .TP
+.B 2
+Epydoc generated an error or warning, and one of the options
+.BI \-\-fail\-on\-error ,
+.BI \-\-fail\-on\-warning ", or"
+.B \-\-fail\-on\-docstring\-warning
+was specified.
+.TP
 .B other
 Internal error (Python exception).
 .\" ================== AUTHOR ====================
@@ -902,7 +750,7 @@
 written by Moshe Zadka, and is currently maintained by Edward Loper.
 .\" ================== BUGS ====================
 .SH BUGS
-Report bugs to <ed...@gr...>.
+Report bugs to <ed...@us...>.
 .\" ================== SEE ALSO ====================
 .SH SEE ALSO
 .BR epydocgui (1)


This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.