<!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">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>sphinx.ext.autosummary – Generate autodoc summaries — Sphinx v1.0.7 documentation</title>
<link rel="stylesheet" href="../_static/sphinxdoc.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '../',
VERSION: '1.0.7',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true
};
</script>
<script type="text/javascript" src="../_static/jquery.js"></script>
<script type="text/javascript" src="../_static/underscore.js"></script>
<script type="text/javascript" src="../_static/doctools.js"></script>
<link rel="search" type="application/opensearchdescription+xml"
title="Search within Sphinx v1.0.7 documentation"
href="../_static/opensearch.xml"/>
<link rel="top" title="Sphinx v1.0.7 documentation" href="../index.html" />
<link rel="up" title="Sphinx Extensions" href="../extensions.html" />
<link rel="next" title="sphinx.ext.doctest – Test snippets in the documentation" href="doctest.html" />
<link rel="prev" title="sphinx.ext.autodoc – Include documentation from docstrings" href="autodoc.html" />
<style type="text/css">
table.right { float: right; margin-left: 20px; }
table.right td { border: 1px solid #ccc; }
</style>
</head>
<body>
<div style="background-color: white; text-align: left; padding: 10px 10px 15px 15px">
<img src="../_static/sphinx.png" alt="Sphinx logo" />
</div>
<div class="related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="doctest.html" title="sphinx.ext.doctest – Test snippets in the documentation"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="autodoc.html" title="sphinx.ext.autodoc – Include documentation from docstrings"
accesskey="P">previous</a> |</li>
<li><a href="../index.html">Sphinx home</a> | </li>
<li><a href="../contents.html">Documentation</a>
»</li>
<li><a href="../extensions.html" accesskey="U">Sphinx Extensions</a> »</li>
</ul>
</div>
<div class="sphinxsidebar">
<div class="sphinxsidebarwrapper">
<h3><a href="../contents.html">Table Of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#"><tt class="docutils literal"><span class="pre">sphinx.ext.autosummary</span></tt> – Generate autodoc summaries</a><ul>
<li><a class="reference internal" href="#sphinx-autogen-generate-autodoc-stub-pages"><strong class="program">sphinx-autogen</strong> – generate autodoc stub pages</a></li>
<li><a class="reference internal" href="#generating-stub-pages-automatically">Generating stub pages automatically</a></li>
<li><a class="reference internal" href="#customizing-templates">Customizing templates</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="autodoc.html"
title="previous chapter"><tt class="docutils literal docutils literal"><span class="pre">sphinx.ext.autodoc</span></tt> – Include documentation from docstrings</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="doctest.html"
title="next chapter"><tt class="docutils literal"><span class="pre">sphinx.ext.doctest</span></tt> – Test snippets in the documentation</a></p>
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../_sources/ext/autosummary.txt"
rel="nofollow">Show Source</a></li>
</ul>
<div id="searchbox" style="display: none">
<h3>Quick search</h3>
<form class="search" action="../search.html" method="get">
<input type="text" name="q" size="18" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
<p class="searchtip" style="font-size: 90%">
Enter search terms or a module, class or function name.
</p>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body">
<div class="section" id="module-sphinx.ext.autosummary">
<span id="sphinx-ext-autosummary-generate-autodoc-summaries"></span><h1><a class="reference internal" href="#module-sphinx.ext.autosummary" title="sphinx.ext.autosummary: Generate autodoc summaries"><tt class="xref py py-mod docutils literal"><span class="pre">sphinx.ext.autosummary</span></tt></a> – Generate autodoc summaries<a class="headerlink" href="#module-sphinx.ext.autosummary" title="Permalink to this headline">¶</a></h1>
<p class="versionadded">
<span class="versionmodified">New in version 0.6.</span></p>
<p>This extension generates function/method/attribute summary lists, similar to
those output e.g. by Epydoc and other API doc generation tools. This is
especially useful when your docstrings are long and detailed, and putting each
one of them on a separate page makes them easier to read.</p>
<p>The <a class="reference internal" href="#module-sphinx.ext.autosummary" title="sphinx.ext.autosummary: Generate autodoc summaries"><tt class="xref py py-mod docutils literal"><span class="pre">sphinx.ext.autosummary</span></tt></a> extension does this in two parts:</p>
<ol class="arabic simple">
<li>There is an <a class="reference internal" href="#directive-autosummary" title="autosummary directive"><tt class="xref rst rst-dir docutils literal"><span class="pre">autosummary</span></tt></a> directive for generating summary listings that
contain links to the documented items, and short summary blurbs extracted
from their docstrings.</li>
<li>The convenience script <strong class="program">sphinx-autogen</strong> or the new
<a class="reference internal" href="#confval-autosummary_generate"><tt class="xref std std-confval docutils literal"><span class="pre">autosummary_generate</span></tt></a> config value can be used to generate short
“stub” files for the entries listed in the <a class="reference internal" href="#directive-autosummary" title="autosummary directive"><tt class="xref rst rst-dir docutils literal"><span class="pre">autosummary</span></tt></a> directives.
These by default contain only the corresponding <a class="reference internal" href="autodoc.html#module-sphinx.ext.autodoc" title="sphinx.ext.autodoc: Include documentation from docstrings."><tt class="xref py py-mod docutils literal"><span class="pre">sphinx.ext.autodoc</span></tt></a>
directive.</li>
</ol>
<dl class="directive">
<dt id="directive-autosummary">
<tt class="descname">.. autosummary::</tt><a class="headerlink" href="#directive-autosummary" title="Permalink to this definition">¶</a></dt>
<dd><p>Insert a table that contains links to documented items, and a short summary
blurb (the first sentence of the docstring) for each of them. The
<a class="reference internal" href="#directive-autosummary" title="autosummary directive"><tt class="xref rst rst-dir docutils literal"><span class="pre">autosummary</span></tt></a> directive can also optionally serve as a <a class="reference internal" href="../markup/toctree.html#directive-toctree" title="toctree directive"><tt class="xref rst rst-dir docutils literal"><span class="pre">toctree</span></tt></a>
entry for the included items.</p>
<p>For example,</p>
<div class="highlight-rest"><pre>.. currentmodule:: sphinx
.. autosummary::
environment.BuildEnvironment
util.relative_uri</pre>
</div>
<p>produces a table like this:</p>
<blockquote>
<div><table border="1" class="docutils">
<colgroup>
<col width="10%" />
<col width="90%" />
</colgroup>
<tbody valign="top">
<tr><td><tt class="xref py py-obj docutils literal"><span class="pre">environment.BuildEnvironment</span></tt>(srcdir, ...)</td>
<td>The environment in which the ReST files are translated.</td>
</tr>
<tr><td><tt class="xref py py-obj docutils literal"><span class="pre">util.relative_uri</span></tt>(base, to)</td>
<td>Return a relative URL from <tt class="docutils literal"><span class="pre">base</span></tt> to <tt class="docutils literal"><span class="pre">to</span></tt>.</td>
</tr>
</tbody>
</table>
</div></blockquote>
<p>Autosummary preprocesses the docstrings and signatures with the same
<a class="reference internal" href="autodoc.html#event-autodoc-process-docstring"><tt class="xref std std-event docutils literal"><span class="pre">autodoc-process-docstring</span></tt></a> and <a class="reference internal" href="autodoc.html#event-autodoc-process-signature"><tt class="xref std std-event docutils literal"><span class="pre">autodoc-process-signature</span></tt></a>
hooks as <a class="reference internal" href="autodoc.html#module-sphinx.ext.autodoc" title="sphinx.ext.autodoc: Include documentation from docstrings."><tt class="xref py py-mod docutils literal"><span class="pre">autodoc</span></tt></a>.</p>
<p><strong>Options</strong></p>
<ul>
<li><p class="first">If you want the <a class="reference internal" href="#directive-autosummary" title="autosummary directive"><tt class="xref rst rst-dir docutils literal"><span class="pre">autosummary</span></tt></a> table to also serve as a <a class="reference internal" href="../markup/toctree.html#directive-toctree" title="toctree directive"><tt class="xref rst rst-dir docutils literal"><span class="pre">toctree</span></tt></a>
entry, use the <tt class="docutils literal"><span class="pre">toctree</span></tt> option, for example:</p>
<div class="highlight-rest"><pre>.. autosummary::
:toctree: DIRNAME
sphinx.environment.BuildEnvironment
sphinx.util.relative_uri</pre>
</div>
<p>The <tt class="docutils literal"><span class="pre">toctree</span></tt> option also signals to the <strong class="program">sphinx-autogen</strong> script
that stub pages should be generated for the entries listed in this
directive. The option accepts a directory name as an argument;
<strong class="program">sphinx-autogen</strong> will by default place its output in this
directory. If no argument is given, output is placed in the same directory
as the file that contains the directive.</p>
</li>
<li><p class="first">If you don’t want the <a class="reference internal" href="#directive-autosummary" title="autosummary directive"><tt class="xref rst rst-dir docutils literal"><span class="pre">autosummary</span></tt></a> to show function signatures in the
listing, include the <tt class="docutils literal"><span class="pre">nosignatures</span></tt> option:</p>
<div class="highlight-rest"><pre>.. autosummary::
:nosignatures:
sphinx.environment.BuildEnvironment
sphinx.util.relative_uri</pre>
</div>
</li>
<li><p class="first">You can specify a custom template with the <tt class="docutils literal"><span class="pre">template</span></tt> option.
For example,</p>
<div class="highlight-rest"><pre>.. autosummary::
:template: mytemplate.rst
sphinx.environment.BuildEnvironment</pre>
</div>
<p>would use the template <tt class="file docutils literal"><span class="pre">mytemplate.rst</span></tt> in your
<a class="reference internal" href="../config.html#confval-templates_path"><tt class="xref std std-confval docutils literal"><span class="pre">templates_path</span></tt></a> to generate the pages for all entries
listed. See <a class="reference internal" href="#customizing-templates">Customizing templates</a> below.</p>
<p class="versionadded">
<span class="versionmodified">New in version 1.0.</span></p>
</li>
</ul>
</dd></dl>
<div class="section" id="sphinx-autogen-generate-autodoc-stub-pages">
<h2><strong class="program">sphinx-autogen</strong> – generate autodoc stub pages<a class="headerlink" href="#sphinx-autogen-generate-autodoc-stub-pages" title="Permalink to this headline">¶</a></h2>
<p>The <strong class="program">sphinx-autogen</strong> script can be used to conveniently generate stub
documentation pages for items included in <a class="reference internal" href="#directive-autosummary" title="autosummary directive"><tt class="xref rst rst-dir docutils literal"><span class="pre">autosummary</span></tt></a> listings.</p>
<p>For example, the command</p>
<div class="highlight-rest"><pre>$ sphinx-autogen -o generated *.rst</pre>
</div>
<p>will read all <a class="reference internal" href="#directive-autosummary" title="autosummary directive"><tt class="xref rst rst-dir docutils literal"><span class="pre">autosummary</span></tt></a> tables in the <tt class="file docutils literal"><span class="pre">*.rst</span></tt> files that have the
<tt class="docutils literal"><span class="pre">:toctree:</span></tt> option set, and output corresponding stub pages in directory
<tt class="docutils literal"><span class="pre">generated</span></tt> for all documented items. The generated pages by default contain
text of the form:</p>
<div class="highlight-rest"><pre>sphinx.util.relative_uri
========================
.. autofunction:: sphinx.util.relative_uri</pre>
</div>
<p>If the <tt class="docutils literal"><span class="pre">-o</span></tt> option is not given, the script will place the output files in the
directories specified in the <tt class="docutils literal"><span class="pre">:toctree:</span></tt> options.</p>
</div>
<div class="section" id="generating-stub-pages-automatically">
<h2>Generating stub pages automatically<a class="headerlink" href="#generating-stub-pages-automatically" title="Permalink to this headline">¶</a></h2>
<p>If you do not want to create stub pages with <strong class="program">sphinx-autogen</strong>, you can
also use this new config value:</p>
<dl class="confval">
<dt id="confval-autosummary_generate">
<tt class="descname">autosummary_generate</tt><a class="headerlink" href="#confval-autosummary_generate" title="Permalink to this definition">¶</a></dt>
<dd><p>Boolean indicating whether to scan all found documents for autosummary
directives, and to generate stub pages for each.</p>
<p>Can also be a list of documents for which stub pages should be generated.</p>
<p>The new files will be placed in the directories specified in the
<tt class="docutils literal"><span class="pre">:toctree:</span></tt> options of the directives.</p>
</dd></dl>
</div>
<div class="section" id="customizing-templates">
<h2>Customizing templates<a class="headerlink" href="#customizing-templates" title="Permalink to this headline">¶</a></h2>
<p class="versionadded">
<span class="versionmodified">New in version 1.0.</span></p>
<p>You can customize the stub page templates, in a similar way as the HTML Jinja
templates, see <a class="reference internal" href="../templating.html#templating"><em>Templating</em></a>. (<a class="reference internal" href="appapi.html#sphinx.application.TemplateBridge" title="sphinx.application.TemplateBridge"><tt class="xref py py-class docutils literal"><span class="pre">TemplateBridge</span></tt></a>
is not supported.)</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">If you find yourself spending much time tailoring the stub templates, this
may indicate that it’s a better idea to write custom narrative documentation
instead.</p>
</div>
<p>Autosummary uses the following template files:</p>
<ul class="simple">
<li><tt class="file docutils literal"><span class="pre">autosummary/base.rst</span></tt> – fallback template</li>
<li><tt class="file docutils literal"><span class="pre">autosummary/module.rst</span></tt> – template for modules</li>
<li><tt class="file docutils literal"><span class="pre">autosummary/class.rst</span></tt> – template for classes</li>
<li><tt class="file docutils literal"><span class="pre">autosummary/function.rst</span></tt> – template for functions</li>
<li><tt class="file docutils literal"><span class="pre">autosummary/attribute.rst</span></tt> – template for class attributes</li>
<li><tt class="file docutils literal"><span class="pre">autosummary/method.rst</span></tt> – template for class methods</li>
</ul>
<p>The following variables available in the templates:</p>
<dl class="data">
<dt id="name">
<tt class="descname">name</tt><a class="headerlink" href="#name" title="Permalink to this definition">¶</a></dt>
<dd><p>Name of the documented object, excluding the module and class parts.</p>
</dd></dl>
<dl class="data">
<dt id="objname">
<tt class="descname">objname</tt><a class="headerlink" href="#objname" title="Permalink to this definition">¶</a></dt>
<dd><p>Name of the documented object, excluding the module parts.</p>
</dd></dl>
<dl class="data">
<dt id="fullname">
<tt class="descname">fullname</tt><a class="headerlink" href="#fullname" title="Permalink to this definition">¶</a></dt>
<dd><p>Full name of the documented object, including module and class parts.</p>
</dd></dl>
<dl class="data">
<dt id="module">
<tt class="descname">module</tt><a class="headerlink" href="#module" title="Permalink to this definition">¶</a></dt>
<dd><p>Name of the module the documented object belongs to.</p>
</dd></dl>
<dl class="data">
<dt id="class">
<tt class="descname">class</tt><a class="headerlink" href="#class" title="Permalink to this definition">¶</a></dt>
<dd><p>Name of the class the documented object belongs to. Only available for
methods and attributes.</p>
</dd></dl>
<dl class="data">
<dt id="underline">
<tt class="descname">underline</tt><a class="headerlink" href="#underline" title="Permalink to this definition">¶</a></dt>
<dd><p>A string containing <tt class="docutils literal"><span class="pre">len(full_name)</span> <span class="pre">*</span> <span class="pre">'='</span></tt>.</p>
</dd></dl>
<dl class="data">
<dt id="members">
<tt class="descname">members</tt><a class="headerlink" href="#members" title="Permalink to this definition">¶</a></dt>
<dd><p>List containing names of all members of the module or class. Only available
for modules and classes.</p>
</dd></dl>
<dl class="data">
<dt id="functions">
<tt class="descname">functions</tt><a class="headerlink" href="#functions" title="Permalink to this definition">¶</a></dt>
<dd><p>List containing names of “public” functions in the module. Here, “public”
here means that the name does not start with an underscore. Only available
for modules.</p>
</dd></dl>
<dl class="data">
<dt id="classes">
<tt class="descname">classes</tt><a class="headerlink" href="#classes" title="Permalink to this definition">¶</a></dt>
<dd><p>List containing names of “public” classes in the module. Only available for
modules.</p>
</dd></dl>
<dl class="data">
<dt id="exceptions">
<tt class="descname">exceptions</tt><a class="headerlink" href="#exceptions" title="Permalink to this definition">¶</a></dt>
<dd><p>List containing names of “public” exceptions in the module. Only available
for modules.</p>
</dd></dl>
<dl class="data">
<dt id="methods">
<tt class="descname">methods</tt><a class="headerlink" href="#methods" title="Permalink to this definition">¶</a></dt>
<dd><p>List containing names of “public” methods in the class. Only available for
classes.</p>
</dd></dl>
<dl class="data">
<dt id="attributes">
<tt class="descname">attributes</tt><a class="headerlink" href="#attributes" title="Permalink to this definition">¶</a></dt>
<dd><p>List containing names of “public” attributes in the class. Only available
for classes.</p>
</dd></dl>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">You can use the <a class="reference internal" href="#directive-autosummary" title="autosummary directive"><tt class="xref rst rst-dir docutils literal"><span class="pre">autosummary</span></tt></a> directive in the stub pages.
Stub pages are generated also based on these directives.</p>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="doctest.html" title="sphinx.ext.doctest – Test snippets in the documentation"
>next</a> |</li>
<li class="right" >
<a href="autodoc.html" title="sphinx.ext.autodoc – Include documentation from docstrings"
>previous</a> |</li>
<li><a href="../index.html">Sphinx home</a> | </li>
<li><a href="../contents.html">Documentation</a>
»</li>
<li><a href="../extensions.html" >Sphinx Extensions</a> »</li>
</ul>
</div>
<div class="footer">
© Copyright 2007-2011, Georg Brandl.
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.0.7.
</div>
</body>
</html>
distrib
>
Fedora
>
14
>
x86_64
>
media
>
updates
>
by-pkgid
>
2b39e69e45f9a0b2b3aece7339c56216
>
files
>
81
