<!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>The build configuration file — 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="HTML theming support" href="theming.html" />
<link rel="prev" title="Available builders" href="builders.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="theming.html" title="HTML theming support"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="builders.html" title="Available builders"
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="#">The build configuration file</a><ul>
<li><a class="reference internal" href="#general-configuration">General configuration</a></li>
<li><a class="reference internal" href="#project-information">Project information</a></li>
<li><a class="reference internal" href="#options-for-html-output">Options for HTML output</a></li>
<li><a class="reference internal" href="#options-for-epub-output">Options for epub output</a></li>
<li><a class="reference internal" href="#options-for-latex-output">Options for LaTeX output</a></li>
<li><a class="reference internal" href="#options-for-manual-page-output">Options for manual page output</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="builders.html"
title="previous chapter">Available builders</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="theming.html"
title="next chapter">HTML theming support</a></p>
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="_sources/config.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-conf">
<span id="the-build-configuration-file"></span><span id="build-config"></span><h1>The build configuration file<a class="headerlink" href="#module-conf" title="Permalink to this headline">¶</a></h1>
<p>The <a class="reference internal" href="glossary.html#term-configuration-directory"><em class="xref std std-term">configuration directory</em></a> must contain a file named <tt class="file docutils literal"><span class="pre">conf.py</span></tt>.
This file (containing Python code) is called the “build configuration file” and
contains all configuration needed to customize Sphinx input and output behavior.</p>
<p>The configuration file is executed as Python code at build time (using
<tt class="xref py py-func docutils literal"><span class="pre">execfile()</span></tt>, and with the current directory set to its containing
directory), and therefore can execute arbitrarily complex code. Sphinx then
reads simple names from the file’s namespace as its configuration.</p>
<p>Important points to note:</p>
<ul class="simple">
<li>If not otherwise documented, values must be strings, and their default is the
empty string.</li>
<li>The term “fully-qualified name” refers to a string that names an importable
Python object inside a module; for example, the FQN
<tt class="docutils literal"><span class="pre">"sphinx.builders.Builder"</span></tt> means the <tt class="docutils literal"><span class="pre">Builder</span></tt> class in the
<tt class="docutils literal"><span class="pre">sphinx.builders</span></tt> module.</li>
<li>Remember that document names use <tt class="docutils literal"><span class="pre">/</span></tt> as the path separator and don’t contain
the file name extension.</li>
<li>Since <tt class="file docutils literal"><span class="pre">conf.py</span></tt> is read as a Python file, the usual rules apply for
encodings and Unicode support: declare the encoding using an encoding cookie
(a comment like <tt class="docutils literal"><span class="pre">#</span> <span class="pre">-*-</span> <span class="pre">coding:</span> <span class="pre">utf-8</span> <span class="pre">-*-</span></tt>) and use Unicode string literals
when you include non-ASCII characters in configuration values.</li>
<li>The contents of the config namespace are pickled (so that Sphinx can find out
when configuration changes), so it may not contain unpickleable values –
delete them from the namespace with <tt class="docutils literal"><span class="pre">del</span></tt> if appropriate. Modules are
removed automatically, so you don’t need to <tt class="docutils literal"><span class="pre">del</span></tt> your imports after use.</li>
<li>There is a special object named <tt class="docutils literal"><span class="pre">tags</span></tt> available in the config file.
It can be used to query and change the tags (see <a class="reference internal" href="markup/misc.html#tags"><em>Including content based on tags</em></a>). Use
<tt class="docutils literal"><span class="pre">tags.has('tag')</span></tt> to query, <tt class="docutils literal"><span class="pre">tags.add('tag')</span></tt> and <tt class="docutils literal"><span class="pre">tags.remove('tag')</span></tt>
to change.</li>
</ul>
<div class="section" id="general-configuration">
<h2>General configuration<a class="headerlink" href="#general-configuration" title="Permalink to this headline">¶</a></h2>
<dl class="confval">
<dt id="confval-extensions">
<tt class="descname">extensions</tt><a class="headerlink" href="#confval-extensions" title="Permalink to this definition">¶</a></dt>
<dd><p>A list of strings that are module names of Sphinx extensions. These can be
extensions coming with Sphinx (named <tt class="docutils literal"><span class="pre">sphinx.ext.*</span></tt>) or custom ones.</p>
<p>Note that you can extend <tt class="xref py py-data docutils literal"><span class="pre">sys.path</span></tt> within the conf file if your
extensions live in another directory – but make sure you use absolute paths.
If your extension path is relative to the <a class="reference internal" href="glossary.html#term-configuration-directory"><em class="xref std std-term">configuration directory</em></a>,
use <tt class="xref py py-func docutils literal"><span class="pre">os.path.abspath()</span></tt> like so:</p>
<div class="highlight-python"><pre>import sys, os
sys.path.append(os.path.abspath('sphinxext'))
extensions = ['extname']</pre>
</div>
<p>That way, you can load an extension called <tt class="docutils literal"><span class="pre">extname</span></tt> from the subdirectory
<tt class="docutils literal"><span class="pre">sphinxext</span></tt>.</p>
<p>The configuration file itself can be an extension; for that, you only need to
provide a <tt class="xref py py-func docutils literal"><span class="pre">setup()</span></tt> function in it.</p>
</dd></dl>
<dl class="confval">
<dt id="confval-source_suffix">
<tt class="descname">source_suffix</tt><a class="headerlink" href="#confval-source_suffix" title="Permalink to this definition">¶</a></dt>
<dd><p>The file name extension of source files. Only files with this suffix will be
read as sources. Default is <tt class="docutils literal"><span class="pre">'.rst'</span></tt>.</p>
</dd></dl>
<dl class="confval">
<dt id="confval-source_encoding">
<tt class="descname">source_encoding</tt><a class="headerlink" href="#confval-source_encoding" title="Permalink to this definition">¶</a></dt>
<dd><p>The encoding of all reST source files. The recommended encoding, and the
default value, is <tt class="docutils literal"><span class="pre">'utf-8-sig'</span></tt>.</p>
<p class="versionadded">
<span class="versionmodified">New in version 0.5: </span>Previously, Sphinx accepted only UTF-8 encoded sources.</p>
</dd></dl>
<dl class="confval">
<dt id="confval-master_doc">
<tt class="descname">master_doc</tt><a class="headerlink" href="#confval-master_doc" title="Permalink to this definition">¶</a></dt>
<dd><p>The document name of the “master” document, that is, the document that
contains the root <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> directive. Default is <tt class="docutils literal"><span class="pre">'contents'</span></tt>.</p>
</dd></dl>
<dl class="confval">
<dt id="confval-exclude_patterns">
<tt class="descname">exclude_patterns</tt><a class="headerlink" href="#confval-exclude_patterns" title="Permalink to this definition">¶</a></dt>
<dd><p>A list of glob-style patterns that should be excluded when looking for source
files. <a class="footnote-reference" href="#id3" id="id1">[1]</a> They are matched against the source file names relative to the
source directory, using slashes as directory separators on all platforms.</p>
<p>Example patterns:</p>
<ul class="simple">
<li><tt class="docutils literal"><span class="pre">'library/xml.rst'</span></tt> – ignores the <tt class="docutils literal"><span class="pre">library/xml.rst</span></tt> file (replaces
entry in <a class="reference internal" href="#confval-unused_docs"><tt class="xref std std-confval docutils literal"><span class="pre">unused_docs</span></tt></a>)</li>
<li><tt class="docutils literal"><span class="pre">'library/xml'</span></tt> – ignores the <tt class="docutils literal"><span class="pre">library/xml</span></tt> directory (replaces entry
in <a class="reference internal" href="#confval-exclude_trees"><tt class="xref std std-confval docutils literal"><span class="pre">exclude_trees</span></tt></a>)</li>
<li><tt class="docutils literal"><span class="pre">'library/xml*'</span></tt> – ignores all files and directories starting with
<tt class="docutils literal"><span class="pre">library/xml</span></tt></li>
<li><tt class="docutils literal"><span class="pre">'**/.svn'</span></tt> – ignores all <tt class="docutils literal"><span class="pre">.svn</span></tt> directories (replaces entry in
<a class="reference internal" href="#confval-exclude_dirnames"><tt class="xref std std-confval docutils literal"><span class="pre">exclude_dirnames</span></tt></a>)</li>
</ul>
<p><a class="reference internal" href="#confval-exclude_patterns"><tt class="xref std std-confval docutils literal"><span class="pre">exclude_patterns</span></tt></a> is also consulted when looking for static files
in <a class="reference internal" href="#confval-html_static_path"><tt class="xref std std-confval docutils literal"><span class="pre">html_static_path</span></tt></a>.</p>
<p class="versionadded">
<span class="versionmodified">New in version 1.0.</span></p>
</dd></dl>
<dl class="confval">
<dt id="confval-unused_docs">
<tt class="descname">unused_docs</tt><a class="headerlink" href="#confval-unused_docs" title="Permalink to this definition">¶</a></dt>
<dd><p>A list of document names that are present, but not currently included in the
toctree. Use this setting to suppress the warning that is normally emitted
in that case.</p>
<p class="deprecated">
<span class="versionmodified">Deprecated since version 1.0: </span>Use <a class="reference internal" href="#confval-exclude_patterns"><tt class="xref std std-confval docutils literal"><span class="pre">exclude_patterns</span></tt></a> instead.</p>
</dd></dl>
<dl class="confval">
<dt id="confval-exclude_trees">
<tt class="descname">exclude_trees</tt><a class="headerlink" href="#confval-exclude_trees" title="Permalink to this definition">¶</a></dt>
<dd><p>A list of directory paths, relative to the source directory, that are to be
recursively excluded from the search for source files, that is, their
subdirectories won’t be searched too. The default is <tt class="docutils literal"><span class="pre">[]</span></tt>.</p>
<p class="versionadded">
<span class="versionmodified">New in version 0.4.</span></p>
<p class="deprecated">
<span class="versionmodified">Deprecated since version 1.0: </span>Use <a class="reference internal" href="#confval-exclude_patterns"><tt class="xref std std-confval docutils literal"><span class="pre">exclude_patterns</span></tt></a> instead.</p>
</dd></dl>
<dl class="confval">
<dt id="confval-exclude_dirnames">
<tt class="descname">exclude_dirnames</tt><a class="headerlink" href="#confval-exclude_dirnames" title="Permalink to this definition">¶</a></dt>
<dd><p>A list of directory names that are to be excluded from any recursive
operation Sphinx performs (e.g. searching for source files or copying static
files). This is useful, for example, to exclude version-control-specific
directories like <tt class="docutils literal"><span class="pre">'CVS'</span></tt>. The default is <tt class="docutils literal"><span class="pre">[]</span></tt>.</p>
<p class="versionadded">
<span class="versionmodified">New in version 0.5.</span></p>
<p class="deprecated">
<span class="versionmodified">Deprecated since version 1.0: </span>Use <a class="reference internal" href="#confval-exclude_patterns"><tt class="xref std std-confval docutils literal"><span class="pre">exclude_patterns</span></tt></a> instead.</p>
</dd></dl>
<dl class="confval">
<dt id="confval-locale_dirs">
<tt class="descname">locale_dirs</tt><a class="headerlink" href="#confval-locale_dirs" title="Permalink to this definition">¶</a></dt>
<dd><p class="versionadded">
<span class="versionmodified">New in version 0.5.</span></p>
<p>Directories in which to search for additional Sphinx message catalogs (see
<a class="reference internal" href="#confval-language"><tt class="xref std std-confval docutils literal"><span class="pre">language</span></tt></a>), relative to the source directory. The directories on
this path are searched by the standard <tt class="xref py py-mod docutils literal"><span class="pre">gettext</span></tt> module for a text
domain of <tt class="docutils literal"><span class="pre">sphinx</span></tt>; so if you add the directory <tt class="file docutils literal"><span class="pre">./locale</span></tt> to this
settting, the message catalogs (compiled from <tt class="docutils literal"><span class="pre">.po</span></tt> format using
<strong class="program">msgfmt</strong>) must be in
<tt class="file docutils literal"><span class="pre">./locale/</span><em><span class="pre">language</span></em><span class="pre">/LC_MESSAGES/sphinx.mo</span></tt>.</p>
<p>The default is <tt class="docutils literal"><span class="pre">[]</span></tt>.</p>
</dd></dl>
<dl class="confval">
<dt id="confval-templates_path">
<tt class="descname">templates_path</tt><a class="headerlink" href="#confval-templates_path" title="Permalink to this definition">¶</a></dt>
<dd><p>A list of paths that contain extra templates (or templates that overwrite
builtin/theme-specific templates). Relative paths are taken as relative to
the configuration directory.</p>
</dd></dl>
<dl class="confval">
<dt id="confval-template_bridge">
<tt class="descname">template_bridge</tt><a class="headerlink" href="#confval-template_bridge" title="Permalink to this definition">¶</a></dt>
<dd><p>A string with the fully-qualified name of a callable (or simply a class) that
returns an instance of <a class="reference internal" href="ext/appapi.html#sphinx.application.TemplateBridge" title="sphinx.application.TemplateBridge"><tt class="xref py py-class docutils literal"><span class="pre">TemplateBridge</span></tt></a>. This
instance is then used to render HTML documents, and possibly the output of
other builders (currently the changes builder). (Note that the template
bridge must be made theme-aware if HTML themes are to be used.)</p>
</dd></dl>
<dl class="confval">
<dt id="confval-rst_epilog">
<tt class="descname">rst_epilog</tt><a class="headerlink" href="#confval-rst_epilog" title="Permalink to this definition">¶</a></dt>
<dd><p id="index-0">A string of reStructuredText that will be included at the end of every source
file that is read. This is the right place to add substitutions that should
be available in every file. An example:</p>
<div class="highlight-python"><pre>rst_epilog = """
.. |psf| replace:: Python Software Foundation
"""</pre>
</div>
<p class="versionadded">
<span class="versionmodified">New in version 0.6.</span></p>
</dd></dl>
<dl class="confval">
<dt id="confval-rst_prolog">
<tt class="descname">rst_prolog</tt><a class="headerlink" href="#confval-rst_prolog" title="Permalink to this definition">¶</a></dt>
<dd><p>A string of reStructuredText that will be included at the beginning of every
source file that is read.</p>
<p class="versionadded">
<span class="versionmodified">New in version 1.0.</span></p>
</dd></dl>
<dl class="confval">
<dt id="confval-primary_domain">
<tt class="descname">primary_domain</tt><a class="headerlink" href="#confval-primary_domain" title="Permalink to this definition">¶</a></dt>
<dd><p id="index-1">The name of the default <a class="reference internal" href="domains.html#domains"><em>domain</em></a>. Can also be <tt class="xref docutils literal"><span class="pre">None</span></tt> to
disable a default domain. The default is <tt class="docutils literal"><span class="pre">'py'</span></tt>. Those objects in other
domains (whether the domain name is given explicitly, or selected by a
<a class="reference internal" href="domains.html#directive-default-domain" title="default-domain directive"><tt class="xref rst rst-dir docutils literal"><span class="pre">default-domain</span></tt></a> directive) will have the domain name explicitly
prepended when named (e.g., when the default domain is C, Python functions
will be named “Python function”, not just “function”).</p>
<p class="versionadded">
<span class="versionmodified">New in version 1.0.</span></p>
</dd></dl>
<dl class="confval">
<dt id="confval-default_role">
<tt class="descname">default_role</tt><a class="headerlink" href="#confval-default_role" title="Permalink to this definition">¶</a></dt>
<dd><p id="index-2">The name of a reST role (builtin or Sphinx extension) to use as the default
role, that is, for text marked up <tt class="docutils literal"><span class="pre">`like</span> <span class="pre">this`</span></tt>. This can be set to
<tt class="docutils literal"><span class="pre">'py:obj'</span></tt> to make <tt class="docutils literal"><span class="pre">`filter`</span></tt> a cross-reference to the Python function
“filter”. The default is <tt class="xref docutils literal"><span class="pre">None</span></tt>, which doesn’t reassign the default role.</p>
<p>The default role can always be set within individual documents using the
standard reST <tt class="xref rst rst-dir docutils literal"><span class="pre">default-role</span></tt> directive.</p>
<p class="versionadded">
<span class="versionmodified">New in version 0.4.</span></p>
</dd></dl>
<dl class="confval">
<dt id="confval-keep_warnings">
<tt class="descname">keep_warnings</tt><a class="headerlink" href="#confval-keep_warnings" title="Permalink to this definition">¶</a></dt>
<dd><p>If true, keep warnings as “system message” paragraphs in the built documents.
Regardless of this setting, warnings are always written to the standard error
stream when <tt class="docutils literal"><span class="pre">sphinx-build</span></tt> is run.</p>
<p>The default is <tt class="xref docutils literal"><span class="pre">False</span></tt>, the pre-0.5 behavior was to always keep them.</p>
<p class="versionadded">
<span class="versionmodified">New in version 0.5.</span></p>
</dd></dl>
<dl class="confval">
<dt id="confval-needs_sphinx">
<tt class="descname">needs_sphinx</tt><a class="headerlink" href="#confval-needs_sphinx" title="Permalink to this definition">¶</a></dt>
<dd><p>If set to a <tt class="docutils literal"><span class="pre">major.minor</span></tt> version string like <tt class="docutils literal"><span class="pre">'1.1'</span></tt>, Sphinx will
compare it with its version and refuse to build if it is too old. Default is
no requirement.</p>
<p class="versionadded">
<span class="versionmodified">New in version 1.0.</span></p>
</dd></dl>
<dl class="confval">
<dt id="confval-nitpicky">
<tt class="descname">nitpicky</tt><a class="headerlink" href="#confval-nitpicky" title="Permalink to this definition">¶</a></dt>
<dd><p>If true, Sphinx will warn about <em>all</em> references where the target cannot be
found. Default is <tt class="xref docutils literal"><span class="pre">False</span></tt>. You can activate this mode temporarily using
the <a class="reference internal" href="invocation.html#cmdoption-n"><em class="xref std std-option">-n</em></a> command-line switch.</p>
<p class="versionadded">
<span class="versionmodified">New in version 1.0.</span></p>
</dd></dl>
</div>
<div class="section" id="project-information">
<h2>Project information<a class="headerlink" href="#project-information" title="Permalink to this headline">¶</a></h2>
<dl class="confval">
<dt id="confval-project">
<tt class="descname">project</tt><a class="headerlink" href="#confval-project" title="Permalink to this definition">¶</a></dt>
<dd><p>The documented project’s name.</p>
</dd></dl>
<dl class="confval">
<dt id="confval-copyright">
<tt class="descname">copyright</tt><a class="headerlink" href="#confval-copyright" title="Permalink to this definition">¶</a></dt>
<dd><p>A copyright statement in the style <tt class="docutils literal"><span class="pre">'2008,</span> <span class="pre">Author</span> <span class="pre">Name'</span></tt>.</p>
</dd></dl>
<dl class="confval">
<dt id="confval-version">
<tt class="descname">version</tt><a class="headerlink" href="#confval-version" title="Permalink to this definition">¶</a></dt>
<dd><p>The major project version, used as the replacement for <tt class="docutils literal"><span class="pre">|version|</span></tt>. For
example, for the Python documentation, this may be something like <tt class="docutils literal"><span class="pre">2.6</span></tt>.</p>
</dd></dl>
<dl class="confval">
<dt id="confval-release">
<tt class="descname">release</tt><a class="headerlink" href="#confval-release" title="Permalink to this definition">¶</a></dt>
<dd><p>The full project version, used as the replacement for <tt class="docutils literal"><span class="pre">|release|</span></tt> and
e.g. in the HTML templates. For example, for the Python documentation, this
may be something like <tt class="docutils literal"><span class="pre">2.6.0rc1</span></tt>.</p>
<p>If you don’t need the separation provided between <a class="reference internal" href="#confval-version"><tt class="xref std std-confval docutils literal"><span class="pre">version</span></tt></a> and
<a class="reference internal" href="#confval-release"><tt class="xref std std-confval docutils literal"><span class="pre">release</span></tt></a>, just set them both to the same value.</p>
</dd></dl>
<dl class="confval">
<dt id="confval-language">
<tt class="descname">language</tt><a class="headerlink" href="#confval-language" title="Permalink to this definition">¶</a></dt>
<dd><p>The code for the language the docs are written in. Any text automatically
generated by Sphinx will be in that language. Also, in the LaTeX builder, a
suitable language will be selected as an option for the <em>Babel</em> package.
Default is <tt class="xref docutils literal"><span class="pre">None</span></tt>, which means that no translation will be done.</p>
<p class="versionadded">
<span class="versionmodified">New in version 0.5.</span></p>
<p>Currently supported languages are:</p>
<ul class="simple">
<li><tt class="docutils literal"><span class="pre">bn</span></tt> – Bengali</li>
<li><tt class="docutils literal"><span class="pre">ca</span></tt> – Catalan</li>
<li><tt class="docutils literal"><span class="pre">cs</span></tt> – Czech</li>
<li><tt class="docutils literal"><span class="pre">da</span></tt> – Danish</li>
<li><tt class="docutils literal"><span class="pre">de</span></tt> – German</li>
<li><tt class="docutils literal"><span class="pre">en</span></tt> – English</li>
<li><tt class="docutils literal"><span class="pre">es</span></tt> – Spanish</li>
<li><tt class="docutils literal"><span class="pre">fi</span></tt> – Finnish</li>
<li><tt class="docutils literal"><span class="pre">fr</span></tt> – French</li>
<li><tt class="docutils literal"><span class="pre">hr</span></tt> – Croatian</li>
<li><tt class="docutils literal"><span class="pre">it</span></tt> – Italian</li>
<li><tt class="docutils literal"><span class="pre">ja</span></tt> – Japanese</li>
<li><tt class="docutils literal"><span class="pre">lt</span></tt> – Lithuanian</li>
<li><tt class="docutils literal"><span class="pre">nl</span></tt> – Dutch</li>
<li><tt class="docutils literal"><span class="pre">pl</span></tt> – Polish</li>
<li><tt class="docutils literal"><span class="pre">pt_BR</span></tt> – Brazilian Portuguese</li>
<li><tt class="docutils literal"><span class="pre">ru</span></tt> – Russian</li>
<li><tt class="docutils literal"><span class="pre">sl</span></tt> – Slovenian</li>
<li><tt class="docutils literal"><span class="pre">tr</span></tt> – Turkish</li>
<li><tt class="docutils literal"><span class="pre">uk_UA</span></tt> – Ukrainian</li>
<li><tt class="docutils literal"><span class="pre">zh_CN</span></tt> – Simplified Chinese</li>
<li><tt class="docutils literal"><span class="pre">zh_TW</span></tt> – Traditional Chinese</li>
</ul>
</dd></dl>
<dl class="confval">
<dt id="confval-today">
<tt class="descname">today</tt><a class="headerlink" href="#confval-today" title="Permalink to this definition">¶</a></dt>
<dt id="confval-today_fmt">
<tt class="descname">today_fmt</tt><a class="headerlink" href="#confval-today_fmt" title="Permalink to this definition">¶</a></dt>
<dd><p>These values determine how to format the current date, used as the
replacement for <tt class="docutils literal"><span class="pre">|today|</span></tt>.</p>
<ul class="simple">
<li>If you set <a class="reference internal" href="#confval-today"><tt class="xref std std-confval docutils literal"><span class="pre">today</span></tt></a> to a non-empty value, it is used.</li>
<li>Otherwise, the current time is formatted using <tt class="xref py py-func docutils literal"><span class="pre">time.strftime()</span></tt> and
the format given in <a class="reference internal" href="#confval-today_fmt"><tt class="xref std std-confval docutils literal"><span class="pre">today_fmt</span></tt></a>.</li>
</ul>
<p>The default is no <a class="reference internal" href="#confval-today"><tt class="xref std std-confval docutils literal"><span class="pre">today</span></tt></a> and a <a class="reference internal" href="#confval-today_fmt"><tt class="xref std std-confval docutils literal"><span class="pre">today_fmt</span></tt></a> of <tt class="docutils literal"><span class="pre">'%B</span> <span class="pre">%d,</span>
<span class="pre">%Y'</span></tt> (or, if translation is enabled with <a class="reference internal" href="#confval-language"><tt class="xref std std-confval docutils literal"><span class="pre">language</span></tt></a>, am equivalent
%format for the selected locale).</p>
</dd></dl>
<dl class="confval">
<dt id="confval-highlight_language">
<tt class="descname">highlight_language</tt><a class="headerlink" href="#confval-highlight_language" title="Permalink to this definition">¶</a></dt>
<dd><p>The default language to highlight source code in. The default is
<tt class="docutils literal"><span class="pre">'python'</span></tt>. The value should be a valid Pygments lexer name, see
<a class="reference internal" href="markup/code.html#code-examples"><em>Showing code examples</em></a> for more details.</p>
<p class="versionadded">
<span class="versionmodified">New in version 0.5.</span></p>
</dd></dl>
<dl class="confval">
<dt id="confval-pygments_style">
<tt class="descname">pygments_style</tt><a class="headerlink" href="#confval-pygments_style" title="Permalink to this definition">¶</a></dt>
<dd><p>The style name to use for Pygments highlighting of source code. The default
style is selected by the theme for HTML output, and <tt class="docutils literal"><span class="pre">'sphinx'</span></tt> otherwise.</p>
<p class="versionchanged">
<span class="versionmodified">Changed in version 0.3: </span>If the value is a fully-qualified name of a custom Pygments style class,
this is then used as custom style.</p>
</dd></dl>
<dl class="confval">
<dt id="confval-add_function_parentheses">
<tt class="descname">add_function_parentheses</tt><a class="headerlink" href="#confval-add_function_parentheses" title="Permalink to this definition">¶</a></dt>
<dd><p>A boolean that decides whether parentheses are appended to function and
method role text (e.g. the content of <tt class="docutils literal"><span class="pre">:func:`input`</span></tt>) to signify that the
name is callable. Default is <tt class="xref docutils literal"><span class="pre">True</span></tt>.</p>
</dd></dl>
<dl class="confval">
<dt id="confval-add_module_names">
<tt class="descname">add_module_names</tt><a class="headerlink" href="#confval-add_module_names" title="Permalink to this definition">¶</a></dt>
<dd><p>A boolean that decides whether module names are prepended to all
<a class="reference internal" href="glossary.html#term-object"><em class="xref std std-term">object</em></a> names (for object types where a “module” of some kind is
defined), e.g. for <a class="reference internal" href="domains.html#directive-py:function" title="py:function directive"><tt class="xref rst rst-dir docutils literal"><span class="pre">py:function</span></tt></a> directives. Default is <tt class="xref docutils literal"><span class="pre">True</span></tt>.</p>
</dd></dl>
<dl class="confval">
<dt id="confval-show_authors">
<tt class="descname">show_authors</tt><a class="headerlink" href="#confval-show_authors" title="Permalink to this definition">¶</a></dt>
<dd><p>A boolean that decides whether <a class="reference internal" href="markup/misc.html#directive-codeauthor" title="codeauthor directive"><tt class="xref rst rst-dir docutils literal"><span class="pre">codeauthor</span></tt></a> and
<a class="reference internal" href="markup/misc.html#directive-sectionauthor" title="sectionauthor directive"><tt class="xref rst rst-dir docutils literal"><span class="pre">sectionauthor</span></tt></a> directives produce any output in the built files.</p>
</dd></dl>
<dl class="confval">
<dt id="confval-modindex_common_prefix">
<tt class="descname">modindex_common_prefix</tt><a class="headerlink" href="#confval-modindex_common_prefix" title="Permalink to this definition">¶</a></dt>
<dd><p>A list of prefixes that are ignored for sorting the Python module index
(e.g., if this is set to <tt class="docutils literal"><span class="pre">['foo.']</span></tt>, then <tt class="docutils literal"><span class="pre">foo.bar</span></tt> is shown under <tt class="docutils literal"><span class="pre">B</span></tt>,
not <tt class="docutils literal"><span class="pre">F</span></tt>). This can be handy if you document a project that consists of a
single package. Works only for the HTML builder currently. Default is
<tt class="docutils literal"><span class="pre">[]</span></tt>.</p>
<p class="versionadded">
<span class="versionmodified">New in version 0.6.</span></p>
</dd></dl>
<dl class="confval">
<dt id="confval-trim_footnote_reference_space">
<tt class="descname">trim_footnote_reference_space</tt><a class="headerlink" href="#confval-trim_footnote_reference_space" title="Permalink to this definition">¶</a></dt>
<dd><p>Trim spaces before footnote references that are necessary for the reST parser
to recognize the footnote, but do not look too nice in the output.</p>
<p class="versionadded">
<span class="versionmodified">New in version 0.6.</span></p>
</dd></dl>
<dl class="confval">
<dt id="confval-trim_doctest_flags">
<tt class="descname">trim_doctest_flags</tt><a class="headerlink" href="#confval-trim_doctest_flags" title="Permalink to this definition">¶</a></dt>
<dd><p>If true, doctest flags (comments looking like <tt class="docutils literal"><span class="pre">#</span> <span class="pre">doctest:</span> <span class="pre">FLAG,</span> <span class="pre">...</span></tt>) at
the ends of lines are removed for all code blocks showing interactive Python
sessions (i.e. doctests). Default is true. See the extension
<a class="reference internal" href="ext/doctest.html#module-sphinx.ext.doctest" title="sphinx.ext.doctest: Test snippets in the documentation."><tt class="xref py py-mod docutils literal"><span class="pre">doctest</span></tt></a> for more possibilities of including doctests.</p>
<p class="versionadded">
<span class="versionmodified">New in version 1.0.</span></p>
</dd></dl>
</div>
<div class="section" id="options-for-html-output">
<span id="html-options"></span><h2>Options for HTML output<a class="headerlink" href="#options-for-html-output" title="Permalink to this headline">¶</a></h2>
<p>These options influence HTML as well as HTML Help output, and other builders
that use Sphinx’ HTMLWriter class.</p>
<dl class="confval">
<dt id="confval-html_theme">
<tt class="descname">html_theme</tt><a class="headerlink" href="#confval-html_theme" title="Permalink to this definition">¶</a></dt>
<dd><p>The “theme” that the HTML output should use. See the <a class="reference internal" href="theming.html"><em>section about
theming</em></a>. The default is <tt class="docutils literal"><span class="pre">'default'</span></tt>.</p>
<p class="versionadded">
<span class="versionmodified">New in version 0.6.</span></p>
</dd></dl>
<dl class="confval">
<dt id="confval-html_theme_options">
<tt class="descname">html_theme_options</tt><a class="headerlink" href="#confval-html_theme_options" title="Permalink to this definition">¶</a></dt>
<dd><p>A dictionary of options that influence the look and feel of the selected
theme. These are theme-specific. For the options understood by the builtin
themes, see <a class="reference internal" href="theming.html#builtin-themes"><em>this section</em></a>.</p>
<p class="versionadded">
<span class="versionmodified">New in version 0.6.</span></p>
</dd></dl>
<dl class="confval">
<dt id="confval-html_theme_path">
<tt class="descname">html_theme_path</tt><a class="headerlink" href="#confval-html_theme_path" title="Permalink to this definition">¶</a></dt>
<dd><p>A list of paths that contain custom themes, either as subdirectories or as
zip files. Relative paths are taken as relative to the configuration
directory.</p>
<p class="versionadded">
<span class="versionmodified">New in version 0.6.</span></p>
</dd></dl>
<dl class="confval">
<dt id="confval-html_style">
<tt class="descname">html_style</tt><a class="headerlink" href="#confval-html_style" title="Permalink to this definition">¶</a></dt>
<dd><p>The style sheet to use for HTML pages. A file of that name must exist either
in Sphinx’ <tt class="file docutils literal"><span class="pre">static/</span></tt> path, or in one of the custom paths given in
<a class="reference internal" href="#confval-html_static_path"><tt class="xref std std-confval docutils literal"><span class="pre">html_static_path</span></tt></a>. Default is the stylesheet given by the selected
theme. If you only want to add or override a few things compared to the
theme’s stylesheet, use CSS <tt class="docutils literal"><span class="pre">@import</span></tt> to import the theme’s stylesheet.</p>
</dd></dl>
<dl class="confval">
<dt id="confval-html_title">
<tt class="descname">html_title</tt><a class="headerlink" href="#confval-html_title" title="Permalink to this definition">¶</a></dt>
<dd><p>The “title” for HTML documentation generated with Sphinx’ own templates.
This is appended to the <tt class="docutils literal"><span class="pre"><title></span></tt> tag of individual pages, and used in the
navigation bar as the “topmost” element. It defaults to <tt class="samp docutils literal"><span class="pre">'</span><em><span class="pre"><project></span></em>
<span class="pre">v</span><em><span class="pre"><revision></span></em> <span class="pre">documentation'</span></tt>, where the placeholders are replaced by the
config values of the same name.</p>
</dd></dl>
<dl class="confval">
<dt id="confval-html_short_title">
<tt class="descname">html_short_title</tt><a class="headerlink" href="#confval-html_short_title" title="Permalink to this definition">¶</a></dt>
<dd><p>A shorter “title” for the HTML docs. This is used in for links in the header
and in the HTML Help docs. If not given, it defaults to the value of
<a class="reference internal" href="#confval-html_title"><tt class="xref std std-confval docutils literal"><span class="pre">html_title</span></tt></a>.</p>
<p class="versionadded">
<span class="versionmodified">New in version 0.4.</span></p>
</dd></dl>
<dl class="confval">
<dt id="confval-html_context">
<tt class="descname">html_context</tt><a class="headerlink" href="#confval-html_context" title="Permalink to this definition">¶</a></dt>
<dd><p>A dictionary of values to pass into the template engine’s context for all
pages. Single values can also be put in this dictionary using the
<a class="reference internal" href="invocation.html#cmdoption-A"><em class="xref std std-option">-A</em></a> command-line option of <tt class="docutils literal"><span class="pre">sphinx-build</span></tt>.</p>
<p class="versionadded">
<span class="versionmodified">New in version 0.5.</span></p>
</dd></dl>
<dl class="confval">
<dt id="confval-html_logo">
<tt class="descname">html_logo</tt><a class="headerlink" href="#confval-html_logo" title="Permalink to this definition">¶</a></dt>
<dd><p>If given, this must be the name of an image file that is the logo of the
docs. It is placed at the top of the sidebar; its width should therefore not
exceed 200 pixels. Default: <tt class="xref docutils literal"><span class="pre">None</span></tt>.</p>
<p class="versionadded">
<span class="versionmodified">New in version 0.4.1: </span>The image file will be copied to the <tt class="docutils literal"><span class="pre">_static</span></tt> directory of the output
HTML, so an already existing file with that name will be overwritten.</p>
</dd></dl>
<dl class="confval">
<dt id="confval-html_favicon">
<tt class="descname">html_favicon</tt><a class="headerlink" href="#confval-html_favicon" title="Permalink to this definition">¶</a></dt>
<dd><p>If given, this must be the name of an image file (within the static path, see
below) that is the favicon of the docs. Modern browsers use this as icon for
tabs, windows and bookmarks. It should be a Windows-style icon file
(<tt class="docutils literal"><span class="pre">.ico</span></tt>), which is 16x16 or 32x32 pixels large. Default: <tt class="xref docutils literal"><span class="pre">None</span></tt>.</p>
<p class="versionadded">
<span class="versionmodified">New in version 0.4.</span></p>
</dd></dl>
<dl class="confval">
<dt id="confval-html_static_path">
<tt class="descname">html_static_path</tt><a class="headerlink" href="#confval-html_static_path" title="Permalink to this definition">¶</a></dt>
<dd><p>A list of paths that contain custom static files (such as style sheets or
script files). Relative paths are taken as relative to the configuration
directory. They are copied to the output directory after the theme’s static
files, so a file named <tt class="file docutils literal"><span class="pre">default.css</span></tt> will overwrite the theme’s
<tt class="file docutils literal"><span class="pre">default.css</span></tt>.</p>
<p class="versionchanged">
<span class="versionmodified">Changed in version 0.4: </span>The paths in <a class="reference internal" href="#confval-html_static_path"><tt class="xref std std-confval docutils literal"><span class="pre">html_static_path</span></tt></a> can now contain subdirectories.</p>
<p class="versionchanged">
<span class="versionmodified">Changed in version 1.0: </span>The entries in <a class="reference internal" href="#confval-html_static_path"><tt class="xref std std-confval docutils literal"><span class="pre">html_static_path</span></tt></a> can now be single files.</p>
</dd></dl>
<dl class="confval">
<dt id="confval-html_last_updated_fmt">
<tt class="descname">html_last_updated_fmt</tt><a class="headerlink" href="#confval-html_last_updated_fmt" title="Permalink to this definition">¶</a></dt>
<dd><p>If this is not the empty string, a ‘Last updated on:’ timestamp is inserted
at every page bottom, using the given <tt class="xref py py-func docutils literal"><span class="pre">strftime()</span></tt> format. Default is
<tt class="docutils literal"><span class="pre">'%b</span> <span class="pre">%d,</span> <span class="pre">%Y'</span></tt> (or a locale-dependent equivalent).</p>
</dd></dl>
<dl class="confval">
<dt id="confval-html_use_smartypants">
<tt class="descname">html_use_smartypants</tt><a class="headerlink" href="#confval-html_use_smartypants" title="Permalink to this definition">¶</a></dt>
<dd><p>If true, <em>SmartyPants</em> will be used to convert quotes and dashes to
typographically correct entities. Default: <tt class="xref docutils literal"><span class="pre">True</span></tt>.</p>
</dd></dl>
<dl class="confval">
<dt id="confval-html_add_permalinks">
<tt class="descname">html_add_permalinks</tt><a class="headerlink" href="#confval-html_add_permalinks" title="Permalink to this definition">¶</a></dt>
<dd><p>If true, Sphinx will add “permalinks” for each heading and description
environment as paragraph signs that become visible when the mouse hovers over
them. Default: <tt class="xref docutils literal"><span class="pre">True</span></tt>.</p>
<p class="versionadded">
<span class="versionmodified">New in version 0.6: </span>Previously, this was always activated.</p>
</dd></dl>
<dl class="confval">
<dt id="confval-html_sidebars">
<tt class="descname">html_sidebars</tt><a class="headerlink" href="#confval-html_sidebars" title="Permalink to this definition">¶</a></dt>
<dd><p>Custom sidebar templates, must be a dictionary that maps document names to
template names.</p>
<p>The keys can contain glob-style patterns <a class="footnote-reference" href="#id3" id="id2">[1]</a>, in which case all matching
documents will get the specified sidebars. (A warning is emitted when a
more than one glob-style pattern matches for any document.)</p>
<p>The values can be either lists or single strings.</p>
<ul>
<li><p class="first">If a value is a list, it specifies the complete list of sidebar templates
to include. If all or some of the default sidebars are to be included,
they must be put into this list as well.</p>
<p>The default sidebars (for documents that don’t match any pattern) are:
<tt class="docutils literal"><span class="pre">['localtoc.html',</span> <span class="pre">'relations.html',</span> <span class="pre">'sourcelink.html',</span>
<span class="pre">'searchbox.html']</span></tt>.</p>
</li>
<li><p class="first">If a value is a single string, it specifies a custom sidebar to be added
between the <tt class="docutils literal"><span class="pre">'sourcelink.html'</span></tt> and <tt class="docutils literal"><span class="pre">'searchbox.html'</span></tt> entries. This
is for compatibility with Sphinx versions before 1.0.</p>
</li>
</ul>
<p>Builtin sidebar templates that can be rendered are:</p>
<ul class="simple">
<li><strong>localtoc.html</strong> – a fine-grained table of contents of the current document</li>
<li><strong>globaltoc.html</strong> – a coarse-grained table of contents for the whole
documentation set, collapsed</li>
<li><strong>relations.html</strong> – two links to the previous and next documents</li>
<li><strong>sourcelink.html</strong> – a link to the source of the current document, if
enabled in <a class="reference internal" href="#confval-html_show_sourcelink"><tt class="xref std std-confval docutils literal"><span class="pre">html_show_sourcelink</span></tt></a></li>
<li><strong>searchbox.html</strong> – the “quick search” box</li>
</ul>
<p>Example:</p>
<div class="highlight-python"><pre>html_sidebars = {
'**': ['globaltoc.html', 'sourcelink.html', 'searchbox.html'],
'using/windows': ['windowssidebar.html', 'searchbox.html'],
}</pre>
</div>
<p>This will render the custom template <tt class="docutils literal"><span class="pre">windowssidebar.html</span></tt> and the quick
search box within the sidebar of the given document, and render the default
sidebars for all other pages (except that the local TOC is replaced by the
global TOC).</p>
<p class="versionadded">
<span class="versionmodified">New in version 1.0: </span>The ability to use globbing keys and to specify multiple sidebars.</p>
<p>Note that this value only has no effect if the chosen theme does not possess
a sidebar, like the builtin <strong>scrolls</strong> and <strong>haiku</strong> themes.</p>
</dd></dl>
<dl class="confval">
<dt id="confval-html_additional_pages">
<tt class="descname">html_additional_pages</tt><a class="headerlink" href="#confval-html_additional_pages" title="Permalink to this definition">¶</a></dt>
<dd><p>Additional templates that should be rendered to HTML pages, must be a
dictionary that maps document names to template names.</p>
<p>Example:</p>
<div class="highlight-python"><pre>html_additional_pages = {
'download': 'customdownload.html',
}</pre>
</div>
<p>This will render the template <tt class="docutils literal"><span class="pre">customdownload.html</span></tt> as the page
<tt class="docutils literal"><span class="pre">download.html</span></tt>.</p>
</dd></dl>
<dl class="confval">
<dt id="confval-html_domain_indices">
<tt class="descname">html_domain_indices</tt><a class="headerlink" href="#confval-html_domain_indices" title="Permalink to this definition">¶</a></dt>
<dd><p>If true, generate domain-specific indices in addition to the general index.
For e.g. the Python domain, this is the global module index. Default is
<tt class="xref docutils literal"><span class="pre">True</span></tt>.</p>
<p>This value can be a bool or a list of index names that should be generated.
To find out the index name for a specific index, look at the HTML file name.
For example, the Python module index has the name <tt class="docutils literal"><span class="pre">'py-modindex'</span></tt>.</p>
<p class="versionadded">
<span class="versionmodified">New in version 1.0.</span></p>
</dd></dl>
<dl class="confval">
<dt id="confval-html_use_modindex">
<tt class="descname">html_use_modindex</tt><a class="headerlink" href="#confval-html_use_modindex" title="Permalink to this definition">¶</a></dt>
<dd><p>If true, add a module index to the HTML documents. Default is <tt class="xref docutils literal"><span class="pre">True</span></tt>.</p>
<p class="deprecated">
<span class="versionmodified">Deprecated since version 1.0: </span>Use <a class="reference internal" href="#confval-html_domain_indices"><tt class="xref std std-confval docutils literal"><span class="pre">html_domain_indices</span></tt></a>.</p>
</dd></dl>
<dl class="confval">
<dt id="confval-html_use_index">
<tt class="descname">html_use_index</tt><a class="headerlink" href="#confval-html_use_index" title="Permalink to this definition">¶</a></dt>
<dd><p>If true, add an index to the HTML documents. Default is <tt class="xref docutils literal"><span class="pre">True</span></tt>.</p>
<p class="versionadded">
<span class="versionmodified">New in version 0.4.</span></p>
</dd></dl>
<dl class="confval">
<dt id="confval-html_split_index">
<tt class="descname">html_split_index</tt><a class="headerlink" href="#confval-html_split_index" title="Permalink to this definition">¶</a></dt>
<dd><p>If true, the index is generated twice: once as a single page with all the
entries, and once as one page per starting letter. Default is <tt class="xref docutils literal"><span class="pre">False</span></tt>.</p>
<p class="versionadded">
<span class="versionmodified">New in version 0.4.</span></p>
</dd></dl>
<dl class="confval">
<dt id="confval-html_copy_source">
<tt class="descname">html_copy_source</tt><a class="headerlink" href="#confval-html_copy_source" title="Permalink to this definition">¶</a></dt>
<dd><p>If true, the reST sources are included in the HTML build as
<tt class="file docutils literal"><span class="pre">_sources/</span><em><span class="pre">name</span></em></tt>. The default is <tt class="xref docutils literal"><span class="pre">True</span></tt>.</p>
<div class="admonition warning">
<p class="first admonition-title">Warning</p>
<p class="last">If this config value is set to <tt class="xref docutils literal"><span class="pre">False</span></tt>, the JavaScript search function
will only display the titles of matching documents, and no excerpt from
the matching contents.</p>
</div>
</dd></dl>
<dl class="confval">
<dt id="confval-html_show_sourcelink">
<tt class="descname">html_show_sourcelink</tt><a class="headerlink" href="#confval-html_show_sourcelink" title="Permalink to this definition">¶</a></dt>
<dd><p>If true (and <a class="reference internal" href="#confval-html_copy_source"><tt class="xref std std-confval docutils literal"><span class="pre">html_copy_source</span></tt></a> is true as well), links to the
reST sources will be added to the sidebar. The default is <tt class="xref docutils literal"><span class="pre">True</span></tt>.</p>
<p class="versionadded">
<span class="versionmodified">New in version 0.6.</span></p>
</dd></dl>
<dl class="confval">
<dt id="confval-html_use_opensearch">
<tt class="descname">html_use_opensearch</tt><a class="headerlink" href="#confval-html_use_opensearch" title="Permalink to this definition">¶</a></dt>
<dd><p>If nonempty, an <cite>OpenSearch <http://opensearch.org></cite> description file will be
output, and all pages will contain a <tt class="docutils literal"><span class="pre"><link></span></tt> tag referring to it. Since
OpenSearch doesn’t support relative URLs for its search page location, the
value of this option must be the base URL from which these documents are
served (without trailing slash), e.g. <tt class="docutils literal"><span class="pre">"http://docs.python.org"</span></tt>. The
default is <tt class="docutils literal"><span class="pre">''</span></tt>.</p>
</dd></dl>
<dl class="confval">
<dt id="confval-html_file_suffix">
<tt class="descname">html_file_suffix</tt><a class="headerlink" href="#confval-html_file_suffix" title="Permalink to this definition">¶</a></dt>
<dd><p>This is the file name suffix for generated HTML files. The default is
<tt class="docutils literal"><span class="pre">".html"</span></tt>.</p>
<p class="versionadded">
<span class="versionmodified">New in version 0.4.</span></p>
</dd></dl>
<dl class="confval">
<dt id="confval-html_link_suffix">
<tt class="descname">html_link_suffix</tt><a class="headerlink" href="#confval-html_link_suffix" title="Permalink to this definition">¶</a></dt>
<dd><p>Suffix for generated links to HTML files. The default is whatever
<a class="reference internal" href="#confval-html_file_suffix"><tt class="xref std std-confval docutils literal"><span class="pre">html_file_suffix</span></tt></a> is set to; it can be set differently (e.g. to
support different web server setups).</p>
<p class="versionadded">
<span class="versionmodified">New in version 0.6.</span></p>
</dd></dl>
<dl class="confval">
<dt id="confval-html_translator_class">
<tt class="descname">html_translator_class</tt><a class="headerlink" href="#confval-html_translator_class" title="Permalink to this definition">¶</a></dt>
<dd><p>A string with the fully-qualified name of a HTML Translator class, that is, a
subclass of Sphinx’ <tt class="xref py py-class docutils literal"><span class="pre">HTMLTranslator</span></tt>, that is used
to translate document trees to HTML. Default is <tt class="xref docutils literal"><span class="pre">None</span></tt> (use the builtin
translator).</p>
</dd></dl>
<dl class="confval">
<dt id="confval-html_show_copyright">
<tt class="descname">html_show_copyright</tt><a class="headerlink" href="#confval-html_show_copyright" title="Permalink to this definition">¶</a></dt>
<dd><p>If true, “(C) Copyright ...” is shown in the HTML footer. Default is <tt class="xref docutils literal"><span class="pre">True</span></tt>.</p>
<p class="versionadded">
<span class="versionmodified">New in version 1.0.</span></p>
</dd></dl>
<dl class="confval">
<dt id="confval-html_show_sphinx">
<tt class="descname">html_show_sphinx</tt><a class="headerlink" href="#confval-html_show_sphinx" title="Permalink to this definition">¶</a></dt>
<dd><p>If true, “Created using Sphinx” is shown in the HTML footer. Default is
<tt class="xref docutils literal"><span class="pre">True</span></tt>.</p>
<p class="versionadded">
<span class="versionmodified">New in version 0.4.</span></p>
</dd></dl>
<dl class="confval">
<dt id="confval-html_output_encoding">
<tt class="descname">html_output_encoding</tt><a class="headerlink" href="#confval-html_output_encoding" title="Permalink to this definition">¶</a></dt>
<dd><p>Encoding of HTML output files. Default is <tt class="docutils literal"><span class="pre">'utf-8'</span></tt>. Note that this
encoding name must both be a valid Python encoding name and a valid HTML
<tt class="docutils literal"><span class="pre">charset</span></tt> value.</p>
<p class="versionadded">
<span class="versionmodified">New in version 1.0.</span></p>
</dd></dl>
<dl class="confval">
<dt id="confval-html_compact_lists">
<tt class="descname">html_compact_lists</tt><a class="headerlink" href="#confval-html_compact_lists" title="Permalink to this definition">¶</a></dt>
<dd><p>If true, list items containing only a single paragraph will not be rendered
with a <tt class="docutils literal"><span class="pre"><p></span></tt> element. This is standard docutils behavior. Default:
<tt class="xref docutils literal"><span class="pre">True</span></tt>.</p>
<p class="versionadded">
<span class="versionmodified">New in version 1.0.</span></p>
</dd></dl>
<dl class="confval">
<dt id="confval-html_secnumber_suffix">
<tt class="descname">html_secnumber_suffix</tt><a class="headerlink" href="#confval-html_secnumber_suffix" title="Permalink to this definition">¶</a></dt>
<dd><p>Suffix for section numbers. Default: <tt class="docutils literal"><span class="pre">".</span> <span class="pre">"</span></tt>. Set to <tt class="docutils literal"><span class="pre">"</span> <span class="pre">"</span></tt> to suppress
the final dot on section numbers.</p>
<p class="versionadded">
<span class="versionmodified">New in version 1.0.</span></p>
</dd></dl>
<dl class="confval">
<dt id="confval-htmlhelp_basename">
<tt class="descname">htmlhelp_basename</tt><a class="headerlink" href="#confval-htmlhelp_basename" title="Permalink to this definition">¶</a></dt>
<dd><p>Output file base name for HTML help builder. Default is <tt class="docutils literal"><span class="pre">'pydoc'</span></tt>.</p>
</dd></dl>
</div>
<div class="section" id="options-for-epub-output">
<span id="epub-options"></span><h2>Options for epub output<a class="headerlink" href="#options-for-epub-output" title="Permalink to this headline">¶</a></h2>
<p>These options influence the epub output. As this builder derives from the HTML
builder, the HTML options also apply where appropriate. The actual values for
some of the options is not really important, they just have to be entered into
the <a class="reference external" href="http://dublincore.org/">Dublin Core metadata</a>.</p>
<dl class="confval">
<dt id="confval-epub_basename">
<tt class="descname">epub_basename</tt><a class="headerlink" href="#confval-epub_basename" title="Permalink to this definition">¶</a></dt>
<dd><p>The basename for the epub file. It defaults to the <a class="reference internal" href="#confval-project"><tt class="xref std std-confval docutils literal"><span class="pre">project</span></tt></a> name.</p>
</dd></dl>
<dl class="confval">
<dt id="confval-epub_theme">
<tt class="descname">epub_theme</tt><a class="headerlink" href="#confval-epub_theme" title="Permalink to this definition">¶</a></dt>
<dd><p>The HTML theme for the epub output. Since the default themes are not
optimized for small screen space, using the same theme for HTML and epub
output is usually not wise. This defaults to <tt class="docutils literal"><span class="pre">'epub'</span></tt>, a theme designed to
save visual space.</p>
</dd></dl>
<dl class="confval">
<dt id="confval-epub_title">
<tt class="descname">epub_title</tt><a class="headerlink" href="#confval-epub_title" title="Permalink to this definition">¶</a></dt>
<dd><p>The title of the document. It defaults to the <a class="reference internal" href="#confval-html_title"><tt class="xref std std-confval docutils literal"><span class="pre">html_title</span></tt></a> option
but can be set independently for epub creation.</p>
</dd></dl>
<dl class="confval">
<dt id="confval-epub_author">
<tt class="descname">epub_author</tt><a class="headerlink" href="#confval-epub_author" title="Permalink to this definition">¶</a></dt>
<dd><p>The author of the document. This is put in the Dublin Core metadata. The
default value is <tt class="docutils literal"><span class="pre">'unknown'</span></tt>.</p>
</dd></dl>
<dl class="confval">
<dt id="confval-epub_language">
<tt class="descname">epub_language</tt><a class="headerlink" href="#confval-epub_language" title="Permalink to this definition">¶</a></dt>
<dd><p>The language of the document. This is put in the Dublin Core metadata. The
default is the <a class="reference internal" href="#confval-language"><tt class="xref std std-confval docutils literal"><span class="pre">language</span></tt></a> option or <tt class="docutils literal"><span class="pre">'en'</span></tt> if unset.</p>
</dd></dl>
<dl class="confval">
<dt id="confval-epub_publisher">
<tt class="descname">epub_publisher</tt><a class="headerlink" href="#confval-epub_publisher" title="Permalink to this definition">¶</a></dt>
<dd><p>The publisher of the document. This is put in the Dublin Core metadata. You
may use any sensible string, e.g. the project homepage. The default value is
<tt class="docutils literal"><span class="pre">'unknown'</span></tt>.</p>
</dd></dl>
<dl class="confval">
<dt id="confval-epub_copyright">
<tt class="descname">epub_copyright</tt><a class="headerlink" href="#confval-epub_copyright" title="Permalink to this definition">¶</a></dt>
<dd><p>The copyright of the document. It defaults to the <a class="reference internal" href="#confval-copyright"><tt class="xref std std-confval docutils literal"><span class="pre">copyright</span></tt></a>
option but can be set independently for epub creation.</p>
</dd></dl>
<dl class="confval">
<dt id="confval-epub_identifier">
<tt class="descname">epub_identifier</tt><a class="headerlink" href="#confval-epub_identifier" title="Permalink to this definition">¶</a></dt>
<dd><p>An identifier for the document. This is put in the Dublin Core metadata.
For published documents this is the ISBN number, but you can also use an
alternative scheme, e.g. the project homepage. The default value is
<tt class="docutils literal"><span class="pre">'unknown'</span></tt>.</p>
</dd></dl>
<dl class="confval">
<dt id="confval-epub_scheme">
<tt class="descname">epub_scheme</tt><a class="headerlink" href="#confval-epub_scheme" title="Permalink to this definition">¶</a></dt>
<dd><p>The publication scheme for the <a class="reference internal" href="#confval-epub_identifier"><tt class="xref std std-confval docutils literal"><span class="pre">epub_identifier</span></tt></a>. This is put in
the Dublin Core metadata. For published books the scheme is <tt class="docutils literal"><span class="pre">'ISBN'</span></tt>. If
you use the project homepage, <tt class="docutils literal"><span class="pre">'URL'</span></tt> seems reasonable. The default value
is <tt class="docutils literal"><span class="pre">'unknown'</span></tt>.</p>
</dd></dl>
<dl class="confval">
<dt id="confval-epub_uid">
<tt class="descname">epub_uid</tt><a class="headerlink" href="#confval-epub_uid" title="Permalink to this definition">¶</a></dt>
<dd><p>A unique identifier for the document. This is put in the Dublin Core
metadata. You may use a random string. The default value is <tt class="docutils literal"><span class="pre">'unknown'</span></tt>.</p>
</dd></dl>
<dl class="confval">
<dt id="confval-epub_pre_files">
<tt class="descname">epub_pre_files</tt><a class="headerlink" href="#confval-epub_pre_files" title="Permalink to this definition">¶</a></dt>
<dd><p>Additional files that should be inserted before the text generated by
Sphinx. It is a list of tuples containing the file name and the title.
If the title is empty, no entry is added to <tt class="file docutils literal"><span class="pre">toc.ncx</span></tt>. Example:</p>
<div class="highlight-python"><pre>epub_pre_files = [
('index.html', 'Welcome'),
]</pre>
</div>
<p>The default value is <tt class="docutils literal"><span class="pre">[]</span></tt>.</p>
</dd></dl>
<dl class="confval">
<dt id="confval-epub_post_files">
<tt class="descname">epub_post_files</tt><a class="headerlink" href="#confval-epub_post_files" title="Permalink to this definition">¶</a></dt>
<dd><p>Additional files that should be inserted after the text generated by Sphinx.
It is a list of tuples containing the file name and the title. This option
can be used to add an appendix. If the title is empty, no entry is added
to <tt class="file docutils literal"><span class="pre">toc.ncx</span></tt>. The default value is <tt class="docutils literal"><span class="pre">[]</span></tt>.</p>
</dd></dl>
<dl class="confval">
<dt id="confval-epub_exclude_files">
<tt class="descname">epub_exclude_files</tt><a class="headerlink" href="#confval-epub_exclude_files" title="Permalink to this definition">¶</a></dt>
<dd><p>A list of files that are generated/copied in the build directory but should
not be included in the epub file. The default value is <tt class="docutils literal"><span class="pre">[]</span></tt>.</p>
</dd></dl>
<dl class="confval">
<dt id="confval-epub_tocdepth">
<tt class="descname">epub_tocdepth</tt><a class="headerlink" href="#confval-epub_tocdepth" title="Permalink to this definition">¶</a></dt>
<dd><p>The depth of the table of contents in the file <tt class="file docutils literal"><span class="pre">toc.ncx</span></tt>. It should
be an integer greater than zero. The default value is 3. Note: A deeply
nested table of contents may be difficult to navigate.</p>
</dd></dl>
<dl class="confval">
<dt id="confval-epub_tocdup">
<tt class="descname">epub_tocdup</tt><a class="headerlink" href="#confval-epub_tocdup" title="Permalink to this definition">¶</a></dt>
<dd><p>This flag determines if a toc entry is inserted again at the beginning of
it’s nested toc listing. This allows easier navitation to the top of
a chapter, but can be confusing because it mixes entries of differnet
depth in one list. The default value is <tt class="xref docutils literal"><span class="pre">True</span></tt>.</p>
</dd></dl>
</div>
<div class="section" id="options-for-latex-output">
<span id="latex-options"></span><h2>Options for LaTeX output<a class="headerlink" href="#options-for-latex-output" title="Permalink to this headline">¶</a></h2>
<p>These options influence LaTeX output.</p>
<dl class="confval">
<dt id="confval-latex_documents">
<tt class="descname">latex_documents</tt><a class="headerlink" href="#confval-latex_documents" title="Permalink to this definition">¶</a></dt>
<dd><p>This value determines how to group the document tree into LaTeX source files.
It must be a list of tuples <tt class="docutils literal"><span class="pre">(startdocname,</span> <span class="pre">targetname,</span> <span class="pre">title,</span> <span class="pre">author,</span>
<span class="pre">documentclass,</span> <span class="pre">toctree_only)</span></tt>, where the items are:</p>
<ul class="simple">
<li><em>startdocname</em>: document name that is the “root” of the LaTeX file. All
documents referenced by it in TOC trees will be included in the LaTeX file
too. (If you want only one LaTeX file, use your <a class="reference internal" href="#confval-master_doc"><tt class="xref std std-confval docutils literal"><span class="pre">master_doc</span></tt></a>
here.)</li>
<li><em>targetname</em>: file name of the LaTeX file in the output directory.</li>
<li><em>title</em>: LaTeX document title. Can be empty to use the title of the
<em>startdoc</em>. This is inserted as LaTeX markup, so special characters like a
backslash or ampersand must be represented by the proper LaTeX commands if
they are to be inserted literally.</li>
<li><em>author</em>: Author for the LaTeX document. The same LaTeX markup caveat as
for <em>title</em> applies. Use <tt class="docutils literal"><span class="pre">\and</span></tt> to separate multiple authors, as in:
<tt class="docutils literal"><span class="pre">'John</span> <span class="pre">\and</span> <span class="pre">Sarah'</span></tt>.</li>
<li><em>documentclass</em>: Normally, one of <tt class="docutils literal"><span class="pre">'manual'</span></tt> or <tt class="docutils literal"><span class="pre">'howto'</span></tt> (provided by
Sphinx). Other document classes can be given, but they must include the
“sphinx” package in order to define Sphinx’ custom LaTeX commands.
“howto” documents will not get appendices. Also, howtos will have a simpler
title page.</li>
<li><em>toctree_only</em>: Must be <tt class="xref docutils literal"><span class="pre">True</span></tt> or <tt class="xref docutils literal"><span class="pre">False</span></tt>. If <tt class="xref docutils literal"><span class="pre">True</span></tt>, the <em>startdoc</em>
document itself is not included in the output, only the documents
referenced by it via TOC trees. With this option, you can put extra stuff
in the master document that shows up in the HTML, but not the LaTeX output.</li>
</ul>
<p class="versionadded">
<span class="versionmodified">New in version 0.3: </span>The 6th item <tt class="docutils literal"><span class="pre">toctree_only</span></tt>. Tuples with 5 items are still accepted.</p>
</dd></dl>
<dl class="confval">
<dt id="confval-latex_logo">
<tt class="descname">latex_logo</tt><a class="headerlink" href="#confval-latex_logo" title="Permalink to this definition">¶</a></dt>
<dd><p>If given, this must be the name of an image file (relative to the
configuration directory) that is the logo of the docs. It is placed at the
top of the title page. Default: <tt class="xref docutils literal"><span class="pre">None</span></tt>.</p>
</dd></dl>
<dl class="confval">
<dt id="confval-latex_use_parts">
<tt class="descname">latex_use_parts</tt><a class="headerlink" href="#confval-latex_use_parts" title="Permalink to this definition">¶</a></dt>
<dd><p>If true, the topmost sectioning unit is parts, else it is chapters. Default:
<tt class="xref docutils literal"><span class="pre">False</span></tt>.</p>
<p class="versionadded">
<span class="versionmodified">New in version 0.3.</span></p>
</dd></dl>
<dl class="confval">
<dt id="confval-latex_appendices">
<tt class="descname">latex_appendices</tt><a class="headerlink" href="#confval-latex_appendices" title="Permalink to this definition">¶</a></dt>
<dd><p>A list of document names to append as an appendix to all manuals.</p>
</dd></dl>
<dl class="confval">
<dt id="confval-latex_domain_indices">
<tt class="descname">latex_domain_indices</tt><a class="headerlink" href="#confval-latex_domain_indices" title="Permalink to this definition">¶</a></dt>
<dd><p>If true, generate domain-specific indices in addition to the general index.
For e.g. the Python domain, this is the global module index. Default is
<tt class="xref docutils literal"><span class="pre">True</span></tt>.</p>
<p>This value can be a bool or a list of index names that should be generated,
like for <a class="reference internal" href="#confval-html_domain_indices"><tt class="xref std std-confval docutils literal"><span class="pre">html_domain_indices</span></tt></a>.</p>
<p class="versionadded">
<span class="versionmodified">New in version 1.0.</span></p>
</dd></dl>
<dl class="confval">
<dt id="confval-latex_use_modindex">
<tt class="descname">latex_use_modindex</tt><a class="headerlink" href="#confval-latex_use_modindex" title="Permalink to this definition">¶</a></dt>
<dd><p>If true, add a module index to LaTeX documents. Default is <tt class="xref docutils literal"><span class="pre">True</span></tt>.</p>
<p class="deprecated">
<span class="versionmodified">Deprecated since version 1.0: </span>Use <a class="reference internal" href="#confval-latex_domain_indices"><tt class="xref std std-confval docutils literal"><span class="pre">latex_domain_indices</span></tt></a>.</p>
</dd></dl>
<dl class="confval">
<dt id="confval-latex_show_pagerefs">
<tt class="descname">latex_show_pagerefs</tt><a class="headerlink" href="#confval-latex_show_pagerefs" title="Permalink to this definition">¶</a></dt>
<dd><p>If true, add page references after internal references. This is very useful
for printed copies of the manual. Default is <tt class="xref docutils literal"><span class="pre">False</span></tt>.</p>
<p class="versionadded">
<span class="versionmodified">New in version 1.0.</span></p>
</dd></dl>
<dl class="confval">
<dt id="confval-latex_show_urls">
<tt class="descname">latex_show_urls</tt><a class="headerlink" href="#confval-latex_show_urls" title="Permalink to this definition">¶</a></dt>
<dd><p>If true, add URL addresses after links. This is very useful for printed
copies of the manual. Default is <tt class="xref docutils literal"><span class="pre">False</span></tt>.</p>
<p class="versionadded">
<span class="versionmodified">New in version 1.0.</span></p>
</dd></dl>
<dl class="confval">
<dt id="confval-latex_elements">
<tt class="descname">latex_elements</tt><a class="headerlink" href="#confval-latex_elements" title="Permalink to this definition">¶</a></dt>
<dd><p class="versionadded">
<span class="versionmodified">New in version 0.5.</span></p>
<p>A dictionary that contains LaTeX snippets that override those Sphinx usually
puts into the generated <tt class="docutils literal"><span class="pre">.tex</span></tt> files.</p>
<p>Keep in mind that backslashes must be doubled in Python string literals to
avoid interpretation as escape sequences.</p>
<ul>
<li><p class="first">Keys that you may want to override include:</p>
<dl class="docutils">
<dt><tt class="docutils literal"><span class="pre">'papersize'</span></tt></dt>
<dd><p class="first last">Paper size option of the document class (<tt class="docutils literal"><span class="pre">'a4paper'</span></tt> or
<tt class="docutils literal"><span class="pre">'letterpaper'</span></tt>), default <tt class="docutils literal"><span class="pre">'letterpaper'</span></tt>.</p>
</dd>
<dt><tt class="docutils literal"><span class="pre">'pointsize'</span></tt></dt>
<dd><p class="first last">Point size option of the document class (<tt class="docutils literal"><span class="pre">'10pt'</span></tt>, <tt class="docutils literal"><span class="pre">'11pt'</span></tt> or
<tt class="docutils literal"><span class="pre">'12pt'</span></tt>), default <tt class="docutils literal"><span class="pre">'10pt'</span></tt>.</p>
</dd>
<dt><tt class="docutils literal"><span class="pre">'babel'</span></tt></dt>
<dd><p class="first last">“babel” package inclusion, default <tt class="docutils literal"><span class="pre">'\\usepackage{babel}'</span></tt>.</p>
</dd>
<dt><tt class="docutils literal"><span class="pre">'fontpkg'</span></tt></dt>
<dd><p class="first last">Font package inclusion, default <tt class="docutils literal"><span class="pre">'\\usepackage{times}'</span></tt> (which uses
Times and Helvetica). You can set this to <tt class="docutils literal"><span class="pre">''</span></tt> to use the Computer
Modern fonts.</p>
</dd>
<dt><tt class="docutils literal"><span class="pre">'fncychap'</span></tt></dt>
<dd><p class="first last">Inclusion of the “fncychap” package (which makes fancy chapter titles),
default <tt class="docutils literal"><span class="pre">'\\usepackage[Bjarne]{fncychap}'</span></tt> for English documentation,
<tt class="docutils literal"><span class="pre">'\\usepackage[Sonny]{fncychap}'</span></tt> for internationalized docs (because
the “Bjarne” style uses numbers spelled out in English). Other
“fncychap” styles you can try include “Lenny”, “Glenn”, “Conny” and
“Rejne”. You can also set this to <tt class="docutils literal"><span class="pre">''</span></tt> to disable fncychap.</p>
</dd>
<dt><tt class="docutils literal"><span class="pre">'preamble'</span></tt></dt>
<dd><p class="first last">Additional preamble content, default empty.</p>
</dd>
<dt><tt class="docutils literal"><span class="pre">'footer'`</span></tt></dt>
<dd><p class="first last">Additional footer content (before the indices), default empty.</p>
</dd>
</dl>
</li>
<li><p class="first">Keys that don’t need be overridden unless in special cases are:</p>
<dl class="docutils">
<dt><tt class="docutils literal"><span class="pre">'inputenc'</span></tt></dt>
<dd><p class="first last">“inputenc” package inclusion, default
<tt class="docutils literal"><span class="pre">'\\usepackage[utf8]{inputenc}'</span></tt>.</p>
</dd>
<dt><tt class="docutils literal"><span class="pre">'fontenc'</span></tt></dt>
<dd><p class="first last">“fontenc” package inclusion, default <tt class="docutils literal"><span class="pre">'\\usepackage[T1]{fontenc}'</span></tt>.</p>
</dd>
<dt><tt class="docutils literal"><span class="pre">'maketitle'</span></tt></dt>
<dd><p class="first last">“maketitle” call, default <tt class="docutils literal"><span class="pre">'\\maketitle'</span></tt>. Override if you want to
generate a differently-styled title page.</p>
</dd>
<dt><tt class="docutils literal"><span class="pre">'tableofcontents'</span></tt></dt>
<dd><p class="first last">“tableofcontents” call, default <tt class="docutils literal"><span class="pre">'\\tableofcontents'</span></tt>. Override if
you want to generate a different table of contents or put content
between the title page and the TOC.</p>
</dd>
<dt><tt class="docutils literal"><span class="pre">'printindex'</span></tt></dt>
<dd><p class="first last">“printindex” call, the last thing in the file, default
<tt class="docutils literal"><span class="pre">'\\printindex'</span></tt>. Override if you want to generate the index
differently or append some content after the index.</p>
</dd>
</dl>
</li>
<li><p class="first">Keys that are set by other options and therefore should not be overridden are:</p>
<p><tt class="docutils literal"><span class="pre">'docclass'</span></tt>
<tt class="docutils literal"><span class="pre">'classoptions'</span></tt>
<tt class="docutils literal"><span class="pre">'title'</span></tt>
<tt class="docutils literal"><span class="pre">'date'</span></tt>
<tt class="docutils literal"><span class="pre">'release'</span></tt>
<tt class="docutils literal"><span class="pre">'author'</span></tt>
<tt class="docutils literal"><span class="pre">'logo'</span></tt>
<tt class="docutils literal"><span class="pre">'releasename'</span></tt>
<tt class="docutils literal"><span class="pre">'makeindex'</span></tt>
<tt class="docutils literal"><span class="pre">'shorthandoff'</span></tt></p>
</li>
</ul>
</dd></dl>
<dl class="confval">
<dt id="confval-latex_docclass">
<tt class="descname">latex_docclass</tt><a class="headerlink" href="#confval-latex_docclass" title="Permalink to this definition">¶</a></dt>
<dd><p>A dictionary mapping <tt class="docutils literal"><span class="pre">'howto'</span></tt> and <tt class="docutils literal"><span class="pre">'manual'</span></tt> to names of real document
classes that will be used as the base for the two Sphinx classes. Default
is to use <tt class="docutils literal"><span class="pre">'article'</span></tt> for <tt class="docutils literal"><span class="pre">'howto'</span></tt> and <tt class="docutils literal"><span class="pre">'report'</span></tt> for <tt class="docutils literal"><span class="pre">'manual'</span></tt>.</p>
<p class="versionadded">
<span class="versionmodified">New in version 1.0.</span></p>
</dd></dl>
<dl class="confval">
<dt id="confval-latex_additional_files">
<tt class="descname">latex_additional_files</tt><a class="headerlink" href="#confval-latex_additional_files" title="Permalink to this definition">¶</a></dt>
<dd><p>A list of file names, relative to the configuration directory, to copy to the
build directory when building LaTeX output. This is useful to copy files
that Sphinx doesn’t copy automatically, e.g. if they are referenced in custom
LaTeX added in <tt class="docutils literal"><span class="pre">latex_elements</span></tt>. Image files that are referenced in source
files (e.g. via <tt class="docutils literal"><span class="pre">..</span> <span class="pre">image::</span></tt>) are copied automatically.</p>
<p>You have to make sure yourself that the filenames don’t collide with those of
any automatically copied files.</p>
<p class="versionadded">
<span class="versionmodified">New in version 0.6.</span></p>
</dd></dl>
<dl class="confval">
<dt id="confval-latex_preamble">
<tt class="descname">latex_preamble</tt><a class="headerlink" href="#confval-latex_preamble" title="Permalink to this definition">¶</a></dt>
<dd><p>Additional LaTeX markup for the preamble.</p>
<p class="deprecated">
<span class="versionmodified">Deprecated since version 0.5: </span>Use the <tt class="docutils literal"><span class="pre">'preamble'</span></tt> key in the <a class="reference internal" href="#confval-latex_elements"><tt class="xref std std-confval docutils literal"><span class="pre">latex_elements</span></tt></a> value.</p>
</dd></dl>
<dl class="confval">
<dt id="confval-latex_paper_size">
<tt class="descname">latex_paper_size</tt><a class="headerlink" href="#confval-latex_paper_size" title="Permalink to this definition">¶</a></dt>
<dd><p>The output paper size (<tt class="docutils literal"><span class="pre">'letter'</span></tt> or <tt class="docutils literal"><span class="pre">'a4'</span></tt>). Default is <tt class="docutils literal"><span class="pre">'letter'</span></tt>.</p>
<p class="deprecated">
<span class="versionmodified">Deprecated since version 0.5: </span>Use the <tt class="docutils literal"><span class="pre">'papersize'</span></tt> key in the <a class="reference internal" href="#confval-latex_elements"><tt class="xref std std-confval docutils literal"><span class="pre">latex_elements</span></tt></a> value.</p>
</dd></dl>
<dl class="confval">
<dt id="confval-latex_font_size">
<tt class="descname">latex_font_size</tt><a class="headerlink" href="#confval-latex_font_size" title="Permalink to this definition">¶</a></dt>
<dd><p>The font size (‘10pt’, ‘11pt’ or ‘12pt’). Default is <tt class="docutils literal"><span class="pre">'10pt'</span></tt>.</p>
<p class="deprecated">
<span class="versionmodified">Deprecated since version 0.5: </span>Use the <tt class="docutils literal"><span class="pre">'pointsize'</span></tt> key in the <a class="reference internal" href="#confval-latex_elements"><tt class="xref std std-confval docutils literal"><span class="pre">latex_elements</span></tt></a> value.</p>
</dd></dl>
</div>
<div class="section" id="options-for-manual-page-output">
<span id="man-options"></span><h2>Options for manual page output<a class="headerlink" href="#options-for-manual-page-output" title="Permalink to this headline">¶</a></h2>
<p>These options influence manual page output.</p>
<dl class="confval">
<dt id="confval-man_pages">
<tt class="descname">man_pages</tt><a class="headerlink" href="#confval-man_pages" title="Permalink to this definition">¶</a></dt>
<dd><p>This value determines how to group the document tree into manual pages. It
must be a list of tuples <tt class="docutils literal"><span class="pre">(startdocname,</span> <span class="pre">name,</span> <span class="pre">description,</span> <span class="pre">authors,</span>
<span class="pre">section)</span></tt>, where the items are:</p>
<ul class="simple">
<li><em>startdocname</em>: document name that is the “root” of the manual page. All
documents referenced by it in TOC trees will be included in the manual file
too. (If you want one master manual page, use your <a class="reference internal" href="#confval-master_doc"><tt class="xref std std-confval docutils literal"><span class="pre">master_doc</span></tt></a>
here.)</li>
<li><em>name</em>: name of the manual page. This should be a short string without
spaces or special characters. It is used to determine the file name as
well as the name of the manual page (in the NAME section).</li>
<li><em>description</em>: description of the manual page. This is used in the NAME
section.</li>
<li><em>authors</em>: A list of strings with authors, or a single string. Can be
an empty string or list if you do not want to automatically generate
an AUTHORS section in the manual page.</li>
<li><em>section</em>: The manual page section. Used for the output file name as well
as in the manual page header.</li>
</ul>
<p class="versionadded">
<span class="versionmodified">New in version 1.0.</span></p>
</dd></dl>
<p class="rubric">Footnotes</p>
<table class="docutils footnote" frame="void" id="id3" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label">[1]</td><td><em>(<a class="fn-backref" href="#id1">1</a>, <a class="fn-backref" href="#id2">2</a>)</em> A note on available globbing syntax: you can use the standard shell
constructs <tt class="docutils literal"><span class="pre">*</span></tt>, <tt class="docutils literal"><span class="pre">?</span></tt>, <tt class="docutils literal"><span class="pre">[...]</span></tt> and <tt class="docutils literal"><span class="pre">[!...]</span></tt> with the feature that
these all don’t match slashes. A double star <tt class="docutils literal"><span class="pre">**</span></tt> can be used to match
any sequence of characters <em>including</em> slashes.</td></tr>
</tbody>
</table>
</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="theming.html" title="HTML theming support"
>next</a> |</li>
<li class="right" >
<a href="builders.html" title="Available builders"
>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
>
74
