<!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 Domains — Sphinx 1.1.3 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.1.3',
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 1.1.3 documentation"
href="_static/opensearch.xml"/>
<link rel="top" title="Sphinx 1.1.3 documentation" href="index.html" />
<link rel="next" title="Available builders" href="builders.html" />
<link rel="prev" title="Miscellaneous markup" href="markup/misc.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="builders.html" title="Available builders"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="markup/misc.html" title="Miscellaneous markup"
accesskey="P">previous</a> |</li>
<li><a href="index.html">Sphinx home</a> | </li>
<li><a href="contents.html">Documentation</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="#">Sphinx Domains</a><ul>
<li><a class="reference internal" href="#what-is-a-domain">What is a Domain?</a></li>
<li><a class="reference internal" href="#basic-markup">Basic Markup</a><ul>
<li><a class="reference internal" href="#cross-referencing-syntax">Cross-referencing syntax</a></li>
</ul>
</li>
<li><a class="reference internal" href="#the-python-domain">The Python Domain</a><ul>
<li><a class="reference internal" href="#python-signatures">Python Signatures</a></li>
<li><a class="reference internal" href="#info-field-lists">Info field lists</a></li>
<li><a class="reference internal" href="#cross-referencing-python-objects">Cross-referencing Python objects</a></li>
</ul>
</li>
<li><a class="reference internal" href="#the-c-domain">The C Domain</a><ul>
<li><a class="reference internal" href="#cross-referencing-c-constructs">Cross-referencing C constructs</a></li>
</ul>
</li>
<li><a class="reference internal" href="#id1">The C++ Domain</a></li>
<li><a class="reference internal" href="#the-standard-domain">The Standard Domain</a></li>
<li><a class="reference internal" href="#the-javascript-domain">The JavaScript Domain</a></li>
<li><a class="reference internal" href="#the-restructuredtext-domain">The reStructuredText domain</a></li>
<li><a class="reference internal" href="#more-domains">More domains</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="markup/misc.html"
title="previous chapter">Miscellaneous markup</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="builders.html"
title="next chapter">Available builders</a></p>
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="_sources/domains.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" />
<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="sphinx-domains">
<span id="domains"></span><h1>Sphinx Domains<a class="headerlink" href="#sphinx-domains" title="Permalink to this headline">¶</a></h1>
<p class="versionadded">
<span class="versionmodified">New in version 1.0.</span></p>
<div class="section" id="what-is-a-domain">
<h2>What is a Domain?<a class="headerlink" href="#what-is-a-domain" title="Permalink to this headline">¶</a></h2>
<p>Originally, Sphinx was conceived for a single project, the documentation of the
Python language. Shortly afterwards, it was made available for everyone as a
documentation tool, but the documentation of Python modules remained deeply
built in – the most fundamental directives, like <tt class="docutils literal"><span class="pre">function</span></tt>, were designed
for Python objects. Since Sphinx has become somewhat popular, interest
developed in using it for many different purposes: C/C++ projects, JavaScript,
or even reStructuredText markup (like in this documentation).</p>
<p>While this was always possible, it is now much easier to easily support
documentation of projects using different programming languages or even ones not
supported by the main Sphinx distribution, by providing a <strong>domain</strong> for every
such purpose.</p>
<p>A domain is a collection of markup (reStructuredText <a class="reference internal" href="glossary.html#term-directive"><em class="xref std std-term">directive</em></a>s and
<a class="reference internal" href="glossary.html#term-role"><em class="xref std std-term">role</em></a>s) to describe and link to <a class="reference internal" href="glossary.html#term-object"><em class="xref std std-term">object</em></a>s belonging together,
e.g. elements of a programming language. Directive and role names in a domain
have names like <tt class="docutils literal"><span class="pre">domain:name</span></tt>, e.g. <tt class="docutils literal"><span class="pre">py:function</span></tt>. Domains can also provide
custom indices (like the Python Module Index).</p>
<p>Having domains means that there are no naming problems when one set of
documentation wants to refer to e.g. C++ and Python classes. It also means that
extensions that support the documentation of whole new languages are much easier
to write.</p>
<p>This section describes what the domains that come with Sphinx provide. The
domain API is documented as well, in the section <a class="reference internal" href="ext/appapi.html#domain-api"><em>Domain API</em></a>.</p>
</div>
<div class="section" id="basic-markup">
<span id="basic-domain-markup"></span><h2>Basic Markup<a class="headerlink" href="#basic-markup" title="Permalink to this headline">¶</a></h2>
<p>Most domains provide a number of <em class="dfn">object description directives</em>, used to
describe specific objects provided by modules. Each directive requires one or
more signatures to provide basic information about what is being described, and
the content should be the description. The basic version makes entries in the
general index; if no index entry is desired, you can give the directive option
flag <tt class="docutils literal"><span class="pre">:noindex:</span></tt>. An example using a Python domain directive:</p>
<div class="highlight-rst"><pre>.. py:function:: spam(eggs)
ham(eggs)
Spam or ham the foo.</pre>
</div>
<p>This describes the two Python functions <tt class="docutils literal"><span class="pre">spam</span></tt> and <tt class="docutils literal"><span class="pre">ham</span></tt>. (Note that when
signatures become too long, you can break them if you add a backslash to lines
that are continued in the next line. Example:</p>
<div class="highlight-rst"><pre>.. py:function:: filterwarnings(action, message='', category=Warning, \
module='', lineno=0, append=False)
:noindex:</pre>
</div>
<p>(This example also shows how to use the <tt class="docutils literal"><span class="pre">:noindex:</span></tt> flag.)</p>
<p>The domains also provide roles that link back to these object descriptions. For
example, to link to one of the functions described in the example above, you
could say</p>
<div class="highlight-rst"><pre>The function :py:func:`spam` does a similar thing.</pre>
</div>
<p>As you can see, both directive and role names contain the domain name and the
directive name.</p>
<p class="rubric">Default Domain</p>
<p>To avoid having to writing the domain name all the time when you e.g. only
describe Python objects, a default domain can be selected with either the config
value <a class="reference internal" href="config.html#confval-primary_domain"><tt class="xref std std-confval docutils literal"><span class="pre">primary_domain</span></tt></a> or this directive:</p>
<dl class="directive">
<dt id="directive-default-domain">
<tt class="descname">.. default-domain::</tt><tt class="descclassname"> name</tt><a class="headerlink" href="#directive-default-domain" title="Permalink to this definition">¶</a></dt>
<dd><p>Select a new default domain. While the <a class="reference internal" href="config.html#confval-primary_domain"><tt class="xref std std-confval docutils literal"><span class="pre">primary_domain</span></tt></a> selects a
global default, this only has an effect within the same file.</p>
</dd></dl>
<p>If no other default is selected, the Python domain (named <tt class="docutils literal"><span class="pre">py</span></tt>) is the default
one, mostly for compatibility with documentation written for older versions of
Sphinx.</p>
<p>Directives and roles that belong to the default domain can be mentioned without
giving the domain name, i.e.</p>
<div class="highlight-rst"><pre>.. function:: pyfunc()
Describes a Python function.
Reference to :func:`pyfunc`.</pre>
</div>
<div class="section" id="cross-referencing-syntax">
<h3>Cross-referencing syntax<a class="headerlink" href="#cross-referencing-syntax" title="Permalink to this headline">¶</a></h3>
<p>For cross-reference roles provided by domains, the same facilities exist as for
general cross-references. See <a class="reference internal" href="markup/inline.html#xref-syntax"><em>Cross-referencing syntax</em></a>.</p>
<p>In short:</p>
<ul class="simple">
<li>You may supply an explicit title and reference target: <tt class="docutils literal"><span class="pre">:role:`title</span>
<span class="pre"><target>`</span></tt> will refer to <em>target</em>, but the link text will be <em>title</em>.</li>
<li>If you prefix the content with <tt class="docutils literal"><span class="pre">!</span></tt>, no reference/hyperlink will be created.</li>
<li>If you prefix the content with <tt class="docutils literal"><span class="pre">~</span></tt>, the link text will only be the last
component of the target. For example, <tt class="docutils literal"><span class="pre">:py:meth:`~Queue.Queue.get`</span></tt> will
refer to <tt class="docutils literal"><span class="pre">Queue.Queue.get</span></tt> but only display <tt class="docutils literal"><span class="pre">get</span></tt> as the link text.</li>
</ul>
</div>
</div>
<div class="section" id="the-python-domain">
<h2>The Python Domain<a class="headerlink" href="#the-python-domain" title="Permalink to this headline">¶</a></h2>
<p>The Python domain (name <strong>py</strong>) provides the following directives for module
declarations:</p>
<dl class="directive">
<dt id="directive-py:module">
<tt class="descname">.. py:module::</tt><tt class="descclassname"> name</tt><a class="headerlink" href="#directive-py:module" title="Permalink to this definition">¶</a></dt>
<dd><p>This directive marks the beginning of the description of a module (or package
submodule, in which case the name should be fully qualified, including the
package name). It does not create content (like e.g. <a class="reference internal" href="#directive-py:class" title="py:class directive"><tt class="xref rst rst-dir docutils literal"><span class="pre">py:class</span></tt></a> does).</p>
<p>This directive will also cause an entry in the global module index.</p>
<p>The <tt class="docutils literal"><span class="pre">platform</span></tt> option, if present, is a comma-separated list of the
platforms on which the module is available (if it is available on all
platforms, the option should be omitted). The keys are short identifiers;
examples that are in use include “IRIX”, “Mac”, “Windows”, and “Unix”. It is
important to use a key which has already been used when applicable.</p>
<p>The <tt class="docutils literal"><span class="pre">synopsis</span></tt> option should consist of one sentence describing the
module’s purpose – it is currently only used in the Global Module Index.</p>
<p>The <tt class="docutils literal"><span class="pre">deprecated</span></tt> option can be given (with no value) to mark a module as
deprecated; it will be designated as such in various locations then.</p>
</dd></dl>
<dl class="directive">
<dt id="directive-py:currentmodule">
<tt class="descname">.. py:currentmodule::</tt><tt class="descclassname"> name</tt><a class="headerlink" href="#directive-py:currentmodule" title="Permalink to this definition">¶</a></dt>
<dd><p>This directive tells Sphinx that the classes, functions etc. documented from
here are in the given module (like <a class="reference internal" href="#directive-py:module" title="py:module directive"><tt class="xref rst rst-dir docutils literal"><span class="pre">py:module</span></tt></a>), but it will not
create index entries, an entry in the Global Module Index, or a link target
for <a class="reference internal" href="#role-py:mod" title="py:mod role"><tt class="xref rst rst-role docutils literal"><span class="pre">py:mod</span></tt></a>. This is helpful in situations where documentation
for things in a module is spread over multiple files or sections – one
location has the <a class="reference internal" href="#directive-py:module" title="py:module directive"><tt class="xref rst rst-dir docutils literal"><span class="pre">py:module</span></tt></a> directive, the others only
<a class="reference internal" href="#directive-py:currentmodule" title="py:currentmodule directive"><tt class="xref rst rst-dir docutils literal"><span class="pre">py:currentmodule</span></tt></a>.</p>
</dd></dl>
<p>The following directives are provided for module and class contents:</p>
<dl class="directive">
<dt id="directive-py:data">
<tt class="descname">.. py:data::</tt><tt class="descclassname"> name</tt><a class="headerlink" href="#directive-py:data" title="Permalink to this definition">¶</a></dt>
<dd><p>Describes global data in a module, including both variables and values used
as “defined constants.” Class and object attributes are not documented
using this environment.</p>
</dd></dl>
<dl class="directive">
<dt id="directive-py:exception">
<tt class="descname">.. py:exception::</tt><tt class="descclassname"> name</tt><a class="headerlink" href="#directive-py:exception" title="Permalink to this definition">¶</a></dt>
<dd><p>Describes an exception class. The signature can, but need not include
parentheses with constructor arguments.</p>
</dd></dl>
<dl class="directive">
<dt id="directive-py:function">
<tt class="descname">.. py:function::</tt><tt class="descclassname"> name(signature)</tt><a class="headerlink" href="#directive-py:function" title="Permalink to this definition">¶</a></dt>
<dd><p>Describes a module-level function. The signature should include the
parameters, enclosing optional parameters in brackets. Default values can be
given if it enhances clarity; see <a class="reference internal" href="#signatures"><em>Python Signatures</em></a>. For example:</p>
<div class="highlight-rst"><pre>.. py:function:: Timer.repeat([repeat=3[, number=1000000]])</pre>
</div>
<p>Object methods are not documented using this directive. Bound object methods
placed in the module namespace as part of the public interface of the module
are documented using this, as they are equivalent to normal functions for
most purposes.</p>
<p>The description should include information about the parameters required and
how they are used (especially whether mutable objects passed as parameters
are modified), side effects, and possible exceptions. A small example may be
provided.</p>
</dd></dl>
<dl class="directive">
<dt id="directive-py:class">
<tt class="descname">.. py:class::</tt><tt class="descclassname"> name[(signature)]</tt><a class="headerlink" href="#directive-py:class" title="Permalink to this definition">¶</a></dt>
<dd><p>Describes a class. The signature can include parentheses with parameters
which will be shown as the constructor arguments. See also
<a class="reference internal" href="#signatures"><em>Python Signatures</em></a>.</p>
<p>Methods and attributes belonging to the class should be placed in this
directive’s body. If they are placed outside, the supplied name should
contain the class name so that cross-references still work. Example:</p>
<div class="highlight-rst"><pre>.. py:class:: Foo
.. py:method:: quux()
-- or --
.. py:class:: Bar
.. py:method:: Bar.quux()</pre>
</div>
<p>The first way is the preferred one.</p>
</dd></dl>
<dl class="directive">
<dt id="directive-py:attribute">
<tt class="descname">.. py:attribute::</tt><tt class="descclassname"> name</tt><a class="headerlink" href="#directive-py:attribute" title="Permalink to this definition">¶</a></dt>
<dd><p>Describes an object data attribute. The description should include
information about the type of the data to be expected and whether it may be
changed directly.</p>
</dd></dl>
<dl class="directive">
<dt id="directive-py:method">
<tt class="descname">.. py:method::</tt><tt class="descclassname"> name(signature)</tt><a class="headerlink" href="#directive-py:method" title="Permalink to this definition">¶</a></dt>
<dd><p>Describes an object method. The parameters should not include the <tt class="docutils literal"><span class="pre">self</span></tt>
parameter. The description should include similar information to that
described for <tt class="docutils literal"><span class="pre">function</span></tt>. See also <a class="reference internal" href="#signatures"><em>Python Signatures</em></a>.</p>
</dd></dl>
<dl class="directive">
<dt id="directive-py:staticmethod">
<tt class="descname">.. py:staticmethod::</tt><tt class="descclassname"> name(signature)</tt><a class="headerlink" href="#directive-py:staticmethod" title="Permalink to this definition">¶</a></dt>
<dd><p>Like <a class="reference internal" href="#directive-py:method" title="py:method directive"><tt class="xref rst rst-dir docutils literal"><span class="pre">py:method</span></tt></a>, but indicates that the method is a static method.</p>
<p class="versionadded">
<span class="versionmodified">New in version 0.4.</span></p>
</dd></dl>
<dl class="directive">
<dt id="directive-py:classmethod">
<tt class="descname">.. py:classmethod::</tt><tt class="descclassname"> name(signature)</tt><a class="headerlink" href="#directive-py:classmethod" title="Permalink to this definition">¶</a></dt>
<dd><p>Like <a class="reference internal" href="#directive-py:method" title="py:method directive"><tt class="xref rst rst-dir docutils literal"><span class="pre">py:method</span></tt></a>, but indicates that the method is a class method.</p>
<p class="versionadded">
<span class="versionmodified">New in version 0.6.</span></p>
</dd></dl>
<dl class="directive">
<dt id="directive-py:decorator">
<tt class="descname">.. py:decorator::</tt><tt class="descclassname"> name</tt><a class="headerlink" href="#directive-py:decorator" title="Permalink to this definition">¶</a></dt>
<dt>
<tt class="descname">.. py:decorator::</tt><tt class="descclassname"> name(signature)</tt></dt>
<dd><p>Describes a decorator function. The signature should <em>not</em> represent the
signature of the actual function, but the usage as a decorator. For example,
given the functions</p>
<div class="highlight-python"><pre>def removename(func):
func.__name__ = ''
return func
def setnewname(name):
def decorator(func):
func.__name__ = name
return func
return decorator</pre>
</div>
<p>the descriptions should look like this:</p>
<div class="highlight-rst"><pre>.. py:decorator:: removename
Remove name of the decorated function.
.. py:decorator:: setnewname(name)
Set name of the decorated function to *name*.</pre>
</div>
<p>There is no <tt class="docutils literal"><span class="pre">py:deco</span></tt> role to link to a decorator that is marked up with
this directive; rather, use the <a class="reference internal" href="#role-py:func" title="py:func role"><tt class="xref rst rst-role docutils literal"><span class="pre">py:func</span></tt></a> role.</p>
</dd></dl>
<dl class="directive">
<dt id="directive-py:decoratormethod">
<tt class="descname">.. py:decoratormethod::</tt><tt class="descclassname"> name</tt><a class="headerlink" href="#directive-py:decoratormethod" title="Permalink to this definition">¶</a></dt>
<dt>
<tt class="descname">.. py:decoratormethod::</tt><tt class="descclassname"> name(signature)</tt></dt>
<dd><p>Same as <a class="reference internal" href="#directive-py:decorator" title="py:decorator directive"><tt class="xref rst rst-dir docutils literal"><span class="pre">py:decorator</span></tt></a>, but for decorators that are methods.</p>
<p>Refer to a decorator method using the <a class="reference internal" href="#role-py:meth" title="py:meth role"><tt class="xref rst rst-role docutils literal"><span class="pre">py:meth</span></tt></a> role.</p>
</dd></dl>
<div class="section" id="python-signatures">
<span id="signatures"></span><h3>Python Signatures<a class="headerlink" href="#python-signatures" title="Permalink to this headline">¶</a></h3>
<p>Signatures of functions, methods and class constructors can be given like they
would be written in Python, with the exception that optional parameters can be
indicated by brackets:</p>
<div class="highlight-rst"><pre>.. py:function:: compile(source[, filename[, symbol]])</pre>
</div>
<p>It is customary to put the opening bracket before the comma. In addition to
this “nested” bracket style, a “flat” style can also be used, due to the fact
that most optional parameters can be given independently:</p>
<div class="highlight-rst"><pre>.. py:function:: compile(source[, filename, symbol])</pre>
</div>
<p>Default values for optional arguments can be given (but if they contain commas,
they will confuse the signature parser). Python 3-style argument annotations
can also be given as well as return type annotations:</p>
<div class="highlight-rst"><pre>.. py:function:: compile(source : string[, filename, symbol]) -> ast object</pre>
</div>
</div>
<div class="section" id="info-field-lists">
<h3>Info field lists<a class="headerlink" href="#info-field-lists" title="Permalink to this headline">¶</a></h3>
<p class="versionadded">
<span class="versionmodified">New in version 0.4.</span></p>
<p>Inside Python object description directives, reST field lists with these fields
are recognized and formatted nicely:</p>
<ul class="simple">
<li><tt class="docutils literal"><span class="pre">param</span></tt>, <tt class="docutils literal"><span class="pre">parameter</span></tt>, <tt class="docutils literal"><span class="pre">arg</span></tt>, <tt class="docutils literal"><span class="pre">argument</span></tt>, <tt class="docutils literal"><span class="pre">key</span></tt>, <tt class="docutils literal"><span class="pre">keyword</span></tt>:
Description of a parameter.</li>
<li><tt class="docutils literal"><span class="pre">type</span></tt>: Type of a parameter.</li>
<li><tt class="docutils literal"><span class="pre">raises</span></tt>, <tt class="docutils literal"><span class="pre">raise</span></tt>, <tt class="docutils literal"><span class="pre">except</span></tt>, <tt class="docutils literal"><span class="pre">exception</span></tt>: That (and when) a specific
exception is raised.</li>
<li><tt class="docutils literal"><span class="pre">var</span></tt>, <tt class="docutils literal"><span class="pre">ivar</span></tt>, <tt class="docutils literal"><span class="pre">cvar</span></tt>: Description of a variable.</li>
<li><tt class="docutils literal"><span class="pre">returns</span></tt>, <tt class="docutils literal"><span class="pre">return</span></tt>: Description of the return value.</li>
<li><tt class="docutils literal"><span class="pre">rtype</span></tt>: Return type.</li>
</ul>
<p>The field names must consist of one of these keywords and an argument (except
for <tt class="docutils literal"><span class="pre">returns</span></tt> and <tt class="docutils literal"><span class="pre">rtype</span></tt>, which do not need an argument). This is best
explained by an example:</p>
<div class="highlight-rst"><pre>.. py:function:: format_exception(etype, value, tb[, limit=None])
Format the exception with a traceback.
:param etype: exception type
:param value: exception value
:param tb: traceback object
:param limit: maximum number of stack frames to show
:type limit: integer or None
:rtype: list of strings</pre>
</div>
<p>This will render like this:</p>
<blockquote>
<div><dl class="function">
<dt>
<tt class="descname">format_exception</tt><big>(</big><em>etype</em>, <em>value</em>, <em>tb</em><span class="optional">[</span>, <em>limit=None</em><span class="optional">]</span><big>)</big></dt>
<dd><p>Format the exception with a traceback.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple">
<li><strong>etype</strong> – exception type</li>
<li><strong>value</strong> – exception value</li>
<li><strong>tb</strong> – traceback object</li>
<li><strong>limit</strong> (<em>integer or None</em>) – maximum number of stack frames to show</li>
</ul>
</td>
</tr>
<tr class="field-even field"><th class="field-name">Return type:</th><td class="field-body"><p class="first last">list of strings</p>
</td>
</tr>
</tbody>
</table>
</dd></dl>
</div></blockquote>
<p>It is also possible to combine parameter type and description, if the type is a
single word, like this:</p>
<div class="highlight-rst"><pre>:param integer limit: maximum number of stack frames to show</pre>
</div>
</div>
<div class="section" id="cross-referencing-python-objects">
<span id="python-roles"></span><h3>Cross-referencing Python objects<a class="headerlink" href="#cross-referencing-python-objects" title="Permalink to this headline">¶</a></h3>
<p>The following roles refer to objects in modules and are possibly hyperlinked if
a matching identifier is found:</p>
<dl class="role">
<dt id="role-py:mod">
<tt class="descname">:py:mod:</tt><a class="headerlink" href="#role-py:mod" title="Permalink to this definition">¶</a></dt>
<dd><p>Reference a module; a dotted name may be used. This should also be used for
package names.</p>
</dd></dl>
<dl class="role">
<dt id="role-py:func">
<tt class="descname">:py:func:</tt><a class="headerlink" href="#role-py:func" title="Permalink to this definition">¶</a></dt>
<dd><p>Reference a Python function; dotted names may be used. The role text needs
not include trailing parentheses to enhance readability; they will be added
automatically by Sphinx if the <a class="reference internal" href="config.html#confval-add_function_parentheses"><tt class="xref std std-confval docutils literal"><span class="pre">add_function_parentheses</span></tt></a> config
value is true (the default).</p>
</dd></dl>
<dl class="role">
<dt id="role-py:data">
<tt class="descname">:py:data:</tt><a class="headerlink" href="#role-py:data" title="Permalink to this definition">¶</a></dt>
<dd><p>Reference a module-level variable.</p>
</dd></dl>
<dl class="role">
<dt id="role-py:const">
<tt class="descname">:py:const:</tt><a class="headerlink" href="#role-py:const" title="Permalink to this definition">¶</a></dt>
<dd><p>Reference a “defined” constant. This may be a C-language <tt class="docutils literal"><span class="pre">#define</span></tt> or a
Python variable that is not intended to be changed.</p>
</dd></dl>
<dl class="role">
<dt id="role-py:class">
<tt class="descname">:py:class:</tt><a class="headerlink" href="#role-py:class" title="Permalink to this definition">¶</a></dt>
<dd><p>Reference a class; a dotted name may be used.</p>
</dd></dl>
<dl class="role">
<dt id="role-py:meth">
<tt class="descname">:py:meth:</tt><a class="headerlink" href="#role-py:meth" title="Permalink to this definition">¶</a></dt>
<dd><p>Reference a method of an object. The role text can include the type name and
the method name; if it occurs within the description of a type, the type name
can be omitted. A dotted name may be used.</p>
</dd></dl>
<dl class="role">
<dt id="role-py:attr">
<tt class="descname">:py:attr:</tt><a class="headerlink" href="#role-py:attr" title="Permalink to this definition">¶</a></dt>
<dd><p>Reference a data attribute of an object.</p>
</dd></dl>
<dl class="role">
<dt id="role-py:exc">
<tt class="descname">:py:exc:</tt><a class="headerlink" href="#role-py:exc" title="Permalink to this definition">¶</a></dt>
<dd><p>Reference an exception. A dotted name may be used.</p>
</dd></dl>
<dl class="role">
<dt id="role-py:obj">
<tt class="descname">:py:obj:</tt><a class="headerlink" href="#role-py:obj" title="Permalink to this definition">¶</a></dt>
<dd><p>Reference an object of unspecified type. Useful e.g. as the
<a class="reference internal" href="config.html#confval-default_role"><tt class="xref std std-confval docutils literal"><span class="pre">default_role</span></tt></a>.</p>
<p class="versionadded">
<span class="versionmodified">New in version 0.4.</span></p>
</dd></dl>
<p>The name enclosed in this markup can include a module name and/or a class name.
For example, <tt class="docutils literal"><span class="pre">:py:func:`filter`</span></tt> could refer to a function named <tt class="docutils literal"><span class="pre">filter</span></tt> in
the current module, or the built-in function of that name. In contrast,
<tt class="docutils literal"><span class="pre">:py:func:`foo.filter`</span></tt> clearly refers to the <tt class="docutils literal"><span class="pre">filter</span></tt> function in the
<tt class="docutils literal"><span class="pre">foo</span></tt> module.</p>
<p>Normally, names in these roles are searched first without any further
qualification, then with the current module name prepended, then with the
current module and class name (if any) prepended. If you prefix the name with a
dot, this order is reversed. For example, in the documentation of Python’s
<tt class="xref py py-mod docutils literal"><span class="pre">codecs</span></tt> module, <tt class="docutils literal"><span class="pre">:py:func:`open`</span></tt> always refers to the built-in
function, while <tt class="docutils literal"><span class="pre">:py:func:`.open`</span></tt> refers to <tt class="xref py py-func docutils literal"><span class="pre">codecs.open()</span></tt>.</p>
<p>A similar heuristic is used to determine whether the name is an attribute of the
currently documented class.</p>
<p>Also, if the name is prefixed with a dot, and no exact match is found, the
target is taken as a suffix and all object names with that suffix are
searched. For example, <tt class="docutils literal"><span class="pre">:py:meth:`.TarFile.close`</span></tt> references the
<tt class="docutils literal"><span class="pre">tarfile.TarFile.close()</span></tt> function, even if the current module is not
<tt class="docutils literal"><span class="pre">tarfile</span></tt>. Since this can get ambiguous, if there is more than one possible
match, you will get a warning from Sphinx.</p>
<p>Note that you can combine the <tt class="docutils literal"><span class="pre">~</span></tt> and <tt class="docutils literal"><span class="pre">.</span></tt> prefixes:
<tt class="docutils literal"><span class="pre">:py:meth:`~.TarFile.close`</span></tt> will reference the <tt class="docutils literal"><span class="pre">tarfile.TarFile.close()</span></tt>
method, but the visible link caption will only be <tt class="docutils literal"><span class="pre">close()</span></tt>.</p>
</div>
</div>
<div class="section" id="the-c-domain">
<span id="c-domain"></span><h2>The C Domain<a class="headerlink" href="#the-c-domain" title="Permalink to this headline">¶</a></h2>
<p>The C domain (name <strong>c</strong>) is suited for documentation of C API.</p>
<dl class="directive">
<dt id="directive-c:function">
<tt class="descname">.. c:function::</tt><tt class="descclassname"> type name(signature)</tt><a class="headerlink" href="#directive-c:function" title="Permalink to this definition">¶</a></dt>
<dd><p>Describes a C function. The signature should be given as in C, e.g.:</p>
<div class="highlight-rst"><pre>.. c:function:: PyObject* PyType_GenericAlloc(PyTypeObject *type, Py_ssize_t nitems)</pre>
</div>
<p>This is also used to describe function-like preprocessor macros. The names
of the arguments should be given so they may be used in the description.</p>
<p>Note that you don’t have to backslash-escape asterisks in the signature, as
it is not parsed by the reST inliner.</p>
</dd></dl>
<dl class="directive">
<dt id="directive-c:member">
<tt class="descname">.. c:member::</tt><tt class="descclassname"> type name</tt><a class="headerlink" href="#directive-c:member" title="Permalink to this definition">¶</a></dt>
<dd><p>Describes a C struct member. Example signature:</p>
<div class="highlight-rst"><pre>.. c:member:: PyObject* PyTypeObject.tp_bases</pre>
</div>
<p>The text of the description should include the range of values allowed, how
the value should be interpreted, and whether the value can be changed.
References to structure members in text should use the <tt class="docutils literal"><span class="pre">member</span></tt> role.</p>
</dd></dl>
<dl class="directive">
<dt id="directive-c:macro">
<tt class="descname">.. c:macro::</tt><tt class="descclassname"> name</tt><a class="headerlink" href="#directive-c:macro" title="Permalink to this definition">¶</a></dt>
<dd><p>Describes a “simple” C macro. Simple macros are macros which are used for
code expansion, but which do not take arguments so cannot be described as
functions. This is not to be used for simple constant definitions. Examples
of its use in the Python documentation include <tt class="xref c c-macro docutils literal"><span class="pre">PyObject_HEAD</span></tt> and
<tt class="xref c c-macro docutils literal"><span class="pre">Py_BEGIN_ALLOW_THREADS</span></tt>.</p>
</dd></dl>
<dl class="directive">
<dt id="directive-c:type">
<tt class="descname">.. c:type::</tt><tt class="descclassname"> name</tt><a class="headerlink" href="#directive-c:type" title="Permalink to this definition">¶</a></dt>
<dd><p>Describes a C type (whether defined by a typedef or struct). The signature
should just be the type name.</p>
</dd></dl>
<dl class="directive">
<dt id="directive-c:var">
<tt class="descname">.. c:var::</tt><tt class="descclassname"> type name</tt><a class="headerlink" href="#directive-c:var" title="Permalink to this definition">¶</a></dt>
<dd><p>Describes a global C variable. The signature should include the type, such
as:</p>
<div class="highlight-rst"><pre>.. c:var:: PyObject* PyClass_Type</pre>
</div>
</dd></dl>
<div class="section" id="cross-referencing-c-constructs">
<span id="c-roles"></span><h3>Cross-referencing C constructs<a class="headerlink" href="#cross-referencing-c-constructs" title="Permalink to this headline">¶</a></h3>
<p>The following roles create cross-references to C-language constructs if they are
defined in the documentation:</p>
<dl class="role">
<dt id="role-c:data">
<tt class="descname">:c:data:</tt><a class="headerlink" href="#role-c:data" title="Permalink to this definition">¶</a></dt>
<dd><p>Reference a C-language variable.</p>
</dd></dl>
<dl class="role">
<dt id="role-c:func">
<tt class="descname">:c:func:</tt><a class="headerlink" href="#role-c:func" title="Permalink to this definition">¶</a></dt>
<dd><p>Reference a C-language function. Should include trailing parentheses.</p>
</dd></dl>
<dl class="role">
<dt id="role-c:macro">
<tt class="descname">:c:macro:</tt><a class="headerlink" href="#role-c:macro" title="Permalink to this definition">¶</a></dt>
<dd><p>Reference a “simple” C macro, as defined above.</p>
</dd></dl>
<dl class="role">
<dt id="role-c:type">
<tt class="descname">:c:type:</tt><a class="headerlink" href="#role-c:type" title="Permalink to this definition">¶</a></dt>
<dd><p>Reference a C-language type.</p>
</dd></dl>
</div>
</div>
<div class="section" id="id1">
<h2>The C++ Domain<a class="headerlink" href="#id1" title="Permalink to this headline">¶</a></h2>
<p>The C++ domain (name <strong>cpp</strong>) supports documenting C++ projects.</p>
<p>The following directives are available:</p>
<dl class="directive">
<dt id="directive-cpp:class">
<tt class="descname">.. cpp:class::</tt><tt class="descclassname"> signatures</tt><a class="headerlink" href="#directive-cpp:class" title="Permalink to this definition">¶</a></dt>
<dt id="directive-cpp:function">
<tt class="descname">.. cpp:function::</tt><tt class="descclassname"> signatures</tt><a class="headerlink" href="#directive-cpp:function" title="Permalink to this definition">¶</a></dt>
<dt id="directive-cpp:member">
<tt class="descname">.. cpp:member::</tt><tt class="descclassname"> signatures</tt><a class="headerlink" href="#directive-cpp:member" title="Permalink to this definition">¶</a></dt>
<dt id="directive-cpp:type">
<tt class="descname">.. cpp:type::</tt><tt class="descclassname"> signatures</tt><a class="headerlink" href="#directive-cpp:type" title="Permalink to this definition">¶</a></dt>
<dd><p>Describe a C++ object. Full signature specification is supported – give the
signature as you would in the declaration. Here some examples:</p>
<div class="highlight-rst"><pre>.. cpp:function:: bool namespaced::theclass::method(int arg1, std::string arg2)
Describes a method with parameters and types.
.. cpp:function:: bool namespaced::theclass::method(arg1, arg2)
Describes a method without types.
.. cpp:function:: const T &array<T>::operator[]() const
Describes the constant indexing operator of a templated array.
.. cpp:function:: operator bool() const
Describe a casting operator here.
.. cpp:function:: constexpr void foo(std::string &bar[2]) noexcept
Describe a constexpr function here.
.. cpp:member:: std::string theclass::name
.. cpp:member:: std::string theclass::name[N][M]
.. cpp:type:: theclass::const_iterator</pre>
</div>
<p>Will be rendered like this:</p>
<blockquote>
<div><dl class="function">
<dt id="namespaced::theclass::method__i.ss">
bool <tt class="descclassname">namespaced::theclass::</tt><tt class="descname">method</tt><big>(</big>int <em>arg1</em>, std::string <em>arg2</em><big>)</big><a class="headerlink" href="#namespaced::theclass::method__i.ss" title="Permalink to this definition">¶</a></dt>
<dd><p>Describes a method with parameters and types.</p>
</dd></dl>
<dl class="function">
<dt id="namespaced::theclass::method__X.X">
bool <tt class="descclassname">namespaced::theclass::</tt><tt class="descname">method</tt><big>(</big><em>arg1</em>, <em>arg2</em><big>)</big><a class="headerlink" href="#namespaced::theclass::method__X.X" title="Permalink to this definition">¶</a></dt>
<dd><p>Describes a method without types.</p>
</dd></dl>
<dl class="function">
<dt id="array:T:::subscript-operatorC">
const T& <tt class="descclassname">array<T>::</tt><tt class="descname">operator[]</tt><big>(</big><big>)</big><tt class="descclassname"> const</tt><a class="headerlink" href="#array:T:::subscript-operatorC" title="Permalink to this definition">¶</a></dt>
<dd><p>Describes the constant indexing operator of a templated array.</p>
</dd></dl>
<dl class="function">
<dt id="castto-b-operatorC">
<tt class="descname">operator</tt> bool<big>(</big><big>)</big><tt class="descclassname"> const</tt><a class="headerlink" href="#castto-b-operatorC" title="Permalink to this definition">¶</a></dt>
<dd><p>Describe a casting operator here.</p>
</dd></dl>
<dl class="function">
<dt id="foo__ssRACE">
<em class="property">constexpr</em> void <tt class="descname">foo</tt><big>(</big>std::string& <em>bar</em>[2]<big>)</big><tt class="descclassname"> noexcept</tt><a class="headerlink" href="#foo__ssRACE" title="Permalink to this definition">¶</a></dt>
<dd><p>Describe a constexpr function here.</p>
</dd></dl>
<dl class="member">
<dt id="theclass::name__ss">
std::string <tt class="descclassname">theclass::</tt><tt class="descname">name</tt><a class="headerlink" href="#theclass::name__ss" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<dl class="member">
<dt id="theclass::name__ssAA">
std::string <tt class="descclassname">theclass::</tt><tt class="descname">name</tt>[N][M]<a class="headerlink" href="#theclass::name__ssAA" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<dl class="type">
<dt id="theclass::const_iterator">
<em class="property">type </em><tt class="descclassname">theclass::</tt><tt class="descname">const_iterator</tt><a class="headerlink" href="#theclass::const_iterator" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
</div></blockquote>
</dd></dl>
<dl class="directive">
<dt id="directive-cpp:namespace">
<tt class="descname">.. cpp:namespace::</tt><tt class="descclassname"> namespace</tt><a class="headerlink" href="#directive-cpp:namespace" title="Permalink to this definition">¶</a></dt>
<dd><p>Select the current C++ namespace for the following objects.</p>
</dd></dl>
<p id="cpp-roles">These roles link to the given object types:</p>
<dl class="role">
<dt id="role-cpp:class">
<tt class="descname">:cpp:class:</tt><a class="headerlink" href="#role-cpp:class" title="Permalink to this definition">¶</a></dt>
<dt id="role-cpp:func">
<tt class="descname">:cpp:func:</tt><a class="headerlink" href="#role-cpp:func" title="Permalink to this definition">¶</a></dt>
<dt id="role-cpp:member">
<tt class="descname">:cpp:member:</tt><a class="headerlink" href="#role-cpp:member" title="Permalink to this definition">¶</a></dt>
<dt id="role-cpp:type">
<tt class="descname">:cpp:type:</tt><a class="headerlink" href="#role-cpp:type" title="Permalink to this definition">¶</a></dt>
<dd><p>Reference a C++ object. You can give the full signature (and need to, for
overloaded functions.)</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">Sphinx’ syntax to give references a custom title can interfere with
linking to template classes, if nothing follows the closing angle
bracket, i.e. if the link looks like this: <tt class="docutils literal"><span class="pre">:cpp:class:`MyClass<T>`</span></tt>.
This is interpreted as a link to <tt class="docutils literal"><span class="pre">T</span></tt> with a title of <tt class="docutils literal"><span class="pre">MyClass</span></tt>.
In this case, please escape the opening angle bracket with a backslash,
like this: <tt class="docutils literal"><span class="pre">:cpp:class:`MyClass\<T>`</span></tt>.</p>
</div>
</dd></dl>
<div class="admonition-note-on-references admonition">
<p class="first admonition-title">Note on References</p>
<p class="last">It is currently impossible to link to a specific version of an
overloaded method. Currently the C++ domain is the first domain
that has basic support for overloaded methods and until there is more
data for comparison we don’t want to select a bad syntax to reference a
specific overload. Currently Sphinx will link to the first overloaded
version of the method / function.</p>
</div>
</div>
<div class="section" id="the-standard-domain">
<h2>The Standard Domain<a class="headerlink" href="#the-standard-domain" title="Permalink to this headline">¶</a></h2>
<p>The so-called “standard” domain collects all markup that doesn’t warrant a
domain of its own. Its directives and roles are not prefixed with a domain
name.</p>
<p>The standard domain is also where custom object descriptions, added using the
<a class="reference internal" href="ext/appapi.html#sphinx.application.Sphinx.add_object_type" title="sphinx.application.Sphinx.add_object_type"><tt class="xref py py-func docutils literal"><span class="pre">add_object_type()</span></tt></a> API, are placed.</p>
<p>There is a set of directives allowing documenting command-line programs:</p>
<dl class="directive">
<dt id="directive-option">
<tt class="descname">.. option::</tt><tt class="descclassname"> name args, name args, ...</tt><a class="headerlink" href="#directive-option" title="Permalink to this definition">¶</a></dt>
<dd><p>Describes a command line option or switch. Option argument names should be
enclosed in angle brackets. Example:</p>
<div class="highlight-rst"><pre>.. option:: -m <module>, --module <module>
Run a module as a script.</pre>
</div>
<p>The directive will create a cross-reference target named after the <em>first</em>
option, referencable by <a class="reference internal" href="markup/inline.html#role-option" title="option role"><tt class="xref rst rst-role docutils literal"><span class="pre">option</span></tt></a> (in the example case, you’d use
something like <tt class="docutils literal"><span class="pre">:option:`-m`</span></tt>).</p>
</dd></dl>
<dl class="directive">
<dt id="directive-envvar">
<tt class="descname">.. envvar::</tt><tt class="descclassname"> name</tt><a class="headerlink" href="#directive-envvar" title="Permalink to this definition">¶</a></dt>
<dd><p>Describes an environment variable that the documented code or program uses or
defines. Referencable by <a class="reference internal" href="markup/inline.html#role-envvar" title="envvar role"><tt class="xref rst rst-role docutils literal"><span class="pre">envvar</span></tt></a>.</p>
</dd></dl>
<dl class="directive">
<dt id="directive-program">
<tt class="descname">.. program::</tt><tt class="descclassname"> name</tt><a class="headerlink" href="#directive-program" title="Permalink to this definition">¶</a></dt>
<dd><p>Like <a class="reference internal" href="#directive-py:currentmodule" title="py:currentmodule directive"><tt class="xref rst rst-dir docutils literal"><span class="pre">py:currentmodule</span></tt></a>, this directive produces no output. Instead, it
serves to notify Sphinx that all following <a class="reference internal" href="#directive-option" title="option directive"><tt class="xref rst rst-dir docutils literal"><span class="pre">option</span></tt></a> directives
document options for the program called <em>name</em>.</p>
<p>If you use <a class="reference internal" href="#directive-program" title="program directive"><tt class="xref rst rst-dir docutils literal"><span class="pre">program</span></tt></a>, you have to qualify the references in your
<a class="reference internal" href="markup/inline.html#role-option" title="option role"><tt class="xref rst rst-role docutils literal"><span class="pre">option</span></tt></a> roles by the program name, so if you have the following
situation</p>
<div class="highlight-rst"><pre>.. program:: rm
.. option:: -r
Work recursively.
.. program:: svn
.. option:: -r revision
Specify the revision to work upon.</pre>
</div>
<p>then <tt class="docutils literal"><span class="pre">:option:`rm</span> <span class="pre">-r`</span></tt> would refer to the first option, while
<tt class="docutils literal"><span class="pre">:option:`svn</span> <span class="pre">-r`</span></tt> would refer to the second one.</p>
<p>The program name may contain spaces (in case you want to document subcommands
like <tt class="docutils literal"><span class="pre">svn</span> <span class="pre">add</span></tt> and <tt class="docutils literal"><span class="pre">svn</span> <span class="pre">commit</span></tt> separately).</p>
<p class="versionadded">
<span class="versionmodified">New in version 0.5.</span></p>
</dd></dl>
<p>There is also a very generic object description directive, which is not tied to
any domain:</p>
<dl class="directive">
<dt id="directive-describe">
<tt class="descname">.. describe::</tt><tt class="descclassname"> text</tt><a class="headerlink" href="#directive-describe" title="Permalink to this definition">¶</a></dt>
<dt id="directive-object">
<tt class="descname">.. object::</tt><tt class="descclassname"> text</tt><a class="headerlink" href="#directive-object" title="Permalink to this definition">¶</a></dt>
<dd><p>This directive produces the same formatting as the specific ones provided by
domains, but does not create index entries or cross-referencing targets.
Example:</p>
<div class="highlight-rst"><pre>.. describe:: PAPER
You can set this variable to select a paper size.</pre>
</div>
</dd></dl>
</div>
<div class="section" id="the-javascript-domain">
<h2>The JavaScript Domain<a class="headerlink" href="#the-javascript-domain" title="Permalink to this headline">¶</a></h2>
<p>The JavaScript domain (name <strong>js</strong>) provides the following directives:</p>
<dl class="directive">
<dt id="directive-js:function">
<tt class="descname">.. js:function::</tt><tt class="descclassname"> name(signature)</tt><a class="headerlink" href="#directive-js:function" title="Permalink to this definition">¶</a></dt>
<dd><p>Describes a JavaScript function or method. If you want to describe
arguments as optional use square brackets as <a class="reference internal" href="#signatures"><em>documented</em></a> for Python signatures.</p>
<p>You can use fields to give more details about arguments and their expected
types, errors which may be thrown by the function, and the value being
returned:</p>
<div class="highlight-rst"><pre>.. js:function:: $.getJSON(href, callback[, errback])
:param string href: An URI to the location of the resource.
:param callback: Get's called with the object.
:param errback:
Get's called in case the request fails. And a lot of other
text so we need multiple lines
:throws SomeError: For whatever reason in that case.
:returns: Something</pre>
</div>
<p>This is rendered as:</p>
<blockquote>
<div><dl class="function">
<dt id="_S_.getJSON">
<tt class="descclassname">$.</tt><tt class="descname">getJSON</tt><big>(</big><em>href</em>, <em>callback</em><span class="optional">[</span>, <em>errback</em><span class="optional">]</span><big>)</big><a class="headerlink" href="#_S_.getJSON" title="Permalink to this definition">¶</a></dt>
<dd><table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Arguments:</th><td class="field-body"><ul class="first simple">
<li><strong>href</strong> (<em>string</em>) – An URI to the location of the resource.</li>
<li><strong>callback</strong> – Get’s called with the object.</li>
<li><strong>errback</strong> – Get’s called in case the request fails. And a lot of other
text so we need multiple lines.</li>
</ul>
</td>
</tr>
<tr class="field-even field"><th class="field-name" colspan="2">Throws SomeError:</th></tr>
<tr class="field-even field"><td> </td><td class="field-body"><p class="first">For whatever reason in that case.</p>
</td>
</tr>
<tr class="field-odd field"><th class="field-name">Returns:</th><td class="field-body"><p class="first last">Something</p>
</td>
</tr>
</tbody>
</table>
</dd></dl>
</div></blockquote>
</dd></dl>
<dl class="directive">
<dt id="directive-js:class">
<tt class="descname">.. js:class::</tt><tt class="descclassname"> name</tt><a class="headerlink" href="#directive-js:class" title="Permalink to this definition">¶</a></dt>
<dd><p>Describes a constructor that creates an object. This is basically like
a function but will show up with a <cite>class</cite> prefix:</p>
<div class="highlight-rst"><pre>.. js:class:: MyAnimal(name[, age])
:param string name: The name of the animal
:param number age: an optional age for the animal</pre>
</div>
<p>This is rendered as:</p>
<blockquote>
<div><dl class="class">
<dt id="MyAnimal">
<em class="property">class </em><tt class="descname">MyAnimal</tt><big>(</big><em>name</em><span class="optional">[</span>, <em>age</em><span class="optional">]</span><big>)</big><a class="headerlink" href="#MyAnimal" title="Permalink to this definition">¶</a></dt>
<dd><table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Arguments:</th><td class="field-body"><ul class="first last simple">
<li><strong>name</strong> (<em>string</em>) – The name of the animal</li>
<li><strong>age</strong> (<em>number</em>) – an optional age for the animal</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>
</div></blockquote>
</dd></dl>
<dl class="directive">
<dt id="directive-js:data">
<tt class="descname">.. js:data::</tt><tt class="descclassname"> name</tt><a class="headerlink" href="#directive-js:data" title="Permalink to this definition">¶</a></dt>
<dd><p>Describes a global variable or constant.</p>
</dd></dl>
<dl class="directive">
<dt id="directive-js:attribute">
<tt class="descname">.. js:attribute::</tt><tt class="descclassname"> object.name</tt><a class="headerlink" href="#directive-js:attribute" title="Permalink to this definition">¶</a></dt>
<dd><p>Describes the attribute <em>name</em> of <em>object</em>.</p>
</dd></dl>
<p id="js-roles">These roles are provided to refer to the described objects:</p>
<dl class="role">
<dt id="role-js:func">
<tt class="descname">:js:func:</tt><a class="headerlink" href="#role-js:func" title="Permalink to this definition">¶</a></dt>
<dt id="role-js:class">
<tt class="descname">:js:class:</tt><a class="headerlink" href="#role-js:class" title="Permalink to this definition">¶</a></dt>
<dt id="role-js:data">
<tt class="descname">:js:data:</tt><a class="headerlink" href="#role-js:data" title="Permalink to this definition">¶</a></dt>
<dt id="role-js:attr">
<tt class="descname">:js:attr:</tt><a class="headerlink" href="#role-js:attr" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
</div>
<div class="section" id="the-restructuredtext-domain">
<h2>The reStructuredText domain<a class="headerlink" href="#the-restructuredtext-domain" title="Permalink to this headline">¶</a></h2>
<p>The reStructuredText domain (name <strong>rst</strong>) provides the following directives:</p>
<dl class="directive">
<dt id="directive-rst:directive">
<tt class="descname">.. rst:directive::</tt><tt class="descclassname"> name</tt><a class="headerlink" href="#directive-rst:directive" title="Permalink to this definition">¶</a></dt>
<dd><p>Describes a reST directive. The <em>name</em> can be a single directive name or
actual directive syntax (<cite>..</cite> prefix and <cite>::</cite> suffix) with arguments that
will be rendered differently. For example:</p>
<div class="highlight-rst"><pre>.. rst:directive:: foo
Foo description.
.. rst:directive:: .. bar:: baz
Bar description.</pre>
</div>
<p>will be rendered as:</p>
<blockquote>
<div><dl class="directive">
<dt id="directive-foo">
<tt class="descname">.. foo::</tt><a class="headerlink" href="#directive-foo" title="Permalink to this definition">¶</a></dt>
<dd><p>Foo description.</p>
</dd></dl>
<dl class="directive">
<dt id="directive-bar">
<tt class="descname">.. bar::</tt><tt class="descclassname"> baz</tt><a class="headerlink" href="#directive-bar" title="Permalink to this definition">¶</a></dt>
<dd><p>Bar description.</p>
</dd></dl>
</div></blockquote>
</dd></dl>
<dl class="directive">
<dt id="directive-rst:role">
<tt class="descname">.. rst:role::</tt><tt class="descclassname"> name</tt><a class="headerlink" href="#directive-rst:role" title="Permalink to this definition">¶</a></dt>
<dd><p>Describes a reST role. For example:</p>
<div class="highlight-rst"><pre>.. rst:role:: foo
Foo description.</pre>
</div>
<p>will be rendered as:</p>
<blockquote>
<div><dl class="role">
<dt id="role-foo">
<tt class="descname">:foo:</tt><a class="headerlink" href="#role-foo" title="Permalink to this definition">¶</a></dt>
<dd><p>Foo description.</p>
</dd></dl>
</div></blockquote>
</dd></dl>
<p id="rst-roles">These roles are provided to refer to the described objects:</p>
<dl class="role">
<dt id="role-rst:dir">
<tt class="descname">:rst:dir:</tt><a class="headerlink" href="#role-rst:dir" title="Permalink to this definition">¶</a></dt>
<dt id="role-rst:role">
<tt class="descname">:rst:role:</tt><a class="headerlink" href="#role-rst:role" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
</div>
<div class="section" id="more-domains">
<h2>More domains<a class="headerlink" href="#more-domains" title="Permalink to this headline">¶</a></h2>
<p>The <a class="reference external" href="https://bitbucket.org/birkenfeld/sphinx-contrib/">sphinx-contrib</a> repository contains more domains available as extensions;
currently a Ruby and an Erlang domain.</p>
</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="builders.html" title="Available builders"
>next</a> |</li>
<li class="right" >
<a href="markup/misc.html" title="Miscellaneous markup"
>previous</a> |</li>
<li><a href="index.html">Sphinx home</a> | </li>
<li><a href="contents.html">Documentation</a>
»</li>
</ul>
</div>
<div class="footer">
© Copyright 2007-2011, Georg Brandl.
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
</div>
</body>
</html>
distrib
>
Mageia
>
4
>
i586
>
media
>
core-release
>
by-pkgid
>
c95717a2237548a7bdaddf39c85b0f0f
>
files
>
95
