<?xml version="1.0" encoding="ascii" ?> <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> <head> <meta http-equiv="Content-Type" content="text/html; charset=ascii" /> <meta name="generator" content="Docutils 0.5: http://docutils.sourceforge.net/" /> <title>References</title> <link rel="stylesheet" href="custom.css" type="text/css" /> </head> <body> <div class="document" id="references"> <h1 class="title">References</h1> <!-- $Id: manual-reference.txt 1549 2007-02-24 16:23:49Z dvarrazzo $ --> <div class="section" id="command-line-usage"> <h1>Command Line Usage</h1> <p>Usage: <tt class="docutils literal"><span class="pre">epydoc.py</span></tt> [<em>ACTION</em>] [<em>options</em>] <em>NAMES...</em></p> <dl class="docutils"> <dt>NAMES...</dt> <dd>A list of the Python objects that should be documented. Objects can be specified using dotted names (such as <tt class="docutils literal"><span class="pre">os.path</span></tt>), module filenames (such as <tt class="docutils literal"><span class="pre">epydoc/epytext.py</span></tt>), or package directory names (such as <tt class="docutils literal"><span class="pre">epydoc/</span></tt>). Packages are expanded to include all sub-modules and sub-packages.</dd> <dt>options</dt> <dd><pre class="first last literal-block"> --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). </pre> </dd> </dl> </div> <div class="section" id="sample-configuration-file"> <h1>Sample Configuration File</h1> <p>Configuration files, specified using the <tt class="docutils literal"><span class="pre">--config</span></tt> 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 <a class="reference external" href="http://docs.python.org/lib/module-ConfigParser.html">ConfigParser</a> module. The following example configuration file demonstrates the various options that you can set. Lines beginning with <tt class="docutils literal"><span class="pre">#</span></tt> or <tt class="docutils literal"><span class="pre">;</span></tt> are treated as comments.</p> <pre class="literal-block"> <strong>[epydoc]</strong> <em># Epydoc section marker (required by ConfigParser)</em> <em># The list of objects to document. Objects can be named using</em> <em># dotted names, module filenames, or package directory names.</em> <em># Alases for this option include "objects" and "values".</em> <strong>modules: sys, os.path, re</strong> <em># The type of output that should be generated. Should be one</em> <em># of: html, text, latex, dvi, ps, pdf.</em> <strong>output: html</strong> <em># The path to the output directory. May be relative or absolute.</em> <strong>target: html/</strong> <em># An integer indicating how verbose epydoc should be. The default</em> <em># value is 0; negative values will supress warnings and errors;</em> <em># positive values will give more verbose output.</em> <strong>verbosity: 0</strong> <em># A boolean value indicating that Epydoc should show a tracaback</em> <em># in case of unexpected error. By default don't show tracebacks</em> <strong>debug: 0</strong> <em># If True, don't try to use colors or cursor control when doing</em> <em># textual output. The default False assumes a rich text prompt</em> <strong>simple-term: 0</strong> <strong>### Generation options</strong> <em># The default markup language for docstrings, for modules that do</em> <em># not define __docformat__. Defaults to epytext.</em> <strong>docformat: epytext</strong> <em># Whether or not parsing should be used to examine objects.</em> <strong>parse: yes</strong> <em># Whether or not introspection should be used to examine objects.</em> <strong>introspect: yes</strong> <em># Don't examine in any way the modules whose dotted name match this</em> <em># regular expression pattern.</em> <strong>#exclude</strong> <em># Don't perform introspection on the modules whose dotted name match this</em> <em># regular expression pattern.</em> <strong>#exclude-introspect</strong> <em># Don't perform parsing on the modules whose dotted name match this</em> <em># regular expression pattern.</em> <strong>#exclude-parse</strong> <em># The format for showing inheritance objects.</em> <em># It should be one of: 'grouped', 'listed', 'included'.</em> <strong>inheritance: listed</strong> <em># Whether or not to inclue private variables. (Even if included,</em> <em># private variables will be hidden by default.)</em> <strong>private: yes</strong> <em># Whether or not to list each module's imports.</em> <strong>imports: no</strong> <em># Whether or not to include syntax highlighted source code in</em> <em># the output (HTML only).</em> <strong>sourcecode: yes</strong> <em># Whether or not to includea a page with Epydoc log, containing</em> <em># effective option at the time of generation and the reported logs.</em> <strong>include-log: no</strong> <strong>### Output options</strong> <em># The documented project's name.</em> <strong>#name: Example</strong> <em># The CSS stylesheet for HTML output. Can be the name of a builtin</em> <em># stylesheet, or the name of a file.</em> <strong>css: white</strong> <em># The documented project's URL.</em> <strong>#url: http://some.project/</strong> <em># HTML code for the project link in the navigation bar. If left</em> <em># unspecified, the project link will be generated based on the</em> <em># project's name and URL.</em> <strong>#link: <a href="somewhere">My Cool Project</a></strong> <em># The "top" page for the documentation. Can be a URL, the name</em> <em># of a module or class, or one of the special names "trees.html",</em> <em># "indices.html", or "help.html"</em> <strong>#top: os.path</strong> <em># An alternative help file. The named file should contain the</em> <em># body of an HTML file; navigation bars will be added to it.</em> <strong>#help: my_helpfile.html</strong> <em># Whether or not to include a frames-based table of contents.</em> <strong>frames: yes</strong> <em># Whether each class should be listed in its own section when</em> <em># generating LaTeX or PDF output.</em> <strong>separate-classes: no</strong> <strong>### API linking options</strong> <em># Define a new API document. A new interpreted text role</em> <em># will be created</em> <strong>#external-api: epydoc</strong> <em># Use the records in this file to resolve objects in the API named NAME.</em> <strong>#external-api-file: epydoc:api-objects.txt</strong> <em># Use this URL prefix to configure the string returned for external API.</em> <strong>#external-api-root: epydoc:http://epydoc.sourceforge.net/api</strong> <strong>### Graph options</strong> <em># The list of graph types that should be automatically included</em> <em># in the output. Graphs are generated using the Graphviz "dot"</em> <em># executable. Graph types include: "classtree", "callgraph",</em> <em># "umlclass". Use "all" to include all graph types</em> <strong>graph: all</strong> <em># The path to the Graphviz "dot" executable, used to generate</em> <em># graphs.</em> <strong>dotpath: /usr/local/bin/dot</strong> <em># The name of one or more pstat files (generated by the profile</em> <em># or hotshot module). These are used to generate call graphs.</em> <strong>pstat: profile.out</strong> <em># Specify the font used to generate Graphviz graphs.</em> <em># (e.g., helvetica or times).</em> <strong>graph-font: Helvetica</strong> <em># Specify the font size used to generate Graphviz graphs.</em> <strong>graph-font-size: 10</strong> <strong>### Return value options</strong> <em># The condition upon which Epydoc should exit with a non-zero</em> <em># exit status. Possible values are error, warning, docstring_warning</em> <strong>#fail-on: error</strong> </pre> </div> <div class="section" id="warnings-and-errors"> <h1>Warnings and Errors</h1> <p>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:</p> <dl class="docutils"> <dt>Epytext Warnings</dt> <dd>are caused by epytext docstrings that contain questionable or suspicious markup. Epytext warnings do not prevent the docstring in question from being parsed.</dd> <dt>Field Warnings</dt> <dd>are caused by epytext docstrings containing invalid fields. The contents of the invalid field are generally ignored.</dd> <dt>Epytext Errors</dt> <dd>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.</dd> </dl> <p>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 <tt class="docutils literal"><span class="pre">epydoc(1)</span></tt> man page.</p> <div class="section" id="epytext-warnings"> <h2>Epytext Warnings</h2> <dl class="docutils"> <dt>Possible mal-formatted field item.</dt> <dd>Epytext detected a line that looks like a field item, but is not correctly formatted. This typically occurs when the trailing colon (<tt class="docutils literal"><span class="pre">:</span></tt>) is not included in the field tag.</dd> <dt>Possible heading typo.</dt> <dd>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.</dd> </dl> </div> <div class="section" id="field-warnings"> <h2>Field Warnings</h2> <dl class="docutils"> <dt><tt class="docutils literal"><span class="pre">@param</span></tt> for unknown parameter <em>param</em>.</dt> <dd>A <tt class="docutils literal"><span class="pre">@param</span></tt> 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.</dd> <dt><em>tag</em> did not expect an argument.</dt> <dd>The field tag <em>tag</em> was used with an argument, but it does not take one.</dd> <dt><em>tag</em> expected an argument.</dt> <dd>The field tag <em>tag</em> was used without an argument, but it requires one.</dd> <dt><tt class="docutils literal"><span class="pre">@type</span></tt> for unknown parameter <em>param</em>.</dt> <dd>A <tt class="docutils literal"><span class="pre">@type</span></tt> 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.</dd> <dt><tt class="docutils literal"><span class="pre">@type</span></tt> for unknown variable <em>var</em>.</dt> <dd>A <tt class="docutils literal"><span class="pre">@type</span></tt> 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.</dd> <dt>Unknown field tag <em>tag</em>.</dt> <dd>A docstring contains a field with the unknown tag <em>tag</em>.</dd> <dt>Redefinition of <em>field</em>.</dt> <dd>Multiple field tags define the value of field in the same docstring, but field can only take a single value.</dd> </dl> </div> <div class="section" id="epytext-errors"> <h2>Epytext Errors</h2> <dl class="docutils"> <dt>Bad link target.</dt> <dd>The target specified for an inline link contruction (L{...}) is not well-formed. Link targets must be valid Python identifiers.</dd> <dt>Bad uri target.</dt> <dd>The target specified for an inline uri contruction (<tt class="docutils literal"><span class="pre">U{...}</span></tt>) is not well-formed. This typically occurs if inline markup is nested inside the URI target.</dd> <dt>Fields must be at the top level.</dt> <dd>The list of fields (<tt class="docutils literal"><span class="pre">@param</span></tt>, etc.) is contained by some other block structure (such as a list or a section).</dd> <dt>Fields must be the final elements in an epytext string.</dt> <dd>The list of fields (<tt class="docutils literal"><span class="pre">@param</span></tt>, etc.) is not at the end of a docstring.</dd> <dt>Headings must occur at top level.</dt> <dd>The heading is contianed in some other block structure (such as a list).</dd> <dt>Improper doctest block indentation.</dt> <dd>The doctest block dedents past the indentation of its initial prompt line.</dd> <dt>Improper heading indentation.</dt> <dd>The heading for a section is not left-aligned with the paragraphs in the section that contains it.</dd> <dt>Improper paragraph indentation.</dt> <dd>The paragraphs within a block are not left-aligned. This error is often generated when plaintext docstrings are parsed using epytext.</dd> <dt>Invalid escape.</dt> <dd>An unknown escape sequence was used with the inline escape construction (<tt class="docutils literal"><span class="pre">E{...}</span></tt>).</dd> <dt>Lists must be indented.</dt> <dd>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.</dd> <dt>Unbalanced '<tt class="docutils literal"><span class="pre">{</span></tt>'.</dt> <dd>The docstring contains unbalanced braces. Epytext requires that all braces must be balanced. To include a single unbalanced brace, use the escape sequences <tt class="docutils literal"><span class="pre">E{lb}</span></tt> (left brace) and <tt class="docutils literal"><span class="pre">E{rb}</span></tt> (right brace).</dd> <dt>Unbalanced '<tt class="docutils literal"><span class="pre">}</span></tt>'.</dt> <dd>The docstring contains unbalanced braces. Epytext requires that all braces must be balanced. To include a single unbalanced brace, use the escape sequences <tt class="docutils literal"><span class="pre">E{lb}</span></tt> (left brace) and <tt class="docutils literal"><span class="pre">E{rb}</span></tt> (right brace).</dd> <dt>Unknown inline markup tag.</dt> <dd>An unknown tag was used with the inline markup construction (<tt class="docutils literal"><span class="pre">x{...}</span></tt>).</dd> <dt>Wrong underline character for heading.</dt> <dd>The underline character used for this section heading does not indicate an appopriate section level. The '<tt class="docutils literal"><span class="pre">=</span></tt>' character should be used to underline sections; '<tt class="docutils literal"><span class="pre">-</span></tt>' for subsections; and '<tt class="docutils literal"><span class="pre">~</span></tt>' for subsubsections.</dd> </dl> </div> </div> </div> <table width="100%" class="navbox" cellpadding="1" cellspacing="0"> <tr> <a class="nav" href="index.html"> <td align="center" width="20%" class="nav"> <a class="nav" href="index.html"> Home</a></td></a> <a class="nav" href="installing.html"> <td align="center" width="20%" class="nav"> <a class="nav" href="installing.html"> Installing Epydoc</a></td></a> <a class="nav" href="using.html"> <td align="center" width="20%" class="nav"> <a class="nav" href="using.html"> Using Epydoc</a></td></a> <a class="nav" href="epytext.html"> <td align="center" width="20%" class="nav"> <a class="nav" href="epytext.html"> Epytext</a></td></a> <td align="center" width="20%" class="nav"> <A href="http://sourceforge.net/projects/epydoc"> <IMG src="sflogo.png" width="88" height="26" border="0" alt="SourceForge" align="top"/></A></td> </tr> </table> </body> </html>