<!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 extensions — Astropy v0.2.4</title>
<link rel="stylesheet" href="../_static/bootstrap-astropy.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '../',
VERSION: '0.2.4',
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>
<script type="text/javascript" src="../_static/sidebar.js"></script>
<link rel="shortcut icon" href="../_static/astropy_logo.ico"/>
<link rel="top" title="Astropy v0.2.4" href="../index.html" />
<link rel="next" title="Full Changelog" href="../changelog.html" />
<link rel="prev" title="Writing Command-Line Scripts" href="scripts.html" />
</head>
<body>
<div class="topbar">
<a class="brand" title="Documentation Home" href="../index.html"></a>
<ul>
<li><a class="homelink" title="AstroPy Homepage" href="http://www.astropy.org"></a></li>
<li><a title="General Index" href="../genindex.html">Index</a></li>
<li><a title="Python Module Index" href="../py-modindex.html">Modules</a></li>
<li>
<form action="../search.html" method="get">
<input type="text" name="q" placeholder="Search" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</li>
</ul>
</div>
<div class="related">
<h3>Navigation</h3>
<ul>
<li class="right">
<a href="../changelog.html" title="Full Changelog">
next »
</a>
</li>
<li class="right">
<a href="scripts.html" title="Writing Command-Line Scripts">
« previous
</a>
|
</li>
<li>
<a href="../index.html">Astropy v0.2.4</a>
»
</li>
<li>Sphinx extensions</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body">
<div class="section" id="sphinx-extensions">
<h1>Sphinx extensions<a class="headerlink" href="#sphinx-extensions" title="Permalink to this headline">¶</a></h1>
<p>This page gives the API for the custom Sphinx extensions used in Astropy.</p>
<div class="section" id="module-astropy.sphinx.ext.automodapi">
<span id="automodapi-extension"></span><h2>automodapi Extension<a class="headerlink" href="#module-astropy.sphinx.ext.automodapi" title="Permalink to this headline">¶</a></h2>
<p>This sphinx extension adds a tools to simplify generating the API
documentationfor Astropy packages and affiliated packages.</p>
<div class="section" id="automodapi-directive">
<h3><tt class="xref py py-obj docutils literal"><span class="pre">automodapi</span></tt> directive<a class="headerlink" href="#automodapi-directive" title="Permalink to this headline">¶</a></h3>
<p>This directive takes a single argument that must be module or package.
It will produce a block of documentation that includes the docstring for
the package, an <tt class="xref py py-obj docutils literal"><span class="pre">automodsumm</span></tt> directive, and an <tt class="xref py py-obj docutils literal"><span class="pre">automod-diagram</span></tt> if
there are any classes in the module.</p>
<p>It accepts the following options:</p>
<blockquote>
<div><ul>
<li><dl class="first docutils">
<dt><tt class="docutils literal"><span class="pre">:no-inheritance-diagram:</span></tt></dt>
<dd><p class="first last">If present, the inheritance diagram will not be shown even if
the module/package has classes.</p>
</dd>
</dl>
</li>
<li><dl class="first docutils">
<dt><tt class="docutils literal"><span class="pre">:skip:</span> <span class="pre">str</span></tt></dt>
<dd><p class="first last">This option results in the
specified object being skipped, that is the object will <em>not</em> be
included in the generated documentation. This option may appear
any number of times to skip multiple objects.</p>
</dd>
</dl>
</li>
<li><dl class="first docutils">
<dt><tt class="docutils literal"><span class="pre">:no-main-docstr:</span></tt></dt>
<dd><p class="first last">If present, the docstring for the module/package will not be generated.
The function and class tables will still be used, however.</p>
</dd>
</dl>
</li>
<li><dl class="first docutils">
<dt><tt class="docutils literal"><span class="pre">:headings:</span> <span class="pre">str</span></tt></dt>
<dd><p class="first last">Specifies the characters (in one string) used as the heading
levels used for the generated section. This must have at least 2
characters (any after 2 will be ignored). This also <em>must</em> match
the rest of the documentation on this page for sphinx to be
happy. Defaults to “-^”, which matches the convention used for
Python’s documentation, assuming the automodapi call is inside a
top-level section (which usually uses ‘=’).</p>
</dd>
</dl>
</li>
</ul>
</div></blockquote>
<p>This extension also adds a sphinx configuration option
<tt class="xref py py-obj docutils literal"><span class="pre">automodapi_toctreedirnm</span></tt>. It must be a string that specifies the name of
the directory the automodsumm generated documentation ends up in. This
directory path should be relative to the documentation root (e.g., same
place as <tt class="docutils literal"><span class="pre">index.rst</span></tt>). It defaults to ‘_generated’</p>
</div>
</div>
<div class="section" id="module-astropy.sphinx.ext.automodsumm">
<span id="automodsumm-extension"></span><h2>automodsumm Extension<a class="headerlink" href="#module-astropy.sphinx.ext.automodsumm" title="Permalink to this headline">¶</a></h2>
<p>This sphinx extension adds two directives for summarizing the public
members of a module or package.</p>
<p>These directives are primarily for use with the <tt class="xref py py-obj docutils literal"><span class="pre">automodapi</span></tt> extension,
but can be used independently.</p>
<div class="section" id="automodsumm-directive">
<h3><tt class="xref py py-obj docutils literal"><span class="pre">automodsumm</span></tt> directive<a class="headerlink" href="#automodsumm-directive" title="Permalink to this headline">¶</a></h3>
<p>This directive will produce an “autosummary”-style table for public
attributes of a specified module. See the <tt class="xref py py-obj docutils literal"><span class="pre">sphinx.ext.autosummary</span></tt>
extension for details on this process. The main difference from the
<tt class="xref py py-obj docutils literal"><span class="pre">autosummary</span></tt> directive is that <tt class="xref py py-obj docutils literal"><span class="pre">autosummary</span></tt> requires manually inputting
all attributes that appear in the table, while this captures the entries
automatically.</p>
<p>This directive requires a single argument that must be a module or
package.</p>
<p>It also accepts any options supported by the <tt class="xref py py-obj docutils literal"><span class="pre">autosummary</span></tt> directive-
see <tt class="xref py py-obj docutils literal"><span class="pre">sphinx.ext.autosummary</span></tt> for details. It also accepts two additional
options:</p>
<blockquote>
<div><ul>
<li><dl class="first docutils">
<dt><tt class="docutils literal"><span class="pre">:classes-only:</span></tt></dt>
<dd><p class="first last">If present, the autosummary table will only contain entries for
classes. This cannot be used at the same time with
<tt class="docutils literal"><span class="pre">:functions-only:</span></tt> .</p>
</dd>
</dl>
</li>
<li><dl class="first docutils">
<dt><tt class="docutils literal"><span class="pre">:functions-only:</span></tt></dt>
<dd><p class="first last">If present, the autosummary table will only contain entries for
functions. This cannot be used at the same time with
<tt class="docutils literal"><span class="pre">:classes-only:</span></tt> .</p>
</dd>
</dl>
</li>
<li><dl class="first docutils">
<dt><tt class="docutils literal"><span class="pre">:skip:</span> <span class="pre">obj1,</span> <span class="pre">[obj2,</span> <span class="pre">obj3,</span> <span class="pre">...]</span></tt></dt>
<dd><p class="first last">If present, specifies that the listed objects should be skipped
and not have their documentation generated, nor be includded in
the summary table.</p>
</dd>
</dl>
</li>
</ul>
</div></blockquote>
</div>
<div class="section" id="automod-diagram-directive">
<h3><tt class="xref py py-obj docutils literal"><span class="pre">automod-diagram</span></tt> directive<a class="headerlink" href="#automod-diagram-directive" title="Permalink to this headline">¶</a></h3>
<p>This directive will produce an inheritance diagram like that of the
<tt class="xref py py-obj docutils literal"><span class="pre">sphinx.ext.inheritance_diagram</span></tt> extension.</p>
<p>This directive requires a single argument that must be a module or
package. It accepts no options.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">Like ‘inheritance-diagram’, ‘automod-diagram’ requires graphviz to
generate the inheritance diagram.</p>
</div>
</div>
</div>
<div class="section" id="numpydoc-extension">
<h2>Numpydoc Extension<a class="headerlink" href="#numpydoc-extension" title="Permalink to this headline">¶</a></h2>
<p>This extension is a port of the
<a class="reference external" href="http://pypi.python.org/pypi/numpydoc/0.3.1">numpydoc</a> extentension written by
the <a class="reference external" href="http://numpy.scipy.org/">numpy</a> and <a class="reference external" href="http://scipy.org/">scipy</a>
projects, with some tweaks for Astropy. See the code for details, as it
is quite complex and includes a variety of interrelated extensions.</p>
</div>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar">
<div class="sphinxsidebarwrapper"><h3>Page Contents</h3>
<ul>
<li><a class="reference internal" href="#">Sphinx extensions</a><ul>
<li><a class="reference internal" href="#module-astropy.sphinx.ext.automodapi">automodapi Extension</a><ul>
<li><a class="reference internal" href="#automodapi-directive"><tt class="docutils literal"><span class="pre">automodapi</span></tt> directive</a></li>
</ul>
</li>
<li><a class="reference internal" href="#module-astropy.sphinx.ext.automodsumm">automodsumm Extension</a><ul>
<li><a class="reference internal" href="#automodsumm-directive"><tt class="docutils literal"><span class="pre">automodsumm</span></tt> directive</a></li>
<li><a class="reference internal" href="#automod-diagram-directive"><tt class="docutils literal"><span class="pre">automod-diagram</span></tt> directive</a></li>
</ul>
</li>
<li><a class="reference internal" href="#numpydoc-extension">Numpydoc Extension</a></li>
</ul>
</li>
</ul>
</div>
</div>
<div class="clearer"></div>
</div>
<footer class="footer">
<p class="pull-right">
<a href="http://github.com/astropy/astropy/tree/v0.2.4/docs/development/sphinxext.rst">Edit This Page on Github</a>
<a href="../_sources/development/sphinxext.txt"
rel="nofollow">Page Source</a>
<a href="#">Back to Top</a></p>
<p>
© Copyright 2011-2013, The Astropy Developers.<br/>
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
Last built 22 Oct 2013. <br/>
</p>
</footer>
</body>
</html>
