<!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 — 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="next" title="Tutorial: Writing a simple extension" href="ext/tutorial.html" />
<link rel="prev" title="Templating" href="templating.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="ext/tutorial.html" title="Tutorial: Writing a simple extension"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="templating.html" title="Templating"
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 Extensions</a><ul>
<li><a class="reference internal" href="#builtin-sphinx-extensions">Builtin Sphinx extensions</a><ul>
</ul>
</li>
<li><a class="reference internal" href="#third-party-extensions">Third-party extensions</a><ul>
<li><a class="reference internal" href="#where-to-put-your-own-extensions">Where to put your own extensions?</a></li>
</ul>
</li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="templating.html"
title="previous chapter">Templating</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="ext/tutorial.html"
title="next chapter">Tutorial: Writing a simple extension</a></p>
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="_sources/extensions.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.application">
<span id="sphinx-extensions"></span><span id="extensions"></span><h1>Sphinx Extensions<a class="headerlink" href="#module-sphinx.application" title="Permalink to this headline">¶</a></h1>
<p>Since many projects will need special features in their documentation, Sphinx is
designed to be extensible on several levels.</p>
<p>This is what you can do in an extension: First, you can add new
<a class="reference internal" href="glossary.html#term-builder"><em class="xref std std-term">builder</em></a>s to support new output formats or actions on the parsed
documents. Then, it is possible to register custom reStructuredText roles and
directives, extending the markup. And finally, there are so-called “hook
points” at strategic places throughout the build process, where an extension can
register a hook and run specialized code.</p>
<p>An extension is simply a Python module. When an extension is loaded, Sphinx
imports this module and executes its <tt class="docutils literal"><span class="pre">setup()</span></tt> function, which in turn
notifies Sphinx of everything the extension offers – see the extension tutorial
for examples.</p>
<p>The configuration file itself can be treated as an extension if it contains a
<tt class="docutils literal"><span class="pre">setup()</span></tt> function. All other extensions to load must be listed in the
<a class="reference internal" href="config.html#confval-extensions"><tt class="xref std std-confval docutils literal"><span class="pre">extensions</span></tt></a> configuration value.</p>
<div class="toctree-wrapper compound">
<ul>
<li class="toctree-l1"><a class="reference internal" href="ext/tutorial.html">Tutorial: Writing a simple extension</a><ul>
<li class="toctree-l2"><a class="reference internal" href="ext/tutorial.html#build-phases">Build Phases</a></li>
<li class="toctree-l2"><a class="reference internal" href="ext/tutorial.html#extension-design">Extension Design</a></li>
<li class="toctree-l2"><a class="reference internal" href="ext/tutorial.html#the-setup-function">The Setup Function</a></li>
<li class="toctree-l2"><a class="reference internal" href="ext/tutorial.html#the-node-classes">The Node Classes</a></li>
<li class="toctree-l2"><a class="reference internal" href="ext/tutorial.html#the-directive-classes">The Directive Classes</a></li>
<li class="toctree-l2"><a class="reference internal" href="ext/tutorial.html#the-event-handlers">The Event Handlers</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="ext/appapi.html">Extension API</a><ul>
<li class="toctree-l2"><a class="reference internal" href="ext/appapi.html#sphinx-core-events">Sphinx core events</a></li>
<li class="toctree-l2"><a class="reference internal" href="ext/appapi.html#the-template-bridge">The template bridge</a></li>
<li class="toctree-l2"><a class="reference internal" href="ext/appapi.html#module-sphinx.domains">Domain API</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="ext/builderapi.html">Writing new builders</a></li>
</ul>
</div>
<div class="section" id="builtin-sphinx-extensions">
<h2>Builtin Sphinx extensions<a class="headerlink" href="#builtin-sphinx-extensions" title="Permalink to this headline">¶</a></h2>
<p>These extensions are built in and can be activated by respective entries in the
<a class="reference internal" href="config.html#confval-extensions"><tt class="xref std std-confval docutils literal"><span class="pre">extensions</span></tt></a> configuration value:</p>
<div class="toctree-wrapper compound">
<ul>
<li class="toctree-l1"><a class="reference internal" href="ext/autodoc.html"><tt class="docutils literal"><span class="pre">sphinx.ext.autodoc</span></tt> – Include documentation from docstrings</a><ul>
<li class="toctree-l2"><a class="reference internal" href="ext/autodoc.html#docstring-preprocessing">Docstring preprocessing</a></li>
<li class="toctree-l2"><a class="reference internal" href="ext/autodoc.html#skipping-members">Skipping members</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="ext/autosummary.html"><tt class="docutils literal"><span class="pre">sphinx.ext.autosummary</span></tt> – Generate autodoc summaries</a><ul>
<li class="toctree-l2"><a class="reference internal" href="ext/autosummary.html#sphinx-autogen-generate-autodoc-stub-pages"><strong class="program">sphinx-autogen</strong> – generate autodoc stub pages</a></li>
<li class="toctree-l2"><a class="reference internal" href="ext/autosummary.html#generating-stub-pages-automatically">Generating stub pages automatically</a></li>
<li class="toctree-l2"><a class="reference internal" href="ext/autosummary.html#customizing-templates">Customizing templates</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="ext/doctest.html"><tt class="docutils literal"><span class="pre">sphinx.ext.doctest</span></tt> – Test snippets in the documentation</a></li>
<li class="toctree-l1"><a class="reference internal" href="ext/intersphinx.html"><tt class="docutils literal"><span class="pre">sphinx.ext.intersphinx</span></tt> – Link to other projects’ documentation</a></li>
<li class="toctree-l1"><a class="reference internal" href="ext/math.html">Math support in Sphinx</a><ul>
<li class="toctree-l2"><a class="reference internal" href="ext/math.html#module-sphinx.ext.pngmath"><tt class="docutils literal"><span class="pre">sphinx.ext.pngmath</span></tt> – Render math as PNG images</a></li>
<li class="toctree-l2"><a class="reference internal" href="ext/math.html#module-sphinx.ext.jsmath"><tt class="docutils literal"><span class="pre">sphinx.ext.jsmath</span></tt> – Render math via JavaScript</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="ext/graphviz.html"><tt class="docutils literal"><span class="pre">sphinx.ext.graphviz</span></tt> – Add Graphviz graphs</a></li>
<li class="toctree-l1"><a class="reference internal" href="ext/inheritance.html"><tt class="docutils literal"><span class="pre">sphinx.ext.inheritance_diagram</span></tt> – Include inheritance diagrams</a></li>
<li class="toctree-l1"><a class="reference internal" href="ext/refcounting.html"><tt class="docutils literal"><span class="pre">sphinx.ext.refcounting</span></tt> – Keep track of reference counting behavior</a></li>
<li class="toctree-l1"><a class="reference internal" href="ext/ifconfig.html"><tt class="docutils literal"><span class="pre">sphinx.ext.ifconfig</span></tt> – Include content based on configuration</a></li>
<li class="toctree-l1"><a class="reference internal" href="ext/coverage.html"><tt class="docutils literal"><span class="pre">sphinx.ext.coverage</span></tt> – Collect doc coverage stats</a></li>
<li class="toctree-l1"><a class="reference internal" href="ext/todo.html"><tt class="docutils literal"><span class="pre">sphinx.ext.todo</span></tt> – Support for todo items</a></li>
<li class="toctree-l1"><a class="reference internal" href="ext/extlinks.html"><tt class="docutils literal"><span class="pre">sphinx.ext.extlinks</span></tt> – Markup to shorten external links</a></li>
<li class="toctree-l1"><a class="reference internal" href="ext/viewcode.html"><tt class="docutils literal"><span class="pre">sphinx.ext.viewcode</span></tt> – Add links to highlighted source code</a></li>
<li class="toctree-l1"><a class="reference internal" href="ext/oldcmarkup.html"><tt class="docutils literal"><span class="pre">sphinx.ext.oldcmarkup</span></tt> – Compatibility extension for old C markup</a></li>
</ul>
</div>
</div>
<div class="section" id="third-party-extensions">
<h2>Third-party extensions<a class="headerlink" href="#third-party-extensions" title="Permalink to this headline">¶</a></h2>
<p>You can find several extensions contributed by users in the <a class="reference external" href="http://www.bitbucket.org/birkenfeld/sphinx-contrib">Sphinx Contrib</a>
repository. It is open for anyone who wants to maintain an extension
publicly; just send a short message asking for write permissions.</p>
<p>There are also several extensions hosted elsewhere. The <a class="reference external" href="http://www.bitbucket.org/birkenfeld/sphinx/wiki/Home">Wiki at BitBucket</a>
maintains a list of those.</p>
<p>If you write an extension that you think others will find useful or you think
should be included as a part of Sphinx, please write to the project mailing
list (<a class="reference external" href="http://groups.google.com/group/sphinx-dev">join here</a>).</p>
<div class="section" id="where-to-put-your-own-extensions">
<h3>Where to put your own extensions?<a class="headerlink" href="#where-to-put-your-own-extensions" title="Permalink to this headline">¶</a></h3>
<p>Extensions local to a project should be put within the project’s directory
structure. Set Python’s module search path, <tt class="docutils literal"><span class="pre">sys.path</span></tt>, accordingly so that
Sphinx can find them.
E.g., if your extension <tt class="docutils literal"><span class="pre">foo.py</span></tt> lies in the <tt class="docutils literal"><span class="pre">exts</span></tt> subdirectory of the
project root, put into <tt class="file docutils literal"><span class="pre">conf.py</span></tt>:</p>
<div class="highlight-python"><pre>import sys, os
sys.path.append(os.path.abspath('exts'))
extensions = ['foo']</pre>
</div>
<p>You can also install extensions anywhere else on <tt class="docutils literal"><span class="pre">sys.path</span></tt>, e.g. in the
<tt class="docutils literal"><span class="pre">site-packages</span></tt> directory.</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="ext/tutorial.html" title="Tutorial: Writing a simple extension"
>next</a> |</li>
<li class="right" >
<a href="templating.html" title="Templating"
>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.0.7.
</div>
</body>
</html>
distrib
>
Fedora
>
14
>
x86_64
>
media
>
updates
>
by-pkgid
>
2b39e69e45f9a0b2b3aece7339c56216
>
files
>
96
