/usr/share/doc/sphinx-doc/html/config.html

<!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 &#8212; Sphinx 1.6.7 documentation</title>
    <link rel="stylesheet" href="_static/sphinx13.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.6.7',
        COLLAPSE_INDEX: false,
        FILE_SUFFIX: '.html',
        HAS_SOURCE:  true,
        SOURCELINK_SUFFIX: '.txt'
      };
    </script>
    <script type="text/javascript" src="_static/jquery.js"></script>
    <script type="text/javascript" src="_static/underscore.js"></script>
    <script type="text/javascript" src="_static/doctools.js"></script>
    <link rel="search" type="application/opensearchdescription+xml"
          title="Search within Sphinx 1.6.7 documentation"
          href="_static/opensearch.xml"/>
    <link rel="index" title="Index" href="genindex.html" />
    <link rel="search" title="Search" href="search.html" />
    <link rel="next" title="Internationalization" href="intl.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>
    <script type="text/javascript">
      // intelligent scrolling of the sidebar content
      $(window).scroll(function() {
        var sb = $('.sphinxsidebarwrapper');
        var win = $(window);
        var sbh = sb.height();
        var offset = $('.sphinxsidebar').position()['top'];
        var wintop = win.scrollTop();
        var winbot = wintop + win.innerHeight();
        var curtop = sb.position()['top'];
        var curbot = curtop + sbh;
        // does sidebar fit in window?
        if (sbh < win.innerHeight()) {
          // yes: easy case -- always keep at the top
          sb.css('top', $u.min([$u.max([0, wintop - offset - 10]),
                                $(document).height() - sbh - 200]));
        } else {
          // no: only scroll if top/bottom edge of sidebar is at
          // top/bottom edge of window
          if (curtop > wintop && curbot > winbot) {
            sb.css('top', $u.max([wintop - offset - 10, 0]));
          } else if (curtop < wintop && curbot < winbot) {
            sb.css('top', $u.min([winbot - sbh - offset - 20,
                                  $(document).height() - sbh - 200]));
          }
        }
      });
    </script>

  </head>
  <body>
<div class="pageheader">
  <ul>
    <li><a href="index.html">Home</a></li>
    <li><a href="install.html">Get it</a></li>
    <li><a href="contents.html">Docs</a></li>
    <li><a href="develop.html">Extend/Develop</a></li>
  </ul>
  <div>
    <a href="index.html">
      <img src="_static/sphinxheader.png" alt="SPHINX" />
    </a>
  </div>
</div>

    <div class="related" role="navigation" aria-label="related navigation">
      <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="intl.html" title="Internationalization"
             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>&#160;|</li>
        <li><a href="contents.html">Documentation</a> &#187;</li>
 
      </ul>
    </div>
      <div class="sphinxsidebar" role="navigation" aria-label="main navigation">
        <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-internationalization">Options for internationalization</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-apple-help-output">Options for Apple Help 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-text-output">Options for text output</a></li>
<li><a class="reference internal" href="#options-for-manual-page-output">Options for manual page output</a></li>
<li><a class="reference internal" href="#options-for-texinfo-output">Options for Texinfo output</a></li>
<li><a class="reference internal" href="#options-for-the-linkcheck-builder">Options for the linkcheck builder</a></li>
<li><a class="reference internal" href="#options-for-the-xml-builder">Options for the XML builder</a></li>
<li><a class="reference internal" href="#options-for-the-c-domain">Options for the C++ domain</a></li>
</ul>
</li>
<li><a class="reference internal" href="#example-of-configuration-file">Example of configuration file</a></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="intl.html"
                        title="next chapter">Internationalization</a></p>
  <div role="note" aria-label="source link">
    <h3>This Page</h3>
    <ul class="this-page-menu">
      <li><a href="_sources/config.rst.txt"
            rel="nofollow">Show Source</a></li>
    </ul>
   </div>
<div id="searchbox" style="display: none" role="search">
  <h3>Quick search</h3>
    <form class="search" action="search.html" method="get">
      <div><input type="text" name="q" /></div>
      <div><input type="submit" value="Go" /></div>
      <input type="hidden" name="check_keywords" value="yes" />
      <input type="hidden" name="area" value="default" />
    </form>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
        </div>
      </div>

    <div class="document">
      <div class="documentwrapper">
        <div class="bodywrapper">
          <div class="body" role="main">
            
  <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"><span class="xref std std-term">configuration directory</span></a> must contain a file named <code class="file docutils literal"><span class="pre">conf.py</span></code>.
This file (containing Python code) is called the “build configuration file”
and contains (almost) all configuration needed to customize Sphinx input
and output behavior.</p>
<blockquote>
<div>An optional file <a class="reference external" href="file:///usr/share/doc/docutils-doc/docs/user/config.html">docutils.conf</a> can be added to the configuration
directory to adjust <a class="reference external" href="http://docutils.sourceforge.net/">Docutils</a> configuration if not otherwise overriden or
set by Sphinx.</div></blockquote>
<p>The configuration file is executed as Python code at build time (using
<code class="xref py py-func docutils literal"><span class="pre">execfile()</span></code>, 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
<code class="docutils literal"><span class="pre">&quot;sphinx.builders.Builder&quot;</span></code> means the <code class="docutils literal"><span class="pre">Builder</span></code> class in the
<code class="docutils literal"><span class="pre">sphinx.builders</span></code> module.</li>
<li>Remember that document names use <code class="docutils literal"><span class="pre">/</span></code> as the path separator and don’t contain
the file name extension.</li>
<li>Since <code class="file docutils literal"><span class="pre">conf.py</span></code> 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 <code 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></code>) 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 <code class="docutils literal"><span class="pre">del</span></code> if appropriate.  Modules are
removed automatically, so you don’t need to <code class="docutils literal"><span class="pre">del</span></code> your imports after use.</li>
<li id="conf-tags">There is a special object named <code class="docutils literal"><span class="pre">tags</span></code> 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"><span class="std std-ref">Including content based on tags</span></a>).  Use
<code class="docutils literal"><span class="pre">tags.has('tag')</span></code> to query, <code class="docutils literal"><span class="pre">tags.add('tag')</span></code> and <code class="docutils literal"><span class="pre">tags.remove('tag')</span></code>
to change. Only tags set via the <code class="docutils literal"><span class="pre">-t</span></code> command-line option or via
<code class="docutils literal"><span class="pre">tags.add('tag')</span></code> can be queried using <code class="docutils literal"><span class="pre">tags.has('tag')</span></code>.
Note that the current builder tag is not available in <code class="docutils literal"><span class="pre">conf.py</span></code>, as it is
created <em>after</em> the builder is initialized.</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">
<code class="descname">extensions</code><a class="headerlink" href="#confval-extensions" title="Permalink to this definition">¶</a></dt>
<dd><p>A list of strings that are module names of <a class="reference internal" href="extensions.html#extensions"><span class="std std-ref">Sphinx Extensions</span></a>. These can be
extensions coming with Sphinx (named <code class="docutils literal"><span class="pre">sphinx.ext.*</span></code>) or custom ones.</p>
<p>Note that you can extend <code class="xref py py-data docutils literal"><span class="pre">sys.path</span></code> 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"><span class="xref std std-term">configuration directory</span></a>,
use <code class="xref py py-func docutils literal"><span class="pre">os.path.abspath()</span></code> like so:</p>
<div class="highlight-python"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">sys</span><span class="o">,</span> <span class="nn">os</span>

<span class="n">sys</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">abspath</span><span class="p">(</span><span class="s1">&#39;sphinxext&#39;</span><span class="p">))</span>

<span class="n">extensions</span> <span class="o">=</span> <span class="p">[</span><span class="s1">&#39;extname&#39;</span><span class="p">]</span>
</pre></div>
</div>
<p>That way, you can load an extension called <code class="docutils literal"><span class="pre">extname</span></code> from the subdirectory
<code class="docutils literal"><span class="pre">sphinxext</span></code>.</p>
<p>The configuration file itself can be an extension; for that, you only need to
provide a <code class="xref py py-func docutils literal"><span class="pre">setup()</span></code> function in it.</p>
</dd></dl>

<dl class="confval">
<dt id="confval-source_suffix">
<code class="descname">source_suffix</code><a class="headerlink" href="#confval-source_suffix" title="Permalink to this definition">¶</a></dt>
<dd><p>The file name extension, or list of extensions, of source files.  Only files
with this suffix will be read as sources.  Default is <code class="docutils literal"><span class="pre">'.rst'</span></code>.</p>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 1.3: </span>Can now be a list of extensions.</p>
</div>
</dd></dl>

<dl class="confval">
<dt id="confval-source_encoding">
<code class="descname">source_encoding</code><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 <code class="docutils literal"><span class="pre">'utf-8-sig'</span></code>.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 0.5: </span>Previously, Sphinx accepted only UTF-8 encoded sources.</p>
</div>
</dd></dl>

<dl class="confval">
<dt id="confval-source_parsers">
<code class="descname">source_parsers</code><a class="headerlink" href="#confval-source_parsers" title="Permalink to this definition">¶</a></dt>
<dd><p>If given, a dictionary of parser classes for different source suffices.  The
keys are the suffix, the values can be either a class or a string giving a
fully-qualified name of a parser class.  The parser class can be either
<code class="docutils literal"><span class="pre">docutils.parsers.Parser</span></code> or <a class="reference internal" href="extdev/parserapi.html#sphinx.parsers.Parser" title="sphinx.parsers.Parser"><code class="xref py py-class docutils literal"><span class="pre">sphinx.parsers.Parser</span></code></a>.  Files with a
suffix that is not in the dictionary will be parsed with the default
reStructuredText parser.</p>
<p>For example:</p>
<div class="highlight-python"><div class="highlight"><pre><span></span><span class="n">source_parsers</span> <span class="o">=</span> <span class="p">{</span><span class="s1">&#39;.md&#39;</span><span class="p">:</span> <span class="s1">&#39;recommonmark.parser.CommonMarkParser&#39;</span><span class="p">}</span>
</pre></div>
</div>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">Read more about how to use Markdown with Sphinx at <a class="reference internal" href="markdown.html#markdown"><span class="std std-ref">Markdown support</span></a>.</p>
</div>
<div class="versionadded">
<p><span class="versionmodified">New in version 1.3.</span></p>
</div>
</dd></dl>

<dl class="confval">
<dt id="confval-master_doc">
<code class="descname">master_doc</code><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"><code class="xref rst rst-dir docutils literal"><span class="pre">toctree</span></code></a> directive.  Default is <code class="docutils literal"><span class="pre">'contents'</span></code>.</p>
</dd></dl>

<dl class="confval">
<dt id="confval-exclude_patterns">
<code class="descname">exclude_patterns</code><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="#id10" 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><code class="docutils literal"><span class="pre">'library/xml.rst'</span></code> – ignores the <code class="docutils literal"><span class="pre">library/xml.rst</span></code> file (replaces
entry in <code class="xref std std-confval docutils literal"><span class="pre">unused_docs</span></code>)</li>
<li><code class="docutils literal"><span class="pre">'library/xml'</span></code> – ignores the <code class="docutils literal"><span class="pre">library/xml</span></code> directory (replaces entry
in <code class="xref std std-confval docutils literal"><span class="pre">exclude_trees</span></code>)</li>
<li><code class="docutils literal"><span class="pre">'library/xml*'</span></code> – ignores all files and directories starting with
<code class="docutils literal"><span class="pre">library/xml</span></code></li>
<li><code class="docutils literal"><span class="pre">'**/.svn'</span></code> – ignores all <code class="docutils literal"><span class="pre">.svn</span></code> directories (replaces entry in
<code class="xref std std-confval docutils literal"><span class="pre">exclude_dirnames</span></code>)</li>
</ul>
<p><a class="reference internal" href="#confval-exclude_patterns"><code class="xref std std-confval docutils literal"><span class="pre">exclude_patterns</span></code></a> is also consulted when looking for static files
in <a class="reference internal" href="#confval-html_static_path"><code class="xref std std-confval docutils literal"><span class="pre">html_static_path</span></code></a> and <a class="reference internal" href="#confval-html_extra_path"><code class="xref std std-confval docutils literal"><span class="pre">html_extra_path</span></code></a>.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 1.0.</span></p>
</div>
</dd></dl>

<dl class="confval">
<dt id="confval-templates_path">
<code class="descname">templates_path</code><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>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 1.3: </span>As these files are not meant to be built, they are automatically added to
<a class="reference internal" href="#confval-exclude_patterns"><code class="xref std std-confval docutils literal"><span class="pre">exclude_patterns</span></code></a>.</p>
</div>
</dd></dl>

<dl class="confval">
<dt id="confval-template_bridge">
<code class="descname">template_bridge</code><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="extdev/appapi.html#sphinx.application.TemplateBridge" title="sphinx.application.TemplateBridge"><code class="xref py py-class docutils literal"><span class="pre">TemplateBridge</span></code></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">
<code class="descname">rst_epilog</code><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"><div class="highlight"><pre><span></span><span class="n">rst_epilog</span> <span class="o">=</span> <span class="s2">&quot;&quot;&quot;</span>
<span class="s2">.. |psf| replace:: Python Software Foundation</span>
<span class="s2">&quot;&quot;&quot;</span>
</pre></div>
</div>
<div class="versionadded">
<p><span class="versionmodified">New in version 0.6.</span></p>
</div>
</dd></dl>

<dl class="confval">
<dt id="confval-rst_prolog">
<code class="descname">rst_prolog</code><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>
<div class="versionadded">
<p><span class="versionmodified">New in version 1.0.</span></p>
</div>
</dd></dl>

<dl class="confval">
<dt id="confval-primary_domain">
<code class="descname">primary_domain</code><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"><span class="std std-ref">domain</span></a>.  Can also be <code class="docutils literal"><span class="pre">None</span></code> to
disable a default domain.  The default is <code class="docutils literal"><span class="pre">'py'</span></code>.  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"><code class="xref rst rst-dir docutils literal"><span class="pre">default-domain</span></code></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>
<div class="versionadded">
<p><span class="versionmodified">New in version 1.0.</span></p>
</div>
</dd></dl>

<dl class="confval">
<dt id="confval-default_role">
<code class="descname">default_role</code><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 <code class="docutils literal"><span class="pre">`like</span> <span class="pre">this`</span></code>.  This can be set to
<code class="docutils literal"><span class="pre">'py:obj'</span></code> to make <code class="docutils literal"><span class="pre">`filter`</span></code> a cross-reference to the Python function
“filter”.  The default is <code class="docutils literal"><span class="pre">None</span></code>, which doesn’t reassign the default role.</p>
<p>The default role can always be set within individual documents using the
standard reST <code class="xref rst rst-dir docutils literal"><span class="pre">default-role</span></code> directive.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 0.4.</span></p>
</div>
</dd></dl>

<dl class="confval">
<dt id="confval-keep_warnings">
<code class="descname">keep_warnings</code><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 <code class="docutils literal"><span class="pre">sphinx-build</span></code> is run.</p>
<p>The default is <code class="docutils literal"><span class="pre">False</span></code>, the pre-0.5 behavior was to always keep them.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 0.5.</span></p>
</div>
</dd></dl>

<dl class="confval">
<dt id="confval-suppress_warnings">
<code class="descname">suppress_warnings</code><a class="headerlink" href="#confval-suppress_warnings" title="Permalink to this definition">¶</a></dt>
<dd><p>A list of warning types to suppress arbitrary warning messages.</p>
<p>Sphinx supports following warning types:</p>
<ul class="simple">
<li>app.add_node</li>
<li>app.add_directive</li>
<li>app.add_role</li>
<li>app.add_generic_role</li>
<li>app.add_source_parser</li>
<li>download.not_readable</li>
<li>image.not_readable</li>
<li>ref.term</li>
<li>ref.ref</li>
<li>ref.numref</li>
<li>ref.keyword</li>
<li>ref.option</li>
<li>ref.citation</li>
<li>ref.footnote</li>
<li>ref.doc</li>
<li>misc.highlighting_failure</li>
<li>toc.secnum</li>
<li>epub.unknown_project_files</li>
</ul>
<p>You can choose from these types.</p>
<p>Now, this option should be considered <em>experimental</em>.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 1.4.</span></p>
</div>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 1.5: </span>Added <code class="docutils literal"><span class="pre">misc.highlighting_failure</span></code></p>
</div>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 1.5.1: </span>Added <code class="docutils literal"><span class="pre">epub.unknown_project_files</span></code></p>
</div>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 1.6: </span>Added <code class="docutils literal"><span class="pre">ref.footnote</span></code></p>
</div>
</dd></dl>

<dl class="confval">
<dt id="confval-needs_sphinx">
<code class="descname">needs_sphinx</code><a class="headerlink" href="#confval-needs_sphinx" title="Permalink to this definition">¶</a></dt>
<dd><p>If set to a <code class="docutils literal"><span class="pre">major.minor</span></code> version string like <code class="docutils literal"><span class="pre">'1.1'</span></code>, Sphinx will
compare it with its version and refuse to build if it is too old.  Default is
no requirement.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 1.0.</span></p>
</div>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 1.4: </span>also accepts micro version string</p>
</div>
</dd></dl>

<dl class="confval">
<dt id="confval-needs_extensions">
<code class="descname">needs_extensions</code><a class="headerlink" href="#confval-needs_extensions" title="Permalink to this definition">¶</a></dt>
<dd><p>This value can be a dictionary specifying version requirements for extensions
in <a class="reference internal" href="#confval-extensions"><code class="xref std std-confval docutils literal"><span class="pre">extensions</span></code></a>, e.g. <code class="docutils literal"><span class="pre">needs_extensions</span> <span class="pre">=</span>
<span class="pre">{'sphinxcontrib.something':</span> <span class="pre">'1.5'}</span></code>.  The version strings should be in the
form <code class="docutils literal"><span class="pre">major.minor</span></code>.  Requirements do not have to be specified for all
extensions, only for those you want to check.</p>
<p>This requires that the extension specifies its version to Sphinx (see
<a class="reference internal" href="extdev/index.html#dev-extensions"><span class="std std-ref">Developing extensions for Sphinx</span></a> for how to do that).</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 1.3.</span></p>
</div>
</dd></dl>

<dl class="confval">
<dt id="confval-nitpicky">
<code class="descname">nitpicky</code><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 <code class="docutils literal"><span class="pre">False</span></code>.  You can activate this mode temporarily using
the <a class="reference internal" href="invocation.html#cmdoption-sphinx-build-n"><code class="xref std std-option docutils literal"><span class="pre">-n</span></code></a> command-line switch.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 1.0.</span></p>
</div>
</dd></dl>

<dl class="confval">
<dt id="confval-nitpick_ignore">
<code class="descname">nitpick_ignore</code><a class="headerlink" href="#confval-nitpick_ignore" title="Permalink to this definition">¶</a></dt>
<dd><p>A list of <code class="docutils literal"><span class="pre">(type,</span> <span class="pre">target)</span></code> tuples (by default empty) that should be ignored
when generating warnings in “nitpicky mode”.  Note that <code class="docutils literal"><span class="pre">type</span></code> should
include the domain name if present.  Example entries would be <code class="docutils literal"><span class="pre">('py:func',</span>
<span class="pre">'int')</span></code> or <code class="docutils literal"><span class="pre">('envvar',</span> <span class="pre">'LD_LIBRARY_PATH')</span></code>.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 1.1.</span></p>
</div>
</dd></dl>

<dl class="confval">
<dt id="confval-numfig">
<code class="descname">numfig</code><a class="headerlink" href="#confval-numfig" title="Permalink to this definition">¶</a></dt>
<dd><p>If true, figures, tables and code-blocks are automatically numbered if they
have a caption.  The <a class="reference internal" href="markup/inline.html#role-numref" title="numref role"><code class="xref rst rst-role docutils literal"><span class="pre">numref</span></code></a> role is enabled.
Obeyed so far only by HTML and LaTeX builders. Default is <code class="docutils literal"><span class="pre">False</span></code>.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">The LaTeX builder always assigns numbers whether this option is enabled or
not.</p>
</div>
<div class="versionadded">
<p><span class="versionmodified">New in version 1.3.</span></p>
</div>
</dd></dl>

<dl class="confval">
<dt id="confval-numfig_format">
<code class="descname">numfig_format</code><a class="headerlink" href="#confval-numfig_format" title="Permalink to this definition">¶</a></dt>
<dd><p>A dictionary mapping <code class="docutils literal"><span class="pre">'figure'</span></code>, <code class="docutils literal"><span class="pre">'table'</span></code>, <code class="docutils literal"><span class="pre">'code-block'</span></code> and
<code class="docutils literal"><span class="pre">'section'</span></code> to strings that are used for format of figure numbers.
As a special character, <cite>%s</cite> will be replaced to figure number.</p>
<p>Default is to use <code class="docutils literal"><span class="pre">'Fig.</span> <span class="pre">%s'</span></code> for <code class="docutils literal"><span class="pre">'figure'</span></code>, <code class="docutils literal"><span class="pre">'Table</span> <span class="pre">%s'</span></code> for
<code class="docutils literal"><span class="pre">'table'</span></code>, <code class="docutils literal"><span class="pre">'Listing</span> <span class="pre">%s'</span></code> for <code class="docutils literal"><span class="pre">'code-block'</span></code> and <code class="docutils literal"><span class="pre">'Section'</span></code> for
<code class="docutils literal"><span class="pre">'section'</span></code>.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 1.3.</span></p>
</div>
</dd></dl>

<dl class="confval">
<dt id="confval-numfig_secnum_depth">
<code class="descname">numfig_secnum_depth</code><a class="headerlink" href="#confval-numfig_secnum_depth" title="Permalink to this definition">¶</a></dt>
<dd><ul class="simple">
<li>if set to <code class="docutils literal"><span class="pre">0</span></code>, figures, tables and code-blocks are continuously numbered
starting at <code class="docutils literal"><span class="pre">1</span></code>.</li>
<li>if <code class="docutils literal"><span class="pre">1</span></code> (default) numbers will be <code class="docutils literal"><span class="pre">x.1</span></code>, <code class="docutils literal"><span class="pre">x.2</span></code>, … with <code class="docutils literal"><span class="pre">x</span></code>
the section number (top level sectioning; no <code class="docutils literal"><span class="pre">x.</span></code> if no section).
This naturally applies only if  section numbering has been activated via
the <code class="docutils literal"><span class="pre">:numbered:</span></code> option of the <a class="reference internal" href="markup/toctree.html#directive-toctree" title="toctree directive"><code class="xref rst rst-dir docutils literal"><span class="pre">toctree</span></code></a> directive.</li>
<li><code class="docutils literal"><span class="pre">2</span></code> means that numbers will be <code class="docutils literal"><span class="pre">x.y.1</span></code>, <code class="docutils literal"><span class="pre">x.y.2</span></code>, … if located in
a sub-section (but still <code class="docutils literal"><span class="pre">x.1</span></code>, <code class="docutils literal"><span class="pre">x.2</span></code>, … if located directly under a
section and <code class="docutils literal"><span class="pre">1</span></code>, <code class="docutils literal"><span class="pre">2</span></code>, … if not in any top level section.)</li>
<li>etc…</li>
</ul>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">The LaTeX builder currently ignores this configuration setting. It will
obey it at Sphinx 1.7.</p>
</div>
<div class="versionadded">
<p><span class="versionmodified">New in version 1.3.</span></p>
</div>
</dd></dl>

<dl class="confval">
<dt id="confval-smartquotes">
<code class="descname">smartquotes</code><a class="headerlink" href="#confval-smartquotes" title="Permalink to this definition">¶</a></dt>
<dd><p>If true, the <a class="reference external" href="file:///usr/share/doc/docutils-doc/docs/user/smartquotes.html">Docutils Smart Quotes transform</a>, originally based on
<a class="reference external" href="https://daringfireball.net/projects/smartypants/">SmartyPants</a> (limited to English) and currently applying to many
languages, will be used to convert quotes and dashes to typographically
correct entities.  Default: <code class="docutils literal"><span class="pre">True</span></code>.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 1.6.6: </span>It replaces deprecated <a class="reference internal" href="#confval-html_use_smartypants"><code class="xref std std-confval docutils literal"><span class="pre">html_use_smartypants</span></code></a>.
It applies by default to all builders except <code class="docutils literal"><span class="pre">man</span></code> and <code class="docutils literal"><span class="pre">text</span></code>
(see <a class="reference internal" href="#confval-smartquotes_excludes"><code class="xref std std-confval docutils literal"><span class="pre">smartquotes_excludes</span></code></a>.)</p>
</div>
<p>A <a class="reference external" href="file:///usr/share/doc/docutils-doc/docs/user/config.html">docutils.conf</a> file located in the configuration directory (or a
global <code class="file docutils literal"><span class="pre">~/.docutils</span></code> file) is obeyed unconditionally if it
<em>deactivates</em> smart quotes via the corresponding <a class="reference external" href="file:///usr/share/doc/docutils-doc/docs/user/config.html#smart-quotes">Docutils option</a>.  But
if it <em>activates</em> them, then <a class="reference internal" href="#confval-smartquotes"><code class="xref std std-confval docutils literal"><span class="pre">smartquotes</span></code></a> does prevail.</p>
</dd></dl>

<dl class="confval">
<dt id="confval-smartquotes_action">
<code class="descname">smartquotes_action</code><a class="headerlink" href="#confval-smartquotes_action" title="Permalink to this definition">¶</a></dt>
<dd><p>This string, for use with Docutils <code class="docutils literal"><span class="pre">0.14</span></code> or later, customizes the Smart
Quotes transform.  See the file <code class="file docutils literal"><span class="pre">smartquotes.py</span></code> at the <a class="reference external" href="https://sourceforge.net/p/docutils/code/HEAD/tree/trunk/docutils/">Docutils
repository</a> for details.  The default <code class="docutils literal"><span class="pre">'qDe'</span></code> educates normal <strong>q</strong>uote characters <code class="docutils literal"><span class="pre">&quot;</span></code>, <code class="docutils literal"><span class="pre">'</span></code>, em- and en-<strong>D</strong>ashes <code class="docutils literal"><span class="pre">---</span></code>, <code class="docutils literal"><span class="pre">--</span></code>, and
<strong>e</strong>llipses <code class="docutils literal"><span class="pre">...</span></code>.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 1.6.6.</span></p>
</div>
</dd></dl>

<dl class="confval">
<dt id="confval-smartquotes_excludes">
<code class="descname">smartquotes_excludes</code><a class="headerlink" href="#confval-smartquotes_excludes" title="Permalink to this definition">¶</a></dt>
<dd><p>This is a <code class="docutils literal"><span class="pre">dict</span></code> whose default is:</p>
<div class="highlight-python"><div class="highlight"><pre><span></span><span class="p">{</span><span class="s1">&#39;languages&#39;</span><span class="p">:</span> <span class="p">[</span><span class="s1">&#39;ja&#39;</span><span class="p">],</span> <span class="s1">&#39;builders&#39;</span><span class="p">:</span> <span class="p">[</span><span class="s1">&#39;man&#39;</span><span class="p">,</span> <span class="s1">&#39;text&#39;</span><span class="p">]}</span>
</pre></div>
</div>
<p>Each entry gives a sufficient condition to ignore the
<a class="reference internal" href="#confval-smartquotes"><code class="xref std std-confval docutils literal"><span class="pre">smartquotes</span></code></a> setting and deactivate the Smart Quotes transform.
Accepted keys are as above <code class="docutils literal"><span class="pre">'builders'</span></code> or <code class="docutils literal"><span class="pre">'languages'</span></code>.
The values are lists.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">Currently, in case of invocation of <strong class="program">make</strong> with multiple
targets, the first target name is the only one which is tested against
the <code class="docutils literal"><span class="pre">'builders'</span></code> entry and it decides for all.  Also, a <code class="docutils literal"><span class="pre">make</span> <span class="pre">text</span></code>
following <code class="docutils literal"><span class="pre">make</span> <span class="pre">html</span></code> needs to be issued in the form <code class="docutils literal"><span class="pre">make</span> <span class="pre">text</span>
<span class="pre">O=&quot;-E&quot;</span></code> to force re-parsing of source files, as the cached ones are
already transformed.  On the other hand the issue does not arise with
direct usage of <strong class="program">sphinx-build</strong> as it caches
(in its default usage) the parsed source files in per builder locations.</p>
</div>
<div class="versionadded">
<p><span class="versionmodified">New in version 1.6.6.</span></p>
</div>
</dd></dl>

<dl class="confval">
<dt id="confval-tls_verify">
<code class="descname">tls_verify</code><a class="headerlink" href="#confval-tls_verify" title="Permalink to this definition">¶</a></dt>
<dd><p>If true, Sphinx verifies server certifications.  Default is <code class="docutils literal"><span class="pre">True</span></code>.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 1.5.</span></p>
</div>
</dd></dl>

<dl class="confval">
<dt id="confval-tls_cacerts">
<code class="descname">tls_cacerts</code><a class="headerlink" href="#confval-tls_cacerts" title="Permalink to this definition">¶</a></dt>
<dd><p>A path to a certification file of CA or a path to directory which
contains the certificates.  This also allows a dictionary mapping
hostname to the path to certificate file.
The certificates are used to verify server certifications.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 1.5.</span></p>
</div>
</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">
<code class="descname">project</code><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">
<code class="descname">copyright</code><a class="headerlink" href="#confval-copyright" title="Permalink to this definition">¶</a></dt>
<dd><p>A copyright statement in the style <code class="docutils literal"><span class="pre">'2008,</span> <span class="pre">Author</span> <span class="pre">Name'</span></code>.</p>
</dd></dl>

<dl class="confval">
<dt id="confval-version">
<code class="descname">version</code><a class="headerlink" href="#confval-version" title="Permalink to this definition">¶</a></dt>
<dd><p>The major project version, used as the replacement for <code class="docutils literal"><span class="pre">|version|</span></code>.  For
example, for the Python documentation, this may be something like <code class="docutils literal"><span class="pre">2.6</span></code>.</p>
</dd></dl>

<dl class="confval">
<dt id="confval-release">
<code class="descname">release</code><a class="headerlink" href="#confval-release" title="Permalink to this definition">¶</a></dt>
<dd><p>The full project version, used as the replacement for <code class="docutils literal"><span class="pre">|release|</span></code> and
e.g. in the HTML templates.  For example, for the Python documentation, this
may be something like <code class="docutils literal"><span class="pre">2.6.0rc1</span></code>.</p>
<p>If you don’t need the separation provided between <a class="reference internal" href="setuptools.html#confval-version"><code class="xref std std-confval docutils literal"><span class="pre">version</span></code></a> and
<a class="reference internal" href="setuptools.html#confval-release"><code class="xref std std-confval docutils literal"><span class="pre">release</span></code></a>, just set them both to the same value.</p>
</dd></dl>

<dl class="confval">
<dt id="confval-today">
<code class="descname">today</code><a class="headerlink" href="#confval-today" title="Permalink to this definition">¶</a></dt>
<dt id="confval-today_fmt">
<code class="descname">today_fmt</code><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 <code class="docutils literal"><span class="pre">|today|</span></code>.</p>
<ul class="simple">
<li>If you set <a class="reference internal" href="setuptools.html#confval-today"><code class="xref std std-confval docutils literal"><span class="pre">today</span></code></a> to a non-empty value, it is used.</li>
<li>Otherwise, the current time is formatted using <code class="xref py py-func docutils literal"><span class="pre">time.strftime()</span></code> and
the format given in <a class="reference internal" href="#confval-today_fmt"><code class="xref std std-confval docutils literal"><span class="pre">today_fmt</span></code></a>.</li>
</ul>
<p>The default is no <a class="reference internal" href="setuptools.html#confval-today"><code class="xref std std-confval docutils literal"><span class="pre">today</span></code></a> and a <a class="reference internal" href="#confval-today_fmt"><code class="xref std std-confval docutils literal"><span class="pre">today_fmt</span></code></a> of <code class="docutils literal"><span class="pre">'%B</span> <span class="pre">%d,</span>
<span class="pre">%Y'</span></code> (or, if translation is enabled with <a class="reference internal" href="#confval-language"><code class="xref std std-confval docutils literal"><span class="pre">language</span></code></a>, an equivalent
format for the selected locale).</p>
</dd></dl>

<dl class="confval">
<dt id="confval-highlight_language">
<code class="descname">highlight_language</code><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
<code class="docutils literal"><span class="pre">'python3'</span></code>.  The value should be a valid Pygments lexer name, see
<a class="reference internal" href="markup/code.html#code-examples"><span class="std std-ref">Showing code examples</span></a> for more details.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 0.5.</span></p>
</div>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 1.4: </span>The default is now <code class="docutils literal"><span class="pre">'default'</span></code>. It is similar to <code class="docutils literal"><span class="pre">'python3'</span></code>;
it is mostly a superset of <code class="docutils literal"><span class="pre">'python'</span></code>. but it fallbacks to
<code class="docutils literal"><span class="pre">'none'</span></code> without warning if failed.  <code class="docutils literal"><span class="pre">'python3'</span></code> and other
languages will emit warning if failed.  If you prefer Python 2
only highlighting, you can set it back to <code class="docutils literal"><span class="pre">'python'</span></code>.</p>
</div>
</dd></dl>

<dl class="confval">
<dt id="confval-highlight_options">
<code class="descname">highlight_options</code><a class="headerlink" href="#confval-highlight_options" title="Permalink to this definition">¶</a></dt>
<dd><p>A dictionary of options that modify how the lexer specified by
<a class="reference internal" href="#confval-highlight_language"><code class="xref std std-confval docutils literal"><span class="pre">highlight_language</span></code></a> generates highlighted source code. These are
lexer-specific; for the options understood by each, see the
<a class="reference external" href="http://pygments.org/docs/lexers/">Pygments documentation</a>.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 1.3.</span></p>
</div>
</dd></dl>

<dl class="confval">
<dt id="confval-pygments_style">
<code class="descname">pygments_style</code><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.  If not set,
either the theme’s default style or <code class="docutils literal"><span class="pre">'sphinx'</span></code> is selected for HTML output.</p>
<div class="versionchanged">
<p><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>
</div>
</dd></dl>

<dl class="confval">
<dt id="confval-add_function_parentheses">
<code class="descname">add_function_parentheses</code><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 <code class="docutils literal"><span class="pre">:func:`input`</span></code>) to signify that the
name is callable.  Default is <code class="docutils literal"><span class="pre">True</span></code>.</p>
</dd></dl>

<dl class="confval">
<dt id="confval-add_module_names">
<code class="descname">add_module_names</code><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"><span class="xref std std-term">object</span></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"><code class="xref rst rst-dir docutils literal"><span class="pre">py:function</span></code></a> directives.  Default is <code class="docutils literal"><span class="pre">True</span></code>.</p>
</dd></dl>

<dl class="confval">
<dt id="confval-show_authors">
<code class="descname">show_authors</code><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"><code class="xref rst rst-dir docutils literal"><span class="pre">codeauthor</span></code></a> and
<a class="reference internal" href="markup/misc.html#directive-sectionauthor" title="sectionauthor directive"><code class="xref rst rst-dir docutils literal"><span class="pre">sectionauthor</span></code></a> directives produce any output in the built files.</p>
</dd></dl>

<dl class="confval">
<dt id="confval-modindex_common_prefix">
<code class="descname">modindex_common_prefix</code><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 <code class="docutils literal"><span class="pre">['foo.']</span></code>, then <code class="docutils literal"><span class="pre">foo.bar</span></code> is shown under <code class="docutils literal"><span class="pre">B</span></code>,
not <code class="docutils literal"><span class="pre">F</span></code>). This can be handy if you document a project that consists of a
single package.  Works only for the HTML builder currently.  Default is
<code class="docutils literal"><span class="pre">[]</span></code>.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 0.6.</span></p>
</div>
</dd></dl>

<dl class="confval">
<dt id="confval-trim_footnote_reference_space">
<code class="descname">trim_footnote_reference_space</code><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>
<div class="versionadded">
<p><span class="versionmodified">New in version 0.6.</span></p>
</div>
</dd></dl>

<dl class="confval">
<dt id="confval-trim_doctest_flags">
<code class="descname">trim_doctest_flags</code><a class="headerlink" href="#confval-trim_doctest_flags" title="Permalink to this definition">¶</a></dt>
<dd><p>If true, doctest flags (comments looking like <code class="docutils literal"><span class="pre">#</span> <span class="pre">doctest:</span> <span class="pre">FLAG,</span> <span class="pre">...</span></code>) at
the ends of lines and <code class="docutils literal"><span class="pre">&lt;BLANKLINE&gt;</span></code> markers are removed for all code
blocks showing interactive Python sessions (i.e. doctests).  Default is
<code class="docutils literal"><span class="pre">True</span></code>.  See the extension <a class="reference internal" href="ext/doctest.html#module-sphinx.ext.doctest" title="sphinx.ext.doctest: Test snippets in the documentation."><code class="xref py py-mod docutils literal"><span class="pre">doctest</span></code></a> for more
possibilities of including doctests.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 1.0.</span></p>
</div>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 1.1: </span>Now also removes <code class="docutils literal"><span class="pre">&lt;BLANKLINE&gt;</span></code>.</p>
</div>
</dd></dl>

</div>
<div class="section" id="options-for-internationalization">
<span id="intl-options"></span><h2>Options for internationalization<a class="headerlink" href="#options-for-internationalization" title="Permalink to this headline">¶</a></h2>
<p>These options influence Sphinx’s <em>Native Language Support</em>.  See the
documentation on <a class="reference internal" href="intl.html#intl"><span class="std std-ref">Internationalization</span></a> for details.</p>
<dl class="confval">
<dt id="confval-language">
<code class="descname">language</code><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, Sphinx will try to
substitute individual paragraphs from your documents with the translation
sets obtained from <a class="reference internal" href="#confval-locale_dirs"><code class="xref std std-confval docutils literal"><span class="pre">locale_dirs</span></code></a>.  Sphinx will search
language-specific figures named by <cite>figure_language_filename</cite> and substitute
them for original figures.  In the LaTeX builder, a suitable language will
be selected as an option for the <em>Babel</em> package.  Default is <code class="docutils literal"><span class="pre">None</span></code>,
which means that no translation will be done.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 0.5.</span></p>
</div>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 1.4: </span>Support figure substitution</p>
</div>
<p>Currently supported languages by Sphinx are:</p>
<ul class="simple">
<li><code class="docutils literal"><span class="pre">bn</span></code> – Bengali</li>
<li><code class="docutils literal"><span class="pre">ca</span></code> – Catalan</li>
<li><code class="docutils literal"><span class="pre">cs</span></code> – Czech</li>
<li><code class="docutils literal"><span class="pre">da</span></code> – Danish</li>
<li><code class="docutils literal"><span class="pre">de</span></code> – German</li>
<li><code class="docutils literal"><span class="pre">en</span></code> – English</li>
<li><code class="docutils literal"><span class="pre">es</span></code> – Spanish</li>
<li><code class="docutils literal"><span class="pre">et</span></code> – Estonian</li>
<li><code class="docutils literal"><span class="pre">eu</span></code> – Basque</li>
<li><code class="docutils literal"><span class="pre">fa</span></code> – Iranian</li>
<li><code class="docutils literal"><span class="pre">fi</span></code> – Finnish</li>
<li><code class="docutils literal"><span class="pre">fr</span></code> – French</li>
<li><code class="docutils literal"><span class="pre">he</span></code> – Hebrew</li>
<li><code class="docutils literal"><span class="pre">hr</span></code> – Croatian</li>
<li><code class="docutils literal"><span class="pre">hu</span></code> – Hungarian</li>
<li><code class="docutils literal"><span class="pre">id</span></code> – Indonesian</li>
<li><code class="docutils literal"><span class="pre">it</span></code> – Italian</li>
<li><code class="docutils literal"><span class="pre">ja</span></code> – Japanese</li>
<li><code class="docutils literal"><span class="pre">ko</span></code> – Korean</li>
<li><code class="docutils literal"><span class="pre">lt</span></code> – Lithuanian</li>
<li><code class="docutils literal"><span class="pre">lv</span></code> – Latvian</li>
<li><code class="docutils literal"><span class="pre">mk</span></code> – Macedonian</li>
<li><code class="docutils literal"><span class="pre">nb_NO</span></code> – Norwegian Bokmal</li>
<li><code class="docutils literal"><span class="pre">ne</span></code> – Nepali</li>
<li><code class="docutils literal"><span class="pre">nl</span></code> – Dutch</li>
<li><code class="docutils literal"><span class="pre">pl</span></code> – Polish</li>
<li><code class="docutils literal"><span class="pre">pt_BR</span></code> – Brazilian Portuguese</li>
<li><code class="docutils literal"><span class="pre">pt_PT</span></code> – European Portuguese</li>
<li><code class="docutils literal"><span class="pre">ru</span></code> – Russian</li>
<li><code class="docutils literal"><span class="pre">si</span></code> – Sinhala</li>
<li><code class="docutils literal"><span class="pre">sk</span></code> – Slovak</li>
<li><code class="docutils literal"><span class="pre">sl</span></code> – Slovenian</li>
<li><code class="docutils literal"><span class="pre">sv</span></code> – Swedish</li>
<li><code class="docutils literal"><span class="pre">tr</span></code> – Turkish</li>
<li><code class="docutils literal"><span class="pre">uk_UA</span></code> – Ukrainian</li>
<li><code class="docutils literal"><span class="pre">vi</span></code> – Vietnamese</li>
<li><code class="docutils literal"><span class="pre">zh_CN</span></code> – Simplified Chinese</li>
<li><code class="docutils literal"><span class="pre">zh_TW</span></code> – Traditional Chinese</li>
</ul>
</dd></dl>

<dl class="confval">
<dt id="confval-locale_dirs">
<code class="descname">locale_dirs</code><a class="headerlink" href="#confval-locale_dirs" title="Permalink to this definition">¶</a></dt>
<dd><div class="versionadded">
<p><span class="versionmodified">New in version 0.5.</span></p>
</div>
<p>Directories in which to search for additional message catalogs (see
<a class="reference internal" href="#confval-language"><code class="xref std std-confval docutils literal"><span class="pre">language</span></code></a>), relative to the source directory.  The directories on
this path are searched by the standard <code class="xref py py-mod docutils literal"><span class="pre">gettext</span></code> module.</p>
<p>Internal messages are fetched from a text domain of <code class="docutils literal"><span class="pre">sphinx</span></code>; so if you
add the directory <code class="file docutils literal"><span class="pre">./locale</span></code> to this setting, the message catalogs
(compiled from <code class="docutils literal"><span class="pre">.po</span></code> format using <strong class="program">msgfmt</strong>) must be in
<code class="file docutils literal"><span class="pre">./locale/</span><em><span class="pre">language</span></em><span class="pre">/LC_MESSAGES/sphinx.mo</span></code>.  The text domain of
individual documents depends on <a class="reference internal" href="#confval-gettext_compact"><code class="xref std std-confval docutils literal"><span class="pre">gettext_compact</span></code></a>.</p>
<p>The default is <code class="docutils literal"><span class="pre">['locales']</span></code>.</p>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 1.5: </span>Use <code class="docutils literal"><span class="pre">locales</span></code> directory as a default value</p>
</div>
</dd></dl>

<dl class="confval">
<dt id="confval-gettext_compact">
<code class="descname">gettext_compact</code><a class="headerlink" href="#confval-gettext_compact" title="Permalink to this definition">¶</a></dt>
<dd><div class="versionadded">
<p><span class="versionmodified">New in version 1.1.</span></p>
</div>
<p>If true, a document’s text domain is its docname if it is a top-level
project file and its very base directory otherwise.</p>
<p>By default, the document <code class="docutils literal"><span class="pre">markup/code.rst</span></code> ends up in the <code class="docutils literal"><span class="pre">markup</span></code> text
domain.  With this option set to <code class="docutils literal"><span class="pre">False</span></code>, it is <code class="docutils literal"><span class="pre">markup/code</span></code>.</p>
</dd></dl>

<dl class="confval">
<dt id="confval-gettext_uuid">
<code class="descname">gettext_uuid</code><a class="headerlink" href="#confval-gettext_uuid" title="Permalink to this definition">¶</a></dt>
<dd><p>If true, Sphinx generates uuid information for version tracking in message
catalogs. It is used for:</p>
<ul class="simple">
<li>Add uid line for each msgids in .pot files.</li>
<li>Calculate similarity between new msgids and previously saved old msgids.
This calculation takes a long time.</li>
</ul>
<p>If you want to accelerate the calculation, you can use
<code class="docutils literal"><span class="pre">python-levenshtein</span></code> 3rd-party package written in C by using
<strong class="command">pip install python-levenshtein</strong>.</p>
<p>The default is <code class="docutils literal"><span class="pre">False</span></code>.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 1.3.</span></p>
</div>
</dd></dl>

<dl class="confval">
<dt id="confval-gettext_location">
<code class="descname">gettext_location</code><a class="headerlink" href="#confval-gettext_location" title="Permalink to this definition">¶</a></dt>
<dd><p>If true, Sphinx generates location information for messages in message
catalogs.</p>
<p>The default is <code class="docutils literal"><span class="pre">True</span></code>.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 1.3.</span></p>
</div>
</dd></dl>

<dl class="confval">
<dt id="confval-gettext_auto_build">
<code class="descname">gettext_auto_build</code><a class="headerlink" href="#confval-gettext_auto_build" title="Permalink to this definition">¶</a></dt>
<dd><p>If true, Sphinx builds mo file for each translation catalog files.</p>
<p>The default is <code class="docutils literal"><span class="pre">True</span></code>.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 1.3.</span></p>
</div>
</dd></dl>

<dl class="confval">
<dt id="confval-gettext_additional_targets">
<code class="descname">gettext_additional_targets</code><a class="headerlink" href="#confval-gettext_additional_targets" title="Permalink to this definition">¶</a></dt>
<dd><p>To specify names to enable gettext extracting and translation applying for
i18n additionally. You can specify below names:</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Index:</th><td class="field-body">index terms</td>
</tr>
<tr class="field-even field"><th class="field-name">Literal-block:</th><td class="field-body">literal blocks: <code class="docutils literal"><span class="pre">::</span></code> and <code class="docutils literal"><span class="pre">code-block</span></code>.</td>
</tr>
<tr class="field-odd field"><th class="field-name">Doctest-block:</th><td class="field-body">doctest block</td>
</tr>
<tr class="field-even field"><th class="field-name">Raw:</th><td class="field-body">raw content</td>
</tr>
<tr class="field-odd field"><th class="field-name">Image:</th><td class="field-body">image/figure uri and alt</td>
</tr>
</tbody>
</table>
<p>For example: <code class="docutils literal"><span class="pre">gettext_additional_targets</span> <span class="pre">=</span> <span class="pre">['literal-block',</span> <span class="pre">'image']</span></code>.</p>
<p>The default is <code class="docutils literal"><span class="pre">[]</span></code>.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 1.3.</span></p>
</div>
</dd></dl>

<dl class="confval">
<dt id="confval-figure_language_filename">
<code class="descname">figure_language_filename</code><a class="headerlink" href="#confval-figure_language_filename" title="Permalink to this definition">¶</a></dt>
<dd><p>The filename format for language-specific figures.  The default value is
<code class="docutils literal"><span class="pre">{root}.{language}{ext}</span></code>.  It will be expanded to
<code class="docutils literal"><span class="pre">dirname/filename.en.png</span></code> from <code class="docutils literal"><span class="pre">..</span> <span class="pre">image::</span> <span class="pre">dirname/filename.png</span></code>.
The available format tokens are:</p>
<ul class="simple">
<li><code class="docutils literal"><span class="pre">{root}</span></code> - the filename, including any path component, without the file
extension, e.g. <code class="docutils literal"><span class="pre">dirname/filename</span></code></li>
<li><code class="docutils literal"><span class="pre">{path}</span></code> - the directory path component of the filename, with a trailing
slash if non-empty, e.g. <code class="docutils literal"><span class="pre">dirname/</span></code></li>
<li><code class="docutils literal"><span class="pre">{basename}</span></code> - the filename without the directory path or file extension
components, e.g. <code class="docutils literal"><span class="pre">filename</span></code></li>
<li><code class="docutils literal"><span class="pre">{ext}</span></code> - the file extension, e.g. <code class="docutils literal"><span class="pre">.png</span></code></li>
<li><code class="docutils literal"><span class="pre">{language}</span></code> - the translation language, e.g. <code class="docutils literal"><span class="pre">en</span></code></li>
</ul>
<p>For example, setting this to <code class="docutils literal"><span class="pre">{path}{language}/{basename}{ext}</span></code> will
expand to <code class="docutils literal"><span class="pre">dirname/en/filename.png</span></code> instead.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 1.4.</span></p>
</div>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 1.5: </span>Added <code class="docutils literal"><span class="pre">{path}</span></code> and <code class="docutils literal"><span class="pre">{basename}</span></code> tokens.</p>
</div>
</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’s HTMLWriter class.</p>
<dl class="confval">
<dt id="confval-html_theme">
<code class="descname">html_theme</code><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"><span class="doc">section about
theming</span></a>.  The default is <code class="docutils literal"><span class="pre">'alabaster'</span></code>.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 0.6.</span></p>
</div>
</dd></dl>

<dl class="confval">
<dt id="confval-html_theme_options">
<code class="descname">html_theme_options</code><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"><span class="std std-ref">this section</span></a>.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 0.6.</span></p>
</div>
</dd></dl>

<dl class="confval">
<dt id="confval-html_theme_path">
<code class="descname">html_theme_path</code><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>
<div class="versionadded">
<p><span class="versionmodified">New in version 0.6.</span></p>
</div>
</dd></dl>

<dl class="confval">
<dt id="confval-html_style">
<code class="descname">html_style</code><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’s <code class="file docutils literal"><span class="pre">static/</span></code> path, or in one of the custom paths given in
<a class="reference internal" href="#confval-html_static_path"><code class="xref std std-confval docutils literal"><span class="pre">html_static_path</span></code></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 <code class="docutils literal"><span class="pre">&#64;import</span></code> to import the theme’s stylesheet.</p>
</dd></dl>

<dl class="confval">
<dt id="confval-html_title">
<code class="descname">html_title</code><a class="headerlink" href="#confval-html_title" title="Permalink to this definition">¶</a></dt>
<dd><p>The “title” for HTML documentation generated with Sphinx’s own templates.
This is appended to the <code class="docutils literal"><span class="pre">&lt;title&gt;</span></code> tag of individual pages, and used in the
navigation bar as the “topmost” element.  It defaults to <code class="samp docutils literal"><span class="pre">'</span><em><span class="pre">&lt;project&gt;</span></em>
<span class="pre">v</span><em><span class="pre">&lt;revision&gt;</span></em> <span class="pre">documentation'</span></code>.</p>
</dd></dl>

<dl class="confval">
<dt id="confval-html_short_title">
<code class="descname">html_short_title</code><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"><code class="xref std std-confval docutils literal"><span class="pre">html_title</span></code></a>.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 0.4.</span></p>
</div>
</dd></dl>

<dl class="confval">
<dt id="confval-html_context">
<code class="descname">html_context</code><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#id3"><code class="xref std std-option docutils literal"><span class="pre">-A</span></code></a> command-line option of <code class="docutils literal"><span class="pre">sphinx-build</span></code>.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 0.5.</span></p>
</div>
</dd></dl>

<dl class="confval">
<dt id="confval-html_logo">
<code class="descname">html_logo</code><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 (path relative to the
<a class="reference internal" href="glossary.html#term-configuration-directory"><span class="xref std std-term">configuration directory</span></a>) 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: <code class="docutils literal"><span class="pre">None</span></code>.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 0.4.1: </span>The image file will be copied to the <code class="docutils literal"><span class="pre">_static</span></code> directory of the output
HTML, but only if the file does not already exist there.</p>
</div>
</dd></dl>

<dl class="confval">
<dt id="confval-html_favicon">
<code class="descname">html_favicon</code><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 (path relative to the
<a class="reference internal" href="glossary.html#term-configuration-directory"><span class="xref std std-term">configuration directory</span></a>) that is the favicon of the docs.  Modern
browsers use this as the icon for tabs, windows and bookmarks.  It should
be a Windows-style icon file (<code class="docutils literal"><span class="pre">.ico</span></code>), which is 16x16 or 32x32
pixels large.  Default: <code class="docutils literal"><span class="pre">None</span></code>.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 0.4: </span>The image file will be copied to the <code class="docutils literal"><span class="pre">_static</span></code> directory of the output
HTML, but only if the file does not already exist there.</p>
</div>
</dd></dl>

<dl class="confval">
<dt id="confval-html_static_path">
<code class="descname">html_static_path</code><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’s
<code class="file docutils literal"><span class="pre">_static</span></code> directory after the theme’s static files, so a file
named <code class="file docutils literal"><span class="pre">default.css</span></code> will overwrite the theme’s
<code class="file docutils literal"><span class="pre">default.css</span></code>.</p>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 0.4: </span>The paths in <a class="reference internal" href="#confval-html_static_path"><code class="xref std std-confval docutils literal"><span class="pre">html_static_path</span></code></a> can now contain subdirectories.</p>
</div>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 1.0: </span>The entries in <a class="reference internal" href="#confval-html_static_path"><code class="xref std std-confval docutils literal"><span class="pre">html_static_path</span></code></a> can now be single files.</p>
</div>
</dd></dl>

<dl class="confval">
<dt id="confval-html_extra_path">
<code class="descname">html_extra_path</code><a class="headerlink" href="#confval-html_extra_path" title="Permalink to this definition">¶</a></dt>
<dd><p>A list of paths that contain extra files not directly related to
the documentation, such as <code class="file docutils literal"><span class="pre">robots.txt</span></code> or <code class="file docutils literal"><span class="pre">.htaccess</span></code>.
Relative paths are taken as relative to the configuration
directory.  They are copied to the output directory.  They will
overwrite any existing file of the same name.</p>
<p>As these files are not meant to be built, they are automatically added to
<a class="reference internal" href="#confval-exclude_patterns"><code class="xref std std-confval docutils literal"><span class="pre">exclude_patterns</span></code></a>.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 1.2.</span></p>
</div>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 1.4: </span>The dotfiles in the extra directory will be copied to the output directory.
And it refers <a class="reference internal" href="#confval-exclude_patterns"><code class="xref std std-confval docutils literal"><span class="pre">exclude_patterns</span></code></a> on copying extra files and
directories, and ignores if path matches to patterns.</p>
</div>
</dd></dl>

<dl class="confval">
<dt id="confval-html_last_updated_fmt">
<code class="descname">html_last_updated_fmt</code><a class="headerlink" href="#confval-html_last_updated_fmt" title="Permalink to this definition">¶</a></dt>
<dd><p>If this is not None, a ‘Last updated on:’ timestamp is inserted
at every page bottom, using the given <code class="xref py py-func docutils literal"><span class="pre">strftime()</span></code> format.
The empty string is equivalent to <code class="docutils literal"><span class="pre">'%b</span> <span class="pre">%d,</span> <span class="pre">%Y'</span></code> (or a
locale-dependent equivalent).</p>
</dd></dl>

<dl class="confval">
<dt id="confval-html_use_smartypants">
<code class="descname">html_use_smartypants</code><a class="headerlink" href="#confval-html_use_smartypants" title="Permalink to this definition">¶</a></dt>
<dd><p>If true, quotes and dashes are converted to typographically correct
entities.  Default: <code class="docutils literal"><span class="pre">True</span></code>.</p>
<div class="deprecated">
<p><span class="versionmodified">Deprecated since version 1.6: </span>To disable smart quotes, use rather <a class="reference internal" href="#confval-smartquotes"><code class="xref std std-confval docutils literal"><span class="pre">smartquotes</span></code></a>.</p>
</div>
</dd></dl>

<dl class="confval">
<dt id="confval-html_add_permalinks">
<code class="descname">html_add_permalinks</code><a class="headerlink" href="#confval-html_add_permalinks" title="Permalink to this definition">¶</a></dt>
<dd><p>Sphinx will add “permalinks” for each heading and description environment as
paragraph signs that become visible when the mouse hovers over them.</p>
<p>This value determines the text for the permalink; it defaults to <code class="docutils literal"><span class="pre">&quot;¶&quot;</span></code>.
Set it to <code class="docutils literal"><span class="pre">None</span></code> or the empty string to disable permalinks.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 0.6: </span>Previously, this was always activated.</p>
</div>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 1.1: </span>This can now be a string to select the actual text of the link.
Previously, only boolean values were accepted.</p>
</div>
</dd></dl>

<dl class="confval">
<dt id="confval-html_sidebars">
<code class="descname">html_sidebars</code><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="#id10" id="id7">[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:
<code 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></code>.</p>
</li>
<li><p class="first">If a value is a single string, it specifies a custom sidebar to be added
between the <code class="docutils literal"><span class="pre">'sourcelink.html'</span></code> and <code class="docutils literal"><span class="pre">'searchbox.html'</span></code> 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"><code class="xref std std-confval docutils literal"><span class="pre">html_show_sourcelink</span></code></a></li>
<li><strong>searchbox.html</strong> – the “quick search” box</li>
</ul>
<p>Example:</p>
<div class="highlight-python"><div class="highlight"><pre><span></span><span class="n">html_sidebars</span> <span class="o">=</span> <span class="p">{</span>
   <span class="s1">&#39;**&#39;</span><span class="p">:</span> <span class="p">[</span><span class="s1">&#39;globaltoc.html&#39;</span><span class="p">,</span> <span class="s1">&#39;sourcelink.html&#39;</span><span class="p">,</span> <span class="s1">&#39;searchbox.html&#39;</span><span class="p">],</span>
   <span class="s1">&#39;using/windows&#39;</span><span class="p">:</span> <span class="p">[</span><span class="s1">&#39;windowssidebar.html&#39;</span><span class="p">,</span> <span class="s1">&#39;searchbox.html&#39;</span><span class="p">],</span>
<span class="p">}</span>
</pre></div>
</div>
<p>This will render the custom template <code class="docutils literal"><span class="pre">windowssidebar.html</span></code> 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>
<div class="versionadded">
<p><span class="versionmodified">New in version 1.0: </span>The ability to use globbing keys and to specify multiple sidebars.</p>
</div>
<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">
<code class="descname">html_additional_pages</code><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"><div class="highlight"><pre><span></span><span class="n">html_additional_pages</span> <span class="o">=</span> <span class="p">{</span>
    <span class="s1">&#39;download&#39;</span><span class="p">:</span> <span class="s1">&#39;customdownload.html&#39;</span><span class="p">,</span>
<span class="p">}</span>
</pre></div>
</div>
<p>This will render the template <code class="docutils literal"><span class="pre">customdownload.html</span></code> as the page
<code class="docutils literal"><span class="pre">download.html</span></code>.</p>
</dd></dl>

<dl class="confval">
<dt id="confval-html_domain_indices">
<code class="descname">html_domain_indices</code><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
<code class="docutils literal"><span class="pre">True</span></code>.</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 <code class="docutils literal"><span class="pre">'py-modindex'</span></code>.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 1.0.</span></p>
</div>
</dd></dl>

<dl class="confval">
<dt id="confval-html_use_index">
<code class="descname">html_use_index</code><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 <code class="docutils literal"><span class="pre">True</span></code>.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 0.4.</span></p>
</div>
</dd></dl>

<dl class="confval">
<dt id="confval-html_split_index">
<code class="descname">html_split_index</code><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 <code class="docutils literal"><span class="pre">False</span></code>.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 0.4.</span></p>
</div>
</dd></dl>

<dl class="confval">
<dt id="confval-html_copy_source">
<code class="descname">html_copy_source</code><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
<code class="file docutils literal"><span class="pre">_sources/</span><em><span class="pre">name</span></em></code>.  The default is <code class="docutils literal"><span class="pre">True</span></code>.</p>
<div class="admonition warning">
<p class="first admonition-title">Warning</p>
<p class="last">If this config value is set to <code class="docutils literal"><span class="pre">False</span></code>, 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">
<code class="descname">html_show_sourcelink</code><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"><code class="xref std std-confval docutils literal"><span class="pre">html_copy_source</span></code></a> is true as well), links to the
reST sources will be added to the sidebar.  The default is <code class="docutils literal"><span class="pre">True</span></code>.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 0.6.</span></p>
</div>
</dd></dl>

<dl class="confval">
<dt id="confval-html_sourcelink_suffix">
<code class="descname">html_sourcelink_suffix</code><a class="headerlink" href="#confval-html_sourcelink_suffix" title="Permalink to this definition">¶</a></dt>
<dd><p>Suffix to be appended to source links (see <a class="reference internal" href="#confval-html_show_sourcelink"><code class="xref std std-confval docutils literal"><span class="pre">html_show_sourcelink</span></code></a>),
unless they have this suffix already.  Default is <code class="docutils literal"><span class="pre">'.txt'</span></code>.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 1.5.</span></p>
</div>
</dd></dl>

<dl class="confval">
<dt id="confval-html_use_opensearch">
<code class="descname">html_use_opensearch</code><a class="headerlink" href="#confval-html_use_opensearch" title="Permalink to this definition">¶</a></dt>
<dd><p>If nonempty, an <a class="reference external" href="http://www.opensearch.org/Home">OpenSearch</a> description file will be
output, and all pages will contain a <code class="docutils literal"><span class="pre">&lt;link&gt;</span></code> 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. <code class="docutils literal"><span class="pre">&quot;https://docs.python.org&quot;</span></code>.  The
default is <code class="docutils literal"><span class="pre">''</span></code>.</p>
</dd></dl>

<dl class="confval">
<dt id="confval-html_file_suffix">
<code class="descname">html_file_suffix</code><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
<code class="docutils literal"><span class="pre">&quot;.html&quot;</span></code>.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 0.4.</span></p>
</div>
</dd></dl>

<dl class="confval">
<dt id="confval-html_link_suffix">
<code class="descname">html_link_suffix</code><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"><code class="xref std std-confval docutils literal"><span class="pre">html_file_suffix</span></code></a> is set to; it can be set differently (e.g. to
support different web server setups).</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 0.6.</span></p>
</div>
</dd></dl>

<dl class="confval">
<dt id="confval-html_show_copyright">
<code class="descname">html_show_copyright</code><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
<code class="docutils literal"><span class="pre">True</span></code>.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 1.0.</span></p>
</div>
</dd></dl>

<dl class="confval">
<dt id="confval-html_show_sphinx">
<code class="descname">html_show_sphinx</code><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
<code class="docutils literal"><span class="pre">True</span></code>.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 0.4.</span></p>
</div>
</dd></dl>

<dl class="confval">
<dt id="confval-html_output_encoding">
<code class="descname">html_output_encoding</code><a class="headerlink" href="#confval-html_output_encoding" title="Permalink to this definition">¶</a></dt>
<dd><p>Encoding of HTML output files. Default is <code class="docutils literal"><span class="pre">'utf-8'</span></code>.  Note that this
encoding name must both be a valid Python encoding name and a valid HTML
<code class="docutils literal"><span class="pre">charset</span></code> value.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 1.0.</span></p>
</div>
</dd></dl>

<dl class="confval">
<dt id="confval-html_compact_lists">
<code class="descname">html_compact_lists</code><a class="headerlink" href="#confval-html_compact_lists" title="Permalink to this definition">¶</a></dt>
<dd><p>If true, a list all whose items consist of a single paragraph and/or a
sub-list all whose items etc… (recursive definition) will not use the
<code class="docutils literal"><span class="pre">&lt;p&gt;</span></code> element for any of its items. This is standard docutils behavior.
Default: <code class="docutils literal"><span class="pre">True</span></code>.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 1.0.</span></p>
</div>
</dd></dl>

<dl class="confval">
<dt id="confval-html_secnumber_suffix">
<code class="descname">html_secnumber_suffix</code><a class="headerlink" href="#confval-html_secnumber_suffix" title="Permalink to this definition">¶</a></dt>
<dd><p>Suffix for section numbers.  Default: <code class="docutils literal"><span class="pre">&quot;.</span> <span class="pre">&quot;</span></code>.  Set to <code class="docutils literal"><span class="pre">&quot;</span> <span class="pre">&quot;</span></code> to suppress
the final dot on section numbers.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 1.0.</span></p>
</div>
</dd></dl>

<dl class="confval">
<dt id="confval-html_search_language">
<code class="descname">html_search_language</code><a class="headerlink" href="#confval-html_search_language" title="Permalink to this definition">¶</a></dt>
<dd><p>Language to be used for generating the HTML full-text search index.  This
defaults to the global language selected with <a class="reference internal" href="#confval-language"><code class="xref std std-confval docutils literal"><span class="pre">language</span></code></a>.  If there
is no support for this language, <code class="docutils literal"><span class="pre">&quot;en&quot;</span></code> is used which selects the English
language.</p>
<p>Support is present for these languages:</p>
<ul class="simple">
<li><code class="docutils literal"><span class="pre">da</span></code> – Danish</li>
<li><code class="docutils literal"><span class="pre">nl</span></code> – Dutch</li>
<li><code class="docutils literal"><span class="pre">en</span></code> – English</li>
<li><code class="docutils literal"><span class="pre">fi</span></code> – Finnish</li>
<li><code class="docutils literal"><span class="pre">fr</span></code> – French</li>
<li><code class="docutils literal"><span class="pre">de</span></code> – German</li>
<li><code class="docutils literal"><span class="pre">hu</span></code> – Hungarian</li>
<li><code class="docutils literal"><span class="pre">it</span></code> – Italian</li>
<li><code class="docutils literal"><span class="pre">ja</span></code> – Japanese</li>
<li><code class="docutils literal"><span class="pre">no</span></code> – Norwegian</li>
<li><code class="docutils literal"><span class="pre">pt</span></code> – Portuguese</li>
<li><code class="docutils literal"><span class="pre">ro</span></code> – Romanian</li>
<li><code class="docutils literal"><span class="pre">ru</span></code> – Russian</li>
<li><code class="docutils literal"><span class="pre">es</span></code> – Spanish</li>
<li><code class="docutils literal"><span class="pre">sv</span></code> – Swedish</li>
<li><code class="docutils literal"><span class="pre">tr</span></code> – Turkish</li>
<li><code class="docutils literal"><span class="pre">zh</span></code> – Chinese</li>
</ul>
<div class="admonition-accelerating-build-speed admonition">
<p class="first admonition-title">Accelerating build speed</p>
<p>Each language (except Japanese) provides its own stemming algorithm.
Sphinx uses a Python implementation by default.  You can use a C
implementation to accelerate building the index file.</p>
<ul class="last simple">
<li><a class="reference external" href="https://pypi.python.org/pypi/PorterStemmer">PorterStemmer</a> (<code class="docutils literal"><span class="pre">en</span></code>)</li>
<li><a class="reference external" href="https://pypi.python.org/pypi/PyStemmer">PyStemmer</a> (all languages)</li>
</ul>
</div>
<div class="versionadded">
<p><span class="versionmodified">New in version 1.1: </span>With support for <code class="docutils literal"><span class="pre">en</span></code> and <code class="docutils literal"><span class="pre">ja</span></code>.</p>
</div>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 1.3: </span>Added additional languages.</p>
</div>
</dd></dl>

<dl class="confval">
<dt id="confval-html_search_options">
<code class="descname">html_search_options</code><a class="headerlink" href="#confval-html_search_options" title="Permalink to this definition">¶</a></dt>
<dd><p>A dictionary with options for the search language support, empty by default.
The meaning of these options depends on the language selected.</p>
<p>The English support has no options.</p>
<p>The Japanese support has these options:</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Type:</th><td class="field-body"><p class="first"><span class="target" id="type">type</span> is dotted module path string to specify Splitter implementation which
should be derived from <code class="xref py py-class docutils literal"><span class="pre">sphinx.search.ja.BaseSplitter</span></code>.
If not specified or None is specified, <code class="docutils literal"><span class="pre">'sphinx.search.ja.DefaultSplitter'</span></code> will
be used.</p>
<p>You can choose from these modules:</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name" colspan="2">‘sphinx.search.ja.DefaultSplitter’:</th></tr>
<tr class="field-odd field"><td>&#160;</td><td class="field-body">TinySegmenter algorithm. This is default splitter.</td>
</tr>
<tr class="field-even field"><th class="field-name" colspan="2">‘sphinx.search.ja.MeCabSplitter’:</th></tr>
<tr class="field-even field"><td>&#160;</td><td class="field-body">MeCab binding. To use this splitter, ‘mecab’ python binding or dynamic link
library (‘libmecab.so’ for linux, ‘libmecab.dll’ for windows) is required.</td>
</tr>
<tr class="field-odd field"><th class="field-name" colspan="2">‘sphinx.search.ja.JanomeSplitter’:</th></tr>
<tr class="field-odd field"><td>&#160;</td><td class="field-body">Janome binding. To use this splitter,
<a class="reference external" href="https://pypi.python.org/pypi/Janome">Janome</a> is required.</td>
</tr>
</tbody>
</table>
<p class="last">To keep compatibility, <code class="docutils literal"><span class="pre">'mecab'</span></code>, <code class="docutils literal"><span class="pre">'janome'</span></code> and <code class="docutils literal"><span class="pre">'default'</span></code> are also
acceptable. However it will be deprecated in Sphinx-1.6.</p>
</td>
</tr>
</tbody>
</table>
<p>Other option values depend on splitter value which you choose.</p>
<dl class="docutils">
<dt>Options for <code class="docutils literal"><span class="pre">'mecab'</span></code>:</dt>
<dd><table class="first docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">dic_enc:</th><td class="field-body"><span class="target" id="dic-enc-option">dic_enc option</span> is the encoding for the MeCab algorithm.</td>
</tr>
<tr class="field-even field"><th class="field-name">dict:</th><td class="field-body"><span class="target" id="dict-option">dict option</span> is the dictionary to use for the MeCab algorithm.</td>
</tr>
<tr class="field-odd field"><th class="field-name">lib:</th><td class="field-body"><span class="target" id="lib-option">lib option</span> is the library name for finding the MeCab library via ctypes if
the Python binding is not installed.</td>
</tr>
</tbody>
</table>
<p>For example:</p>
<div class="last highlight-python"><div class="highlight"><pre><span></span><span class="n">html_search_options</span> <span class="o">=</span> <span class="p">{</span>
    <span class="s1">&#39;type&#39;</span><span class="p">:</span> <span class="s1">&#39;mecab&#39;</span><span class="p">,</span>
    <span class="s1">&#39;dic_enc&#39;</span><span class="p">:</span> <span class="s1">&#39;utf-8&#39;</span><span class="p">,</span>
    <span class="s1">&#39;dict&#39;</span><span class="p">:</span> <span class="s1">&#39;/path/to/mecab.dic&#39;</span><span class="p">,</span>
    <span class="s1">&#39;lib&#39;</span><span class="p">:</span> <span class="s1">&#39;/path/to/libmecab.so&#39;</span><span class="p">,</span>
<span class="p">}</span>
</pre></div>
</div>
</dd>
<dt>Options for <code class="docutils literal"><span class="pre">'janome'</span></code>:</dt>
<dd><table class="first last docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">user_dic:</th><td class="field-body"><span class="target" id="user-dic-option">user_dic option</span> is the user dictionary file path for Janome.</td>
</tr>
<tr class="field-even field"><th class="field-name">user_dic_enc:</th><td class="field-body"><span class="target" id="user-dic-enc-option">user_dic_enc option</span> is the encoding for the user dictionary file specified by
<code class="docutils literal"><span class="pre">user_dic</span></code> option. Default is ‘utf8’.</td>
</tr>
</tbody>
</table>
</dd>
</dl>
<div class="versionadded">
<p><span class="versionmodified">New in version 1.1.</span></p>
</div>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 1.4: </span>html_search_options for Japanese is re-organized and any custom splitter can be
used by <a class="reference internal" href="#type">type</a> settings.</p>
</div>
<p>The Chinese support has these options:</p>
<ul class="simple">
<li><code class="docutils literal"><span class="pre">dict</span></code>  – the <code class="docutils literal"><span class="pre">jieba</span></code> dictionary path if want to use
custom dictionary.</li>
</ul>
</dd></dl>

<dl class="confval">
<dt id="confval-html_search_scorer">
<code class="descname">html_search_scorer</code><a class="headerlink" href="#confval-html_search_scorer" title="Permalink to this definition">¶</a></dt>
<dd><p>The name of a JavaScript file (relative to the configuration directory) that
implements a search results scorer.  If empty, the default will be used.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 1.2.</span></p>
</div>
</dd></dl>

<dl class="confval">
<dt id="confval-html_scaled_image_link">
<code class="descname">html_scaled_image_link</code><a class="headerlink" href="#confval-html_scaled_image_link" title="Permalink to this definition">¶</a></dt>
<dd><p>If true, images itself links to the original image if it doesn’t have
‘target’ option or scale related options: ‘scale’, ‘width’, ‘height’.
The default is <code class="docutils literal"><span class="pre">True</span></code>.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 1.3.</span></p>
</div>
</dd></dl>

<dl class="confval">
<dt id="confval-htmlhelp_basename">
<code class="descname">htmlhelp_basename</code><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 <code class="docutils literal"><span class="pre">'pydoc'</span></code>.</p>
</dd></dl>

<dl class="confval">
<dt id="confval-html_experimental_html5_writer">
<code class="descname">html_experimental_html5_writer</code><a class="headerlink" href="#confval-html_experimental_html5_writer" title="Permalink to this definition">¶</a></dt>
<dd><p>Output is processed with HTML5 writer.  This feature needs docutils 0.13 or newer.  Default is <code class="docutils literal"><span class="pre">False</span></code>.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 1.6.</span></p>
</div>
</dd></dl>

</div>
<div class="section" id="options-for-apple-help-output">
<span id="applehelp-options"></span><h2>Options for Apple Help output<a class="headerlink" href="#options-for-apple-help-output" title="Permalink to this headline">¶</a></h2>
<div class="versionadded">
<p><span class="versionmodified">New in version 1.3.</span></p>
</div>
<p>These options influence the Apple Help output.  This builder derives from the
HTML builder, so the HTML options also apply where appropriate.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p>Apple Help output will only work on Mac OS X 10.6 and higher, as it
requires the <strong class="program">hiutil</strong> and <strong class="program">codesign</strong> command line tools,
neither of which are Open Source.</p>
<p class="last">You can disable the use of these tools using
<a class="reference internal" href="#confval-applehelp_disable_external_tools"><code class="xref std std-confval docutils literal"><span class="pre">applehelp_disable_external_tools</span></code></a>, but the result will not be a
valid help book until the indexer is run over the <code class="docutils literal"><span class="pre">.lproj</span></code> folders within
the bundle.</p>
</div>
<dl class="confval">
<dt id="confval-applehelp_bundle_name">
<code class="descname">applehelp_bundle_name</code><a class="headerlink" href="#confval-applehelp_bundle_name" title="Permalink to this definition">¶</a></dt>
<dd><p>The basename for the Apple Help Book.  Defaults to the <a class="reference internal" href="setuptools.html#confval-project"><code class="xref std std-confval docutils literal"><span class="pre">project</span></code></a>
name.</p>
</dd></dl>

<dl class="confval">
<dt id="confval-applehelp_bundle_id">
<code class="descname">applehelp_bundle_id</code><a class="headerlink" href="#confval-applehelp_bundle_id" title="Permalink to this definition">¶</a></dt>
<dd><p>The bundle ID for the help book bundle.</p>
<div class="admonition warning">
<p class="first admonition-title">Warning</p>
<p class="last">You <em>must</em> set this value in order to generate Apple Help.</p>
</div>
</dd></dl>

<dl class="confval">
<dt id="confval-applehelp_dev_region">
<code class="descname">applehelp_dev_region</code><a class="headerlink" href="#confval-applehelp_dev_region" title="Permalink to this definition">¶</a></dt>
<dd><p>The development region.  Defaults to <code class="docutils literal"><span class="pre">'en-us'</span></code>, which is Apple’s
recommended setting.</p>
</dd></dl>

<dl class="confval">
<dt id="confval-applehelp_bundle_version">
<code class="descname">applehelp_bundle_version</code><a class="headerlink" href="#confval-applehelp_bundle_version" title="Permalink to this definition">¶</a></dt>
<dd><p>The bundle version (as a string).  Defaults to <code class="docutils literal"><span class="pre">'1'</span></code>.</p>
</dd></dl>

<dl class="confval">
<dt id="confval-applehelp_icon">
<code class="descname">applehelp_icon</code><a class="headerlink" href="#confval-applehelp_icon" title="Permalink to this definition">¶</a></dt>
<dd><p>The help bundle icon file, or <code class="docutils literal"><span class="pre">None</span></code> for no icon.  According to Apple’s
documentation, this should be a 16-by-16 pixel version of the application’s
icon with a transparent background, saved as a PNG file.</p>
</dd></dl>

<dl class="confval">
<dt id="confval-applehelp_kb_product">
<code class="descname">applehelp_kb_product</code><a class="headerlink" href="#confval-applehelp_kb_product" title="Permalink to this definition">¶</a></dt>
<dd><p>The product tag for use with <a class="reference internal" href="#confval-applehelp_kb_url"><code class="xref std std-confval docutils literal"><span class="pre">applehelp_kb_url</span></code></a>.  Defaults to
<code class="samp docutils literal"><span class="pre">'</span><em><span class="pre">&lt;project&gt;</span></em><span class="pre">-</span><em><span class="pre">&lt;release&gt;</span></em><span class="pre">'</span></code>.</p>
</dd></dl>

<dl class="confval">
<dt id="confval-applehelp_kb_url">
<code class="descname">applehelp_kb_url</code><a class="headerlink" href="#confval-applehelp_kb_url" title="Permalink to this definition">¶</a></dt>
<dd><p>The URL for your knowledgebase server,
e.g. <code class="docutils literal"><span class="pre">https://example.com/kbsearch.py?p='product'&amp;q='query'&amp;l='lang'</span></code>.
Help Viewer will replace the values <code class="docutils literal"><span class="pre">'product'</span></code>, <code class="docutils literal"><span class="pre">'query'</span></code> and
<code class="docutils literal"><span class="pre">'lang'</span></code> at runtime with the contents of <a class="reference internal" href="#confval-applehelp_kb_product"><code class="xref std std-confval docutils literal"><span class="pre">applehelp_kb_product</span></code></a>,
the text entered by the user in the search box and the user’s system
language respectively.</p>
<p>Defaults to <code class="docutils literal"><span class="pre">None</span></code> for no remote search.</p>
</dd></dl>

<dl class="confval">
<dt id="confval-applehelp_remote_url">
<code class="descname">applehelp_remote_url</code><a class="headerlink" href="#confval-applehelp_remote_url" title="Permalink to this definition">¶</a></dt>
<dd><p>The URL for remote content.  You can place a copy of your Help Book’s
<code class="docutils literal"><span class="pre">Resources</span></code> folder at this location and Help Viewer will attempt to use
it to fetch updated content.</p>
<p>e.g. if you set it to <code class="docutils literal"><span class="pre">https://example.com/help/Foo/</span></code> and Help Viewer
wants a copy of <code class="docutils literal"><span class="pre">index.html</span></code> for an English speaking customer, it will
look at <code class="docutils literal"><span class="pre">https://example.com/help/Foo/en.lproj/index.html</span></code>.</p>
<p>Defaults to <code class="docutils literal"><span class="pre">None</span></code> for no remote content.</p>
</dd></dl>

<dl class="confval">
<dt id="confval-applehelp_index_anchors">
<code class="descname">applehelp_index_anchors</code><a class="headerlink" href="#confval-applehelp_index_anchors" title="Permalink to this definition">¶</a></dt>
<dd><p>If <code class="docutils literal"><span class="pre">True</span></code>, tell the help indexer to index anchors in the generated HTML.
This can be useful for jumping to a particular topic using the
<code class="docutils literal"><span class="pre">AHLookupAnchor</span></code> function or the <code class="docutils literal"><span class="pre">openHelpAnchor:inBook:</span></code> method in
your code.  It also allows you to use <code class="docutils literal"><span class="pre">help:anchor</span></code> URLs; see the Apple
documentation for more information on this topic.</p>
</dd></dl>

<dl class="confval">
<dt id="confval-applehelp_min_term_length">
<code class="descname">applehelp_min_term_length</code><a class="headerlink" href="#confval-applehelp_min_term_length" title="Permalink to this definition">¶</a></dt>
<dd><p>Controls the minimum term length for the help indexer.  Defaults to
<code class="docutils literal"><span class="pre">None</span></code>, which means the default will be used.</p>
</dd></dl>

<dl class="confval">
<dt id="confval-applehelp_stopwords">
<code class="descname">applehelp_stopwords</code><a class="headerlink" href="#confval-applehelp_stopwords" title="Permalink to this definition">¶</a></dt>
<dd><p>Either a language specification (to use the built-in stopwords), or the
path to a stopwords plist, or <code class="docutils literal"><span class="pre">None</span></code> if you do not want to use stopwords.
The default stopwords plist can be found at
<code class="docutils literal"><span class="pre">/usr/share/hiutil/Stopwords.plist</span></code> and contains, at time of writing,
stopwords for the following languages:</p>
<table border="1" class="docutils">
<colgroup>
<col width="69%" />
<col width="31%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Language</th>
<th class="head">Code</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td>English</td>
<td>en</td>
</tr>
<tr class="row-odd"><td>German</td>
<td>de</td>
</tr>
<tr class="row-even"><td>Spanish</td>
<td>es</td>
</tr>
<tr class="row-odd"><td>French</td>
<td>fr</td>
</tr>
<tr class="row-even"><td>Swedish</td>
<td>sv</td>
</tr>
<tr class="row-odd"><td>Hungarian</td>
<td>hu</td>
</tr>
<tr class="row-even"><td>Italian</td>
<td>it</td>
</tr>
</tbody>
</table>
<p>Defaults to <a class="reference internal" href="#confval-language"><code class="xref std std-confval docutils literal"><span class="pre">language</span></code></a>, or if that is not set, to <code class="xref std std-confval docutils literal"><span class="pre">en</span></code>.</p>
</dd></dl>

<dl class="confval">
<dt id="confval-applehelp_locale">
<code class="descname">applehelp_locale</code><a class="headerlink" href="#confval-applehelp_locale" title="Permalink to this definition">¶</a></dt>
<dd><p>Specifies the locale to generate help for.  This is used to determine
the name of the <code class="docutils literal"><span class="pre">.lproj</span></code> folder inside the Help Book’s <code class="docutils literal"><span class="pre">Resources</span></code>, and
is passed to the help indexer.</p>
<p>Defaults to <a class="reference internal" href="#confval-language"><code class="xref std std-confval docutils literal"><span class="pre">language</span></code></a>, or if that is not set, to <code class="xref std std-confval docutils literal"><span class="pre">en</span></code>.</p>
</dd></dl>

<dl class="confval">
<dt id="confval-applehelp_title">
<code class="descname">applehelp_title</code><a class="headerlink" href="#confval-applehelp_title" title="Permalink to this definition">¶</a></dt>
<dd><p>Specifies the help book title.  Defaults to <code class="samp docutils literal"><span class="pre">'</span><em><span class="pre">&lt;project&gt;</span></em> <span class="pre">Help'</span></code>.</p>
</dd></dl>

<dl class="confval">
<dt id="confval-applehelp_codesign_identity">
<code class="descname">applehelp_codesign_identity</code><a class="headerlink" href="#confval-applehelp_codesign_identity" title="Permalink to this definition">¶</a></dt>
<dd><p>Specifies the identity to use for code signing, or <code class="docutils literal"><span class="pre">None</span></code> if code signing
is not to be performed.</p>
<p>Defaults to the value of the environment variable <code class="docutils literal"><span class="pre">CODE_SIGN_IDENTITY</span></code>,
which is set by Xcode for script build phases, or <code class="docutils literal"><span class="pre">None</span></code> if that variable
is not set.</p>
</dd></dl>

<dl class="confval">
<dt id="confval-applehelp_codesign_flags">
<code class="descname">applehelp_codesign_flags</code><a class="headerlink" href="#confval-applehelp_codesign_flags" title="Permalink to this definition">¶</a></dt>
<dd><p>A <em>list</em> of additional arguments to pass to <strong class="program">codesign</strong> when
signing the help book.</p>
<p>Defaults to a list based on the value of the environment variable
<code class="docutils literal"><span class="pre">OTHER_CODE_SIGN_FLAGS</span></code>, which is set by Xcode for script build phases,
or the empty list if that variable is not set.</p>
</dd></dl>

<dl class="confval">
<dt id="confval-applehelp_indexer_path">
<code class="descname">applehelp_indexer_path</code><a class="headerlink" href="#confval-applehelp_indexer_path" title="Permalink to this definition">¶</a></dt>
<dd><p>The path to the <strong class="program">hiutil</strong> program.  Defaults to
<code class="docutils literal"><span class="pre">'/usr/bin/hiutil'</span></code>.</p>
</dd></dl>

<dl class="confval">
<dt id="confval-applehelp_codesign_path">
<code class="descname">applehelp_codesign_path</code><a class="headerlink" href="#confval-applehelp_codesign_path" title="Permalink to this definition">¶</a></dt>
<dd><p>The path to the <strong class="program">codesign</strong> program.  Defaults to
<code class="docutils literal"><span class="pre">'/usr/bin/codesign'</span></code>.</p>
</dd></dl>

<dl class="confval">
<dt id="confval-applehelp_disable_external_tools">
<code class="descname">applehelp_disable_external_tools</code><a class="headerlink" href="#confval-applehelp_disable_external_tools" title="Permalink to this definition">¶</a></dt>
<dd><p>If <code class="docutils literal"><span class="pre">True</span></code>, the builder will not run the indexer or the code signing tool,
no matter what other settings are specified.</p>
<p>This is mainly useful for testing, or where you want to run the Sphinx
build on a non-Mac OS X platform and then complete the final steps on OS X
for some reason.</p>
<p>Defaults to <code class="docutils literal"><span class="pre">False</span></code>.</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">
<code class="descname">epub_basename</code><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="setuptools.html#confval-project"><code class="xref std std-confval docutils literal"><span class="pre">project</span></code></a> name.</p>
</dd></dl>

<dl class="confval">
<dt id="confval-epub_theme">
<code class="descname">epub_theme</code><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 <code class="docutils literal"><span class="pre">'epub'</span></code>, a theme designed to
save visual space.</p>
</dd></dl>

<dl class="confval">
<dt id="confval-epub_theme_options">
<code class="descname">epub_theme_options</code><a class="headerlink" href="#confval-epub_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"><span class="std std-ref">this section</span></a>.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 1.2.</span></p>
</div>
</dd></dl>

<dl class="confval">
<dt id="confval-epub_title">
<code class="descname">epub_title</code><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"><code class="xref std std-confval docutils literal"><span class="pre">html_title</span></code></a> option
but can be set independently for epub creation.</p>
</dd></dl>

<dl class="confval">
<dt id="confval-epub_description">
<code class="descname">epub_description</code><a class="headerlink" href="#confval-epub_description" title="Permalink to this definition">¶</a></dt>
<dd><p>The description of the document. The default value is <code class="docutils literal"><span class="pre">'unknown'</span></code>.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 1.4.</span></p>
</div>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 1.5: </span>Renamed from <code class="docutils literal"><span class="pre">epub3_description</span></code></p>
</div>
</dd></dl>

<dl class="confval">
<dt id="confval-epub_author">
<code class="descname">epub_author</code><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 <code class="docutils literal"><span class="pre">'unknown'</span></code>.</p>
</dd></dl>

<dl class="confval">
<dt id="confval-epub_contributor">
<code class="descname">epub_contributor</code><a class="headerlink" href="#confval-epub_contributor" title="Permalink to this definition">¶</a></dt>
<dd><p>The name of a person, organization, etc. that played a secondary role in
the creation of the content of an EPUB Publication. The default value is
<code class="docutils literal"><span class="pre">'unknown'</span></code>.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 1.4.</span></p>
</div>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 1.5: </span>Renamed from <code class="docutils literal"><span class="pre">epub3_contributor</span></code></p>
</div>
</dd></dl>

<dl class="confval">
<dt id="confval-epub_language">
<code class="descname">epub_language</code><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"><code class="xref std std-confval docutils literal"><span class="pre">language</span></code></a> option or <code class="docutils literal"><span class="pre">'en'</span></code> if unset.</p>
</dd></dl>

<dl class="confval">
<dt id="confval-epub_publisher">
<code class="descname">epub_publisher</code><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
<code class="docutils literal"><span class="pre">'unknown'</span></code>.</p>
</dd></dl>

<dl class="confval">
<dt id="confval-epub_copyright">
<code class="descname">epub_copyright</code><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="setuptools.html#confval-copyright"><code class="xref std std-confval docutils literal"><span class="pre">copyright</span></code></a>
option but can be set independently for epub creation.</p>
</dd></dl>

<dl class="confval">
<dt id="confval-epub_identifier">
<code class="descname">epub_identifier</code><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
<code class="docutils literal"><span class="pre">'unknown'</span></code>.</p>
</dd></dl>

<dl class="confval">
<dt id="confval-epub_scheme">
<code class="descname">epub_scheme</code><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"><code class="xref std std-confval docutils literal"><span class="pre">epub_identifier</span></code></a>.  This is put in
the Dublin Core metadata.  For published books the scheme is <code class="docutils literal"><span class="pre">'ISBN'</span></code>.  If
you use the project homepage, <code class="docutils literal"><span class="pre">'URL'</span></code> seems reasonable.  The default value
is <code class="docutils literal"><span class="pre">'unknown'</span></code>.</p>
</dd></dl>

<dl class="confval">
<dt id="confval-epub_uid">
<code class="descname">epub_uid</code><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
<a class="reference external" href="https://www.w3.org/TR/REC-xml/#NT-NameStartChar">XML’s Name format</a> string.
You can’t use hyphen, period, numbers as a first character.
The default value is <code class="docutils literal"><span class="pre">'unknown'</span></code>.</p>
</dd></dl>

<dl class="confval">
<dt id="confval-epub_cover">
<code class="descname">epub_cover</code><a class="headerlink" href="#confval-epub_cover" title="Permalink to this definition">¶</a></dt>
<dd><p>The cover page information.  This is a tuple containing the filenames of
the cover image and the html template.  The rendered html cover page is
inserted as the first item in the spine in <code class="file docutils literal"><span class="pre">content.opf</span></code>.  If the
template filename is empty, no html cover page is created.  No cover at all
is created if the tuple is empty.  Examples:</p>
<div class="highlight-python"><div class="highlight"><pre><span></span><span class="n">epub_cover</span> <span class="o">=</span> <span class="p">(</span><span class="s1">&#39;_static/cover.png&#39;</span><span class="p">,</span> <span class="s1">&#39;epub-cover.html&#39;</span><span class="p">)</span>
<span class="n">epub_cover</span> <span class="o">=</span> <span class="p">(</span><span class="s1">&#39;_static/cover.png&#39;</span><span class="p">,</span> <span class="s1">&#39;&#39;</span><span class="p">)</span>
<span class="n">epub_cover</span> <span class="o">=</span> <span class="p">()</span>
</pre></div>
</div>
<p>The default value is <code class="docutils literal"><span class="pre">()</span></code>.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 1.1.</span></p>
</div>
</dd></dl>

<dl class="confval">
<dt id="confval-epub_guide">
<code class="descname">epub_guide</code><a class="headerlink" href="#confval-epub_guide" title="Permalink to this definition">¶</a></dt>
<dd><p>Meta data for the guide element of <code class="file docutils literal"><span class="pre">content.opf</span></code>. This is a
sequence of tuples containing the <em>type</em>, the <em>uri</em> and the <em>title</em> of
the optional guide information. See the OPF documentation
at <a class="reference external" href="http://idpf.org/epub">http://idpf.org/epub</a> for details. If possible, default entries
for the <em>cover</em> and <em>toc</em> types are automatically inserted. However,
the types can be explicitly overwritten if the default entries are not
appropriate. Example:</p>
<div class="highlight-python"><div class="highlight"><pre><span></span><span class="n">epub_guide</span> <span class="o">=</span> <span class="p">((</span><span class="s1">&#39;cover&#39;</span><span class="p">,</span> <span class="s1">&#39;cover.html&#39;</span><span class="p">,</span> <span class="sa">u</span><span class="s1">&#39;Cover Page&#39;</span><span class="p">),)</span>
</pre></div>
</div>
<p>The default value is <code class="docutils literal"><span class="pre">()</span></code>.</p>
</dd></dl>

<dl class="confval">
<dt id="confval-epub_pre_files">
<code class="descname">epub_pre_files</code><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 <code class="file docutils literal"><span class="pre">toc.ncx</span></code>.  Example:</p>
<div class="highlight-python"><div class="highlight"><pre><span></span><span class="n">epub_pre_files</span> <span class="o">=</span> <span class="p">[</span>
    <span class="p">(</span><span class="s1">&#39;index.html&#39;</span><span class="p">,</span> <span class="s1">&#39;Welcome&#39;</span><span class="p">),</span>
<span class="p">]</span>
</pre></div>
</div>
<p>The default value is <code class="docutils literal"><span class="pre">[]</span></code>.</p>
</dd></dl>

<dl class="confval">
<dt id="confval-epub_post_files">
<code class="descname">epub_post_files</code><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 <code class="file docutils literal"><span class="pre">toc.ncx</span></code>.  The default value is <code class="docutils literal"><span class="pre">[]</span></code>.</p>
</dd></dl>

<dl class="confval">
<dt id="confval-epub_exclude_files">
<code class="descname">epub_exclude_files</code><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 <code class="docutils literal"><span class="pre">[]</span></code>.</p>
</dd></dl>

<dl class="confval">
<dt id="confval-epub_tocdepth">
<code class="descname">epub_tocdepth</code><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 <code class="file docutils literal"><span class="pre">toc.ncx</span></code>.  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">
<code class="descname">epub_tocdup</code><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
its nested toc listing.  This allows easier navigation to the top of
a chapter, but can be confusing because it mixes entries of different
depth in one list.  The default value is <code class="docutils literal"><span class="pre">True</span></code>.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last"><code class="docutils literal"><span class="pre">epub3</span></code> builder ignores <code class="docutils literal"><span class="pre">epub_tocdup</span></code> option(always <code class="docutils literal"><span class="pre">False</span></code>)</p>
</div>
</dd></dl>

<dl class="confval">
<dt id="confval-epub_tocscope">
<code class="descname">epub_tocscope</code><a class="headerlink" href="#confval-epub_tocscope" title="Permalink to this definition">¶</a></dt>
<dd><p>This setting control the scope of the epub table of contents.  The setting
can have the following values:</p>
<ul class="simple">
<li><code class="docutils literal"><span class="pre">'default'</span></code> – include all toc entries that are not hidden (default)</li>
<li><code class="docutils literal"><span class="pre">'includehidden'</span></code> – include all toc entries</li>
</ul>
<div class="versionadded">
<p><span class="versionmodified">New in version 1.2.</span></p>
</div>
</dd></dl>

<dl class="confval">
<dt id="confval-epub_fix_images">
<code class="descname">epub_fix_images</code><a class="headerlink" href="#confval-epub_fix_images" title="Permalink to this definition">¶</a></dt>
<dd><p>This flag determines if sphinx should try to fix image formats that are not
supported by some epub readers.  At the moment palette images with a small
color table are upgraded.  You need the Python Image Library (Pillow the
successor of the PIL) installed to use this option.  The default value is
<code class="docutils literal"><span class="pre">False</span></code> because the automatic conversion may lose information.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 1.2.</span></p>
</div>
</dd></dl>

<dl class="confval">
<dt id="confval-epub_max_image_width">
<code class="descname">epub_max_image_width</code><a class="headerlink" href="#confval-epub_max_image_width" title="Permalink to this definition">¶</a></dt>
<dd><p>This option specifies the maximum width of images.  If it is set to a value
greater than zero, images with a width larger than the given value are
scaled accordingly.  If it is zero, no scaling is performed. The default
value is <code class="docutils literal"><span class="pre">0</span></code>.  You need the Python Image Library (Pillow) installed to use
this option.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 1.2.</span></p>
</div>
</dd></dl>

<dl class="confval">
<dt id="confval-epub_show_urls">
<code class="descname">epub_show_urls</code><a class="headerlink" href="#confval-epub_show_urls" title="Permalink to this definition">¶</a></dt>
<dd><p>Control whether to display URL addresses. This is very useful for
readers that have no other means to display the linked URL. The
settings can have the following values:</p>
<ul class="simple">
<li><code class="docutils literal"><span class="pre">'inline'</span></code> – display URLs inline in parentheses (default)</li>
<li><code class="docutils literal"><span class="pre">'footnote'</span></code> – display URLs in footnotes</li>
<li><code class="docutils literal"><span class="pre">'no'</span></code> – do not display URLs</li>
</ul>
<p>The display of inline URLs can be customized by adding CSS rules for the
class <code class="docutils literal"><span class="pre">link-target</span></code>.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 1.2.</span></p>
</div>
</dd></dl>

<dl class="confval">
<dt id="confval-epub_use_index">
<code class="descname">epub_use_index</code><a class="headerlink" href="#confval-epub_use_index" title="Permalink to this definition">¶</a></dt>
<dd><p>If true, add an index to the epub document.  It defaults to the
<a class="reference internal" href="#confval-html_use_index"><code class="xref std std-confval docutils literal"><span class="pre">html_use_index</span></code></a> option but can be set independently for epub
creation.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 1.2.</span></p>
</div>
</dd></dl>

<dl class="confval">
<dt id="confval-epub_writing_mode">
<code class="descname">epub_writing_mode</code><a class="headerlink" href="#confval-epub_writing_mode" title="Permalink to this definition">¶</a></dt>
<dd><p>It specifies writing direction. It can accept <code class="docutils literal"><span class="pre">'horizontal'</span></code> (default) and
<code class="docutils literal"><span class="pre">'vertical'</span></code></p>
<table border="1" class="docutils">
<colgroup>
<col width="33%" />
<col width="33%" />
<col width="33%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head stub"><code class="docutils literal"><span class="pre">epub_writing_mode</span></code></th>
<th class="head"><code class="docutils literal"><span class="pre">'horizontal'</span></code></th>
<th class="head"><code class="docutils literal"><span class="pre">'vertical'</span></code></th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><th class="stub">writing-mode <a class="footnote-reference" href="#id9" id="id8">[2]</a></th>
<td><code class="docutils literal"><span class="pre">horizontal-tb</span></code></td>
<td><code class="docutils literal"><span class="pre">vertical-rl</span></code></td>
</tr>
<tr class="row-odd"><th class="stub">page progression</th>
<td>left to right</td>
<td>right to left</td>
</tr>
<tr class="row-even"><th class="stub">iBook’s Scroll Theme support</th>
<td>scroll-axis is vertical.</td>
<td>scroll-axis is horizontal.</td>
</tr>
</tbody>
</table>
<table class="docutils footnote" frame="void" id="id9" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#id8">[2]</a></td><td><a class="reference external" href="https://developer.mozilla.org/en-US/docs/Web/CSS/writing-mode">https://developer.mozilla.org/en-US/docs/Web/CSS/writing-mode</a></td></tr>
</tbody>
</table>
</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. See further <a class="reference internal" href="latex.html"><span class="doc">LaTeX customization</span></a>.</p>
<dl class="confval">
<dt id="confval-latex_engine">
<code class="descname">latex_engine</code><a class="headerlink" href="#confval-latex_engine" title="Permalink to this definition">¶</a></dt>
<dd><p>The LaTeX engine to build the docs.  The setting can have the following
values:</p>
<ul class="simple">
<li><code class="docutils literal"><span class="pre">'pdflatex'</span></code> – PDFLaTeX (default)</li>
<li><code class="docutils literal"><span class="pre">'xelatex'</span></code> – XeLaTeX</li>
<li><code class="docutils literal"><span class="pre">'lualatex'</span></code> – LuaLaTeX</li>
<li><code class="docutils literal"><span class="pre">'platex'</span></code> – pLaTeX (default if <a class="reference internal" href="#confval-language"><code class="xref std std-confval docutils literal"><span class="pre">language</span></code></a> is <code class="docutils literal"><span class="pre">'ja'</span></code>)</li>
</ul>
<p>PDFLaTeX’s support for Unicode characters covers those from the document
language (the LaTeX <code class="docutils literal"><span class="pre">babel</span></code> and <code class="docutils literal"><span class="pre">inputenc</span></code> packages map them to glyph
slots in the document font, at various encodings allowing each only 256
characters; Sphinx uses by default (except for Cyrillic languages) the
<code class="docutils literal"><span class="pre">times</span></code> package), but stray characters from other scripts or special
symbols may require adding extra LaTeX packages or macros to the LaTeX
preamble.</p>
<p>If your project uses such extra Unicode characters, switching the engine to
XeLaTeX or LuaLaTeX often provides a quick fix. They only work with UTF-8
encoded sources and can (in fact, should) use OpenType fonts, either from
the system or the TeX install tree. Recent LaTeX releases will default with
these engines to the Latin Modern OpenType font, which has good coverage of
Latin and Cyrillic scripts (it is provided by standard LaTeX installation),
and Sphinx does not modify this default. Refer to the documentation of the
LaTeX <code class="docutils literal"><span class="pre">polyglossia</span></code> package to see how to instruct LaTeX to use some
other OpenType font if Unicode coverage proves insufficient (or use
directly <code class="docutils literal"><span class="pre">\setmainfont</span></code> et. al. as in <a class="reference internal" href="latex.html#latex-basic"><span class="std std-ref">this example</span></a>.)</p>
</dd></dl>

<dl class="confval">
<dt id="confval-latex_documents">
<code class="descname">latex_documents</code><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 <code 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></code>, 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"><code class="xref std std-confval docutils literal"><span class="pre">master_doc</span></code></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 <code class="docutils literal"><span class="pre">\\and</span></code> to separate multiple authors, as in:
<code class="docutils literal"><span class="pre">'John</span> <span class="pre">\\and</span> <span class="pre">Sarah'</span></code> (backslashes must be Python-escaped to reach LaTeX).</li>
<li><em>documentclass</em>: Normally, one of <code class="docutils literal"><span class="pre">'manual'</span></code> or <code class="docutils literal"><span class="pre">'howto'</span></code> (provided
by Sphinx and based on <code class="docutils literal"><span class="pre">'report'</span></code>, resp. <code class="docutils literal"><span class="pre">'article'</span></code>; Japanese
documents use <code class="docutils literal"><span class="pre">'jsbook'</span></code>, resp. <code class="docutils literal"><span class="pre">'jreport'</span></code>.) “howto” (non-Japanese)
documents will not get appendices. Also they have a simpler title page.
Other document classes can be given. Independently of the document class,
the “sphinx” package is always loaded in order to define Sphinx’s custom
LaTeX commands.</li>
<li><em>toctree_only</em>: Must be <code class="docutils literal"><span class="pre">True</span></code> or <code class="docutils literal"><span class="pre">False</span></code>.  If true, 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>
<div class="versionadded">
<p><span class="versionmodified">New in version 1.2: </span>In the past including your own document class required you to prepend the
document class name with the string “sphinx”. This is not necessary
anymore.</p>
</div>
<div class="versionadded">
<p><span class="versionmodified">New in version 0.3: </span>The 6th item <code class="docutils literal"><span class="pre">toctree_only</span></code>.  Tuples with 5 items are still accepted.</p>
</div>
</dd></dl>

<dl class="confval">
<dt id="confval-latex_logo">
<code class="descname">latex_logo</code><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: <code class="docutils literal"><span class="pre">None</span></code>.</p>
</dd></dl>

<dl class="confval">
<dt id="confval-latex_toplevel_sectioning">
<code class="descname">latex_toplevel_sectioning</code><a class="headerlink" href="#confval-latex_toplevel_sectioning" title="Permalink to this definition">¶</a></dt>
<dd><p>This value determines the topmost sectioning unit. It should be chosen from
<code class="docutils literal"><span class="pre">'part'</span></code>, <code class="docutils literal"><span class="pre">'chapter'</span></code> or <code class="docutils literal"><span class="pre">'section'</span></code>. The default is <code class="docutils literal"><span class="pre">None</span></code>;
the topmost
sectioning unit is switched by documentclass: <code class="docutils literal"><span class="pre">section</span></code> is used if
documentclass will be <code class="docutils literal"><span class="pre">howto</span></code>, otherwise <code class="docutils literal"><span class="pre">chapter</span></code> will be used.</p>
<p>Note that if LaTeX uses <code class="docutils literal"><span class="pre">\part</span></code> command, then the numbering of sectioning
units one level deep gets off-sync with HTML numbering, because LaTeX
numbers continuously <code class="docutils literal"><span class="pre">\chapter</span></code> (or <code class="docutils literal"><span class="pre">\section</span></code> for <code class="docutils literal"><span class="pre">howto</span></code>.)</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 1.4.</span></p>
</div>
</dd></dl>

<dl class="confval">
<dt id="confval-latex_appendices">
<code class="descname">latex_appendices</code><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">
<code class="descname">latex_domain_indices</code><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
<code class="docutils literal"><span class="pre">True</span></code>.</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"><code class="xref std std-confval docutils literal"><span class="pre">html_domain_indices</span></code></a>.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 1.0.</span></p>
</div>
</dd></dl>

<dl class="confval">
<dt id="confval-latex_show_pagerefs">
<code class="descname">latex_show_pagerefs</code><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 <code class="docutils literal"><span class="pre">False</span></code>.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 1.0.</span></p>
</div>
</dd></dl>

<dl class="confval">
<dt id="confval-latex_show_urls">
<code class="descname">latex_show_urls</code><a class="headerlink" href="#confval-latex_show_urls" title="Permalink to this definition">¶</a></dt>
<dd><p>Control whether to display URL addresses.  This is very useful for printed
copies of the manual.  The setting can have the following values:</p>
<ul class="simple">
<li><code class="docutils literal"><span class="pre">'no'</span></code> – do not display URLs (default)</li>
<li><code class="docutils literal"><span class="pre">'footnote'</span></code> – display URLs in footnotes</li>
<li><code class="docutils literal"><span class="pre">'inline'</span></code> – display URLs inline in parentheses</li>
</ul>
<div class="versionadded">
<p><span class="versionmodified">New in version 1.0.</span></p>
</div>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 1.1: </span>This value is now a string; previously it was a boolean value, and a true
value selected the <code class="docutils literal"><span class="pre">'inline'</span></code> display.  For backwards compatibility,
<code class="docutils literal"><span class="pre">True</span></code> is still accepted.</p>
</div>
</dd></dl>

<dl class="confval">
<dt id="confval-latex_keep_old_macro_names">
<code class="descname">latex_keep_old_macro_names</code><a class="headerlink" href="#confval-latex_keep_old_macro_names" title="Permalink to this definition">¶</a></dt>
<dd><p>If <code class="docutils literal"><span class="pre">True</span></code> the <code class="docutils literal"><span class="pre">\strong</span></code>, <code class="docutils literal"><span class="pre">\code</span></code>, <code class="docutils literal"><span class="pre">\bfcode</span></code>, <code class="docutils literal"><span class="pre">\email</span></code>,
<code class="docutils literal"><span class="pre">\tablecontinued</span></code>, <code class="docutils literal"><span class="pre">\titleref</span></code>, <code class="docutils literal"><span class="pre">\menuselection</span></code>, <code class="docutils literal"><span class="pre">\accelerator</span></code>,
<code class="docutils literal"><span class="pre">\crossref</span></code>, <code class="docutils literal"><span class="pre">\termref</span></code>, and <code class="docutils literal"><span class="pre">\optional</span></code> text styling macros are
pre-defined by Sphinx and may be user-customized by some
<code class="docutils literal"><span class="pre">\renewcommand</span></code>’s inserted either via <code class="docutils literal"><span class="pre">'preamble'</span></code> key or <a class="reference external" href="file:///usr/share/doc/docutils-doc/docs/ref/rst/directives.html#raw-data-pass-through">raw</a> directive. If <code class="docutils literal"><span class="pre">False</span></code>, only <code class="docutils literal"><span class="pre">\sphinxstrong</span></code>,
etc… macros are defined (and may be redefined by user).</p>
<p>The default is <code class="docutils literal"><span class="pre">False</span></code> as it prevents macro name conflicts caused by
latex packages. For example (<code class="docutils literal"><span class="pre">lualatex</span></code> or <code class="docutils literal"><span class="pre">xelatex</span></code>) <code class="docutils literal"><span class="pre">fontspec</span> <span class="pre">v2.6</span></code>
has its own <code class="docutils literal"><span class="pre">\strong</span></code> macro.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 1.4.5.</span></p>
</div>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 1.6: </span>Default was changed from <code class="docutils literal"><span class="pre">True</span></code> to <code class="docutils literal"><span class="pre">False</span></code>.</p>
</div>
<div class="deprecated">
<p><span class="versionmodified">Deprecated since version 1.6: </span>This setting will be removed at Sphinx 1.7.</p>
</div>
</dd></dl>

<dl class="confval">
<dt id="confval-latex_use_latex_multicolumn">
<code class="descname">latex_use_latex_multicolumn</code><a class="headerlink" href="#confval-latex_use_latex_multicolumn" title="Permalink to this definition">¶</a></dt>
<dd><p>The default is <code class="docutils literal"><span class="pre">False</span></code>: it means that Sphinx’s own macros are used for
merged cells from grid tables. They allow general contents (literal blocks,
lists, blockquotes, …) but may have problems if the
<a class="reference internal" href="markup/misc.html#directive-tabularcolumns" title="tabularcolumns directive"><code class="xref rst rst-dir docutils literal"><span class="pre">tabularcolumns</span></code></a> directive was used to inject LaTeX mark-up of the
type <code class="docutils literal"><span class="pre">&gt;{..}</span></code>, <code class="docutils literal"><span class="pre">&lt;{..}</span></code>, <code class="docutils literal"><span class="pre">&#64;{..}</span></code> as column specification.</p>
<p>Setting to <code class="docutils literal"><span class="pre">True</span></code> means to use LaTeX’s standard <code class="docutils literal"><span class="pre">\multicolumn</span></code>; this is
incompatible with literal blocks in the horizontally merged cell, and also
with multiple paragraphs in such cell if the table is rendered using
<code class="docutils literal"><span class="pre">tabulary</span></code>.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 1.6.</span></p>
</div>
</dd></dl>

<dl class="confval">
<dt id="confval-latex_elements">
<code class="descname">latex_elements</code><a class="headerlink" href="#confval-latex_elements" title="Permalink to this definition">¶</a></dt>
<dd><div class="versionadded">
<p><span class="versionmodified">New in version 0.5.</span></p>
</div>
<p>A dictionary that contains LaTeX snippets that override those Sphinx usually
puts into the generated <code class="docutils literal"><span class="pre">.tex</span></code> 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><code class="docutils literal"><span class="pre">'papersize'</span></code></dt>
<dd><p class="first last">Paper size option of the document class (<code class="docutils literal"><span class="pre">'a4paper'</span></code> or
<code class="docutils literal"><span class="pre">'letterpaper'</span></code>), default <code class="docutils literal"><span class="pre">'letterpaper'</span></code>.</p>
</dd>
<dt><code class="docutils literal"><span class="pre">'pointsize'</span></code></dt>
<dd><p class="first last">Point size option of the document class (<code class="docutils literal"><span class="pre">'10pt'</span></code>, <code class="docutils literal"><span class="pre">'11pt'</span></code> or
<code class="docutils literal"><span class="pre">'12pt'</span></code>), default <code class="docutils literal"><span class="pre">'10pt'</span></code>.</p>
</dd>
<dt><code class="docutils literal"><span class="pre">'pxunit'</span></code></dt>
<dd><p class="first">the value of the <code class="docutils literal"><span class="pre">px</span></code> when used in image attributes <code class="docutils literal"><span class="pre">width</span></code> and
<code class="docutils literal"><span class="pre">height</span></code>. The default value is <code class="docutils literal"><span class="pre">'0.75bp'</span></code> which achieves
<code class="docutils literal"><span class="pre">96px=1in</span></code> (in TeX <code class="docutils literal"><span class="pre">1in</span> <span class="pre">=</span> <span class="pre">72bp</span> <span class="pre">=</span> <span class="pre">72.27pt</span></code>.) To obtain for
example <code class="docutils literal"><span class="pre">100px=1in</span></code> use <code class="docutils literal"><span class="pre">'0.01in'</span></code> or <code class="docutils literal"><span class="pre">'0.7227pt'</span></code> (the latter
leads to TeX computing a more precise value, due to the smaller unit
used in the specification); for <code class="docutils literal"><span class="pre">72px=1in</span></code>,
simply use <code class="docutils literal"><span class="pre">'1bp'</span></code>; for <code class="docutils literal"><span class="pre">90px=1in</span></code>, use <code class="docutils literal"><span class="pre">'0.8bp'</span></code> or <code class="docutils literal"><span class="pre">'0.803pt'</span></code>.</p>
<div class="last versionadded">
<p><span class="versionmodified">New in version 1.5.</span></p>
</div>
</dd>
<dt><code class="docutils literal"><span class="pre">'sphinxsetup'</span></code></dt>
<dd><p class="first">A comma separated list of <code class="docutils literal"><span class="pre">key=value</span></code> package options for the Sphinx
LaTeX style, default empty. See <a class="reference internal" href="latex.html"><span class="doc">LaTeX customization</span></a>.</p>
<div class="last versionadded">
<p><span class="versionmodified">New in version 1.5.</span></p>
</div>
</dd>
<dt><code class="docutils literal"><span class="pre">'passoptionstopackages'</span></code></dt>
<dd><p class="first">A string which will be positioned early in the preamble, designed to
contain <code class="docutils literal"><span class="pre">\\PassOptionsToPackage{options}{foo}</span></code> commands. Default empty.</p>
<div class="last versionadded">
<p><span class="versionmodified">New in version 1.4.</span></p>
</div>
</dd>
<dt><code class="docutils literal"><span class="pre">'babel'</span></code></dt>
<dd><p class="first">“babel” package inclusion, default <code class="docutils literal"><span class="pre">'\\usepackage{babel}'</span></code> (the
suitable document language string is passed as class option, and
<code class="docutils literal"><span class="pre">english</span></code> is used if no language.) For Japanese documents, the
default is the empty string.</p>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 1.5: </span>For <a class="reference internal" href="#confval-latex_engine"><code class="xref std std-confval docutils literal"><span class="pre">latex_engine</span></code></a> set to <code class="docutils literal"><span class="pre">'xelatex'</span></code>, the default
is <code class="docutils literal"><span class="pre">'\\usepackage{polyglossia}\n\\setmainlanguage{&lt;language&gt;}'</span></code>.</p>
</div>
<div class="last versionchanged">
<p><span class="versionmodified">Changed in version 1.6: </span><code class="docutils literal"><span class="pre">'lualatex'</span></code> uses same default setting as <code class="docutils literal"><span class="pre">'xelatex'</span></code></p>
</div>
</dd>
<dt><code class="docutils literal"><span class="pre">'fontpkg'</span></code></dt>
<dd><p class="first">Font package inclusion, default <code class="docutils literal"><span class="pre">'\\usepackage{times}'</span></code> (which uses
Times and Helvetica).  You can set this to <code class="docutils literal"><span class="pre">''</span></code> to use the Computer
Modern fonts.</p>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 1.2: </span>Defaults to <code class="docutils literal"><span class="pre">''</span></code> when the <a class="reference internal" href="#confval-language"><code class="xref std std-confval docutils literal"><span class="pre">language</span></code></a> uses the Cyrillic
script.</p>
</div>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 1.5: </span>Defaults to <code class="docutils literal"><span class="pre">''</span></code> when <a class="reference internal" href="#confval-latex_engine"><code class="xref std std-confval docutils literal"><span class="pre">latex_engine</span></code></a> is <code class="docutils literal"><span class="pre">'xelatex'</span></code>.</p>
</div>
<div class="last versionchanged">
<p><span class="versionmodified">Changed in version 1.6: </span>Defaults to <code class="docutils literal"><span class="pre">''</span></code> also with <code class="docutils literal"><span class="pre">'lualatex'</span></code>.</p>
</div>
</dd>
<dt><code class="docutils literal"><span class="pre">'fncychap'</span></code></dt>
<dd><p class="first last">Inclusion of the “fncychap” package (which makes fancy chapter titles),
default <code class="docutils literal"><span class="pre">'\\usepackage[Bjarne]{fncychap}'</span></code> for English documentation
(this option is slightly customized by Sphinx),
<code class="docutils literal"><span class="pre">'\\usepackage[Sonny]{fncychap}'</span></code> for internationalized docs (because
the “Bjarne” style uses numbers spelled out in English).  Other
“fncychap” styles you can try are “Lenny”, “Glenn”, “Conny”, “Rejne” and
“Bjornstrup”.  You can also set this to <code class="docutils literal"><span class="pre">''</span></code> to disable fncychap.</p>
</dd>
<dt><code class="docutils literal"><span class="pre">'preamble'</span></code></dt>
<dd><p class="first last">Additional preamble content, default empty. See <a class="reference internal" href="latex.html"><span class="doc">LaTeX customization</span></a>.</p>
</dd>
<dt><code class="docutils literal"><span class="pre">'atendofbody'</span></code></dt>
<dd><p class="first">Additional document content (right before the indices), default empty.</p>
<div class="last versionadded">
<p><span class="versionmodified">New in version 1.5.</span></p>
</div>
</dd>
<dt><code class="docutils literal"><span class="pre">'figure_align'</span></code></dt>
<dd><p class="first">Latex figure float alignment, default ‘htbp’ (here, top, bottom, page).
Whenever an image doesn’t fit into the current page, it will be
‘floated’ into the next page but may be preceded by any other text.
If you don’t like this behavior, use ‘H’ which will disable floating
and position figures strictly in the order they appear in the source.</p>
<div class="last versionadded">
<p><span class="versionmodified">New in version 1.3.</span></p>
</div>
</dd>
<dt><code class="docutils literal"><span class="pre">'footer'</span></code></dt>
<dd><p class="first">Additional footer content (before the indices), default empty.</p>
<div class="last deprecated">
<p><span class="versionmodified">Deprecated since version 1.5: </span>Use <code class="docutils literal"><span class="pre">'atendofbody'</span></code> key instead.</p>
</div>
</dd>
</dl>
</li>
<li><p class="first">Keys that don’t need to be overridden unless in special cases are:</p>
<dl class="docutils">
<dt><code class="docutils literal"><span class="pre">'extraclassoptions'</span></code></dt>
<dd><p class="first">The default is the empty string. Example: <code class="docutils literal"><span class="pre">'extraclassoptions':</span>
<span class="pre">'openany'</span></code> will allow chapters (for documents of the <code class="docutils literal"><span class="pre">'manual'</span></code>
type) to start on any page.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 1.2.</span></p>
</div>
<div class="last versionchanged">
<p><span class="versionmodified">Changed in version 1.6: </span>Added this documentation.</p>
</div>
</dd>
<dt><code class="docutils literal"><span class="pre">'maxlistdepth'</span></code></dt>
<dd><p class="first">LaTeX allows by default at most 6 levels for nesting list and
quote-like environments, with at most 4 enumerated lists, and 4 bullet
lists. Setting this key for example to <code class="docutils literal"><span class="pre">'10'</span></code> (as a string) will
allow up to 10 nested levels (of all sorts). Leaving it to the empty
string means to obey the LaTeX default.</p>
<div class="admonition warning">
<p class="first admonition-title">Warning</p>
<ul class="last simple">
<li>Using this key may prove incompatible with some LaTeX packages
or special document classes which do their own list customization.</li>
<li>The key setting is silently <em>ignored</em> if <code class="docutils literal"><span class="pre">\usepackage{enumitem}</span></code>
is executed inside the document preamble. Use then rather the
dedicated commands of this LaTeX package.</li>
</ul>
</div>
<div class="last versionadded">
<p><span class="versionmodified">New in version 1.5.</span></p>
</div>
</dd>
<dt><code class="docutils literal"><span class="pre">'inputenc'</span></code></dt>
<dd><p class="first">“inputenc” package inclusion, defaults to
<code class="docutils literal"><span class="pre">'\\usepackage[utf8]{inputenc}'</span></code> when using pdflatex.
Otherwise empty.</p>
<div class="last versionchanged">
<p><span class="versionmodified">Changed in version 1.4.3: </span>Previously <code class="docutils literal"><span class="pre">'\\usepackage[utf8]{inputenc}'</span></code> was used for all
compilers.</p>
</div>
</dd>
<dt><code class="docutils literal"><span class="pre">'cmappkg'</span></code></dt>
<dd><p class="first">“cmap” package inclusion, default <code class="docutils literal"><span class="pre">'\\usepackage{cmap}'</span></code>.</p>
<div class="last versionadded">
<p><span class="versionmodified">New in version 1.2.</span></p>
</div>
</dd>
<dt><code class="docutils literal"><span class="pre">'fontenc'</span></code></dt>
<dd><p class="first">“fontenc” package inclusion, default <code class="docutils literal"><span class="pre">'\\usepackage[T1]{fontenc}'</span></code>.</p>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 1.5: </span>Defaults to <code class="docutils literal"><span class="pre">'\\usepackage{fontspec}'</span></code> when
<a class="reference internal" href="#confval-latex_engine"><code class="xref std std-confval docutils literal"><span class="pre">latex_engine</span></code></a> is <code class="docutils literal"><span class="pre">'xelatex'</span></code>.</p>
</div>
<div class="last versionchanged">
<p><span class="versionmodified">Changed in version 1.6: </span><code class="docutils literal"><span class="pre">'lualatex'</span></code> also uses <code class="docutils literal"><span class="pre">fontspec</span></code> per default.</p>
</div>
</dd>
<dt><code class="docutils literal"><span class="pre">'geometry'</span></code></dt>
<dd><p class="first">“geometry” package inclusion, the default definition is:</p>
<blockquote>
<div><p><code class="docutils literal"><span class="pre">'\\usepackage{geometry}'</span></code></p>
</div></blockquote>
<p>with an additional <code class="docutils literal"><span class="pre">[dvipdfm]</span></code> for Japanese documents.
The Sphinx LaTeX style file executes:</p>
<blockquote>
<div><p><code class="docutils literal"><span class="pre">\PassOptionsToPackage{hmargin=1in,vmargin=1in,marginpar=0.5in}{geometry}</span></code></p>
</div></blockquote>
<p>which can be customized via corresponding <a class="reference internal" href="latex.html#latexsphinxsetup"><span class="std std-ref">‘sphinxsetup’ options</span></a>.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 1.5.</span></p>
</div>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 1.5.2: </span><code class="docutils literal"><span class="pre">dvipdfm</span></code> option if <a class="reference internal" href="#confval-latex_engine"><code class="xref std std-confval docutils literal"><span class="pre">latex_engine</span></code></a> is <code class="docutils literal"><span class="pre">'platex'</span></code>.</p>
</div>
<div class="versionadded">
<p><span class="versionmodified">New in version 1.5.3: </span>The <a class="reference internal" href="latex.html#latexsphinxsetuphmargin"><span class="std std-ref">‘sphinxsetup’ keys for the margins</span></a>.</p>
</div>
<div class="last versionchanged">
<p><span class="versionmodified">Changed in version 1.5.3: </span>The location in the LaTeX file has been moved to after
<code class="docutils literal"><span class="pre">\usepackage{sphinx}</span></code> and <code class="docutils literal"><span class="pre">\sphinxsetup{..}</span></code>, hence also after
insertion of <code class="docutils literal"><span class="pre">'fontpkg'</span></code> key. This is in order to handle the paper
layout options in a special way for Japanese documents: the text
width will be set to an integer multiple of the <em>zenkaku</em> width, and
the text height to an integer multiple of the baseline. See the
<a class="reference internal" href="latex.html#latexsphinxsetuphmargin"><span class="std std-ref">hmargin</span></a> documentation for more.</p>
</div>
</dd>
<dt><code class="docutils literal"><span class="pre">'hyperref'</span></code></dt>
<dd><p class="first">“hyperref” package inclusion; also loads package “hypcap” and issues
<code class="docutils literal"><span class="pre">\urlstyle{same}</span></code>. This is done after <code class="file docutils literal"><span class="pre">sphinx.sty</span></code> file is
loaded and before executing the contents of <code class="docutils literal"><span class="pre">'preamble'</span></code> key.</p>
<div class="admonition attention">
<p class="first admonition-title">Attention</p>
<p class="last">Loading of packages “hyperref” and “hypcap” is mandatory.</p>
</div>
<div class="last versionadded">
<p><span class="versionmodified">New in version 1.5: </span>Previously this was done from inside <code class="file docutils literal"><span class="pre">sphinx.sty</span></code>.</p>
</div>
</dd>
<dt><code class="docutils literal"><span class="pre">'maketitle'</span></code></dt>
<dd><p class="first last">“maketitle” call, default <code class="docutils literal"><span class="pre">'\\maketitle'</span></code> (but it has been
redefined by the Sphinx <code class="docutils literal"><span class="pre">manual</span></code> and <code class="docutils literal"><span class="pre">howto</span></code> classes.) Override
if you want to
generate a differently-styled title page.</p>
</dd>
<dt><code class="docutils literal"><span class="pre">'releasename'</span></code></dt>
<dd><p class="first last">value that prefixes <code class="docutils literal"><span class="pre">'release'</span></code> element on title page, default
<code class="docutils literal"><span class="pre">'Release'</span></code>. As for <em>title</em> and <em>author</em> used in the tuples of
<a class="reference internal" href="#confval-latex_documents"><code class="xref std std-confval docutils literal"><span class="pre">latex_documents</span></code></a>, it is inserted as LaTeX markup.</p>
</dd>
<dt><code class="docutils literal"><span class="pre">'tableofcontents'</span></code></dt>
<dd><p class="first">“tableofcontents” call, default <code class="docutils literal"><span class="pre">'\\sphinxtableofcontents'</span></code> (it is a
wrapper of unmodified <code class="docutils literal"><span class="pre">\tableofcontents</span></code>, which may itself be
customized by user loaded packages.)
Override if
you want to generate a different table of contents or put content
between the title page and the TOC.</p>
<div class="last versionchanged">
<p><span class="versionmodified">Changed in version 1.5: </span>Previously the meaning of <code class="docutils literal"><span class="pre">\tableofcontents</span></code> itself was modified
by Sphinx. This created an incompatibility with dedicated packages
modifying it also such as “tocloft” or “etoc”.</p>
</div>
</dd>
<dt><code class="docutils literal"><span class="pre">'transition'</span></code></dt>
<dd><p class="first">Commands used to display transitions, default
<code class="docutils literal"><span class="pre">'\n\n\\bigskip\\hrule\\bigskip\n\n'</span></code>.  Override if you want to
display transitions differently.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 1.2.</span></p>
</div>
<div class="last versionchanged">
<p><span class="versionmodified">Changed in version 1.6: </span>Remove unneeded <code class="docutils literal"><span class="pre">{}</span></code> after <code class="docutils literal"><span class="pre">\\hrule</span></code>.</p>
</div>
</dd>
<dt><code class="docutils literal"><span class="pre">'printindex'</span></code></dt>
<dd><p class="first last">“printindex” call, the last thing in the file, default
<code class="docutils literal"><span class="pre">'\\printindex'</span></code>.  Override if you want to generate the index
differently or append some content after the index. For example
<code class="docutils literal"><span class="pre">'\\footnotesize\\raggedright\\printindex'</span></code> is advisable when the
index is full of long entries.</p>
</dd>
</dl>
</li>
<li><p class="first">Keys that are set by other options and therefore should not be overridden
are:</p>
<p><code class="docutils literal"><span class="pre">'docclass'</span></code>
<code class="docutils literal"><span class="pre">'classoptions'</span></code>
<code class="docutils literal"><span class="pre">'title'</span></code>
<code class="docutils literal"><span class="pre">'date'</span></code>
<code class="docutils literal"><span class="pre">'release'</span></code>
<code class="docutils literal"><span class="pre">'author'</span></code>
<code class="docutils literal"><span class="pre">'logo'</span></code>
<code class="docutils literal"><span class="pre">'makeindex'</span></code>
<code class="docutils literal"><span class="pre">'shorthandoff'</span></code></p>
</li>
</ul>
</dd></dl>

<dl class="confval">
<dt id="confval-latex_docclass">
<code class="descname">latex_docclass</code><a class="headerlink" href="#confval-latex_docclass" title="Permalink to this definition">¶</a></dt>
<dd><p>A dictionary mapping <code class="docutils literal"><span class="pre">'howto'</span></code> and <code class="docutils literal"><span class="pre">'manual'</span></code> to names of real document
classes that will be used as the base for the two Sphinx classes.  Default
is to use <code class="docutils literal"><span class="pre">'article'</span></code> for <code class="docutils literal"><span class="pre">'howto'</span></code> and <code class="docutils literal"><span class="pre">'report'</span></code> for <code class="docutils literal"><span class="pre">'manual'</span></code>.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 1.0.</span></p>
</div>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 1.5: </span>In Japanese docs (<a class="reference internal" href="#confval-language"><code class="xref std std-confval docutils literal"><span class="pre">language</span></code></a> is <code class="docutils literal"><span class="pre">'ja'</span></code>), by default
<code class="docutils literal"><span class="pre">'jreport'</span></code> is used for <code class="docutils literal"><span class="pre">'howto'</span></code> and <code class="docutils literal"><span class="pre">'jsbook'</span></code> for <code class="docutils literal"><span class="pre">'manual'</span></code>.</p>
</div>
</dd></dl>

<dl class="confval">
<dt id="confval-latex_additional_files">
<code class="descname">latex_additional_files</code><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 <code class="docutils literal"><span class="pre">latex_elements</span></code>.  Image files that are referenced in source
files (e.g. via <code class="docutils literal"><span class="pre">..</span> <span class="pre">image::</span></code>) 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>
<div class="versionadded">
<p><span class="versionmodified">New in version 0.6.</span></p>
</div>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 1.2: </span>This overrides the files which is provided from Sphinx such as sphinx.sty.</p>
</div>
</dd></dl>

</div>
<div class="section" id="options-for-text-output">
<span id="text-options"></span><h2>Options for text output<a class="headerlink" href="#options-for-text-output" title="Permalink to this headline">¶</a></h2>
<p>These options influence text output.</p>
<dl class="confval">
<dt id="confval-text_newlines">
<code class="descname">text_newlines</code><a class="headerlink" href="#confval-text_newlines" title="Permalink to this definition">¶</a></dt>
<dd><p>Determines which end-of-line character(s) are used in text output.</p>
<ul class="simple">
<li><code class="docutils literal"><span class="pre">'unix'</span></code>: use Unix-style line endings (<code class="docutils literal"><span class="pre">\n</span></code>)</li>
<li><code class="docutils literal"><span class="pre">'windows'</span></code>: use Windows-style line endings (<code class="docutils literal"><span class="pre">\r\n</span></code>)</li>
<li><code class="docutils literal"><span class="pre">'native'</span></code>: use the line ending style of the platform the documentation
is built on</li>
</ul>
<p>Default: <code class="docutils literal"><span class="pre">'unix'</span></code>.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 1.1.</span></p>
</div>
</dd></dl>

<dl class="confval">
<dt id="confval-text_sectionchars">
<code class="descname">text_sectionchars</code><a class="headerlink" href="#confval-text_sectionchars" title="Permalink to this definition">¶</a></dt>
<dd><p>A string of 7 characters that should be used for underlining sections.
The first character is used for first-level headings, the second for
second-level headings and so on.</p>
<p>The default is <code class="docutils literal"><span class="pre">'*=-~&quot;+`'</span></code>.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 1.1.</span></p>
</div>
</dd></dl>

<dl class="confval">
<dt id="confval-text_add_secnumbers">
<code class="descname">text_add_secnumbers</code><a class="headerlink" href="#confval-text_add_secnumbers" title="Permalink to this definition">¶</a></dt>
<dd><p>A boolean that decides whether section numbers are included in text output.
Default is <code class="docutils literal"><span class="pre">False</span></code>.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 1.7.</span></p>
</div>
</dd></dl>

<dl class="confval">
<dt id="confval-text_secnumber_suffix">
<code class="descname">text_secnumber_suffix</code><a class="headerlink" href="#confval-text_secnumber_suffix" title="Permalink to this definition">¶</a></dt>
<dd><p>Suffix for section numbers in text output.  Default: <code class="docutils literal"><span class="pre">&quot;.</span> <span class="pre">&quot;</span></code>. Set to <code class="docutils literal"><span class="pre">&quot;</span> <span class="pre">&quot;</span></code>
to suppress the final dot on section numbers.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 1.7.</span></p>
</div>
</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">
<code class="descname">man_pages</code><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 <code 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></code>, 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"><code class="xref std std-confval docutils literal"><span class="pre">master_doc</span></code></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>
<div class="versionadded">
<p><span class="versionmodified">New in version 1.0.</span></p>
</div>
</dd></dl>

<dl class="confval">
<dt id="confval-man_show_urls">
<code class="descname">man_show_urls</code><a class="headerlink" href="#confval-man_show_urls" title="Permalink to this definition">¶</a></dt>
<dd><p>If true, add URL addresses after links.  Default is <code class="docutils literal"><span class="pre">False</span></code>.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 1.1.</span></p>
</div>
</dd></dl>

</div>
<div class="section" id="options-for-texinfo-output">
<span id="texinfo-options"></span><h2>Options for Texinfo output<a class="headerlink" href="#options-for-texinfo-output" title="Permalink to this headline">¶</a></h2>
<p>These options influence Texinfo output.</p>
<dl class="confval">
<dt id="confval-texinfo_documents">
<code class="descname">texinfo_documents</code><a class="headerlink" href="#confval-texinfo_documents" title="Permalink to this definition">¶</a></dt>
<dd><p>This value determines how to group the document tree into Texinfo source
files.  It must be a list of tuples <code 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">dir_entry,</span> <span class="pre">description,</span> <span class="pre">category,</span> <span class="pre">toctree_only)</span></code>, where the items
are:</p>
<ul class="simple">
<li><em>startdocname</em>: document name that is the “root” of the Texinfo file.  All
documents referenced by it in TOC trees will be included in the Texinfo
file too.  (If you want only one Texinfo file, use your
<a class="reference internal" href="#confval-master_doc"><code class="xref std std-confval docutils literal"><span class="pre">master_doc</span></code></a> here.)</li>
<li><em>targetname</em>: file name (no extension) of the Texinfo file in the output
directory.</li>
<li><em>title</em>: Texinfo document title.  Can be empty to use the title of the
<em>startdoc</em>.  Inserted as Texinfo markup, so special characters like &#64; and
{} will need to be escaped to be inserted literally.</li>
<li><em>author</em>: Author for the Texinfo document.  Inserted as Texinfo markup.
Use <code class="docutils literal"><span class="pre">&#64;*</span></code> to separate multiple authors, as in: <code class="docutils literal"><span class="pre">'John&#64;*Sarah'</span></code>.</li>
<li><em>dir_entry</em>: The name that will appear in the top-level <code class="docutils literal"><span class="pre">DIR</span></code> menu file.</li>
<li><em>description</em>: Descriptive text to appear in the top-level <code class="docutils literal"><span class="pre">DIR</span></code> menu
file.</li>
<li><em>category</em>: Specifies the section which this entry will appear in the
top-level <code class="docutils literal"><span class="pre">DIR</span></code> menu file.</li>
<li><em>toctree_only</em>: Must be <code class="docutils literal"><span class="pre">True</span></code> or <code class="docutils literal"><span class="pre">False</span></code>.  If true, 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 Texinfo
output.</li>
</ul>
<div class="versionadded">
<p><span class="versionmodified">New in version 1.1.</span></p>
</div>
</dd></dl>

<dl class="confval">
<dt id="confval-texinfo_appendices">
<code class="descname">texinfo_appendices</code><a class="headerlink" href="#confval-texinfo_appendices" title="Permalink to this definition">¶</a></dt>
<dd><p>A list of document names to append as an appendix to all manuals.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 1.1.</span></p>
</div>
</dd></dl>

<dl class="confval">
<dt id="confval-texinfo_domain_indices">
<code class="descname">texinfo_domain_indices</code><a class="headerlink" href="#confval-texinfo_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
<code class="docutils literal"><span class="pre">True</span></code>.</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"><code class="xref std std-confval docutils literal"><span class="pre">html_domain_indices</span></code></a>.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 1.1.</span></p>
</div>
</dd></dl>

<dl class="confval">
<dt id="confval-texinfo_show_urls">
<code class="descname">texinfo_show_urls</code><a class="headerlink" href="#confval-texinfo_show_urls" title="Permalink to this definition">¶</a></dt>
<dd><p>Control how to display URL addresses.</p>
<ul class="simple">
<li><code class="docutils literal"><span class="pre">'footnote'</span></code> – display URLs in footnotes (default)</li>
<li><code class="docutils literal"><span class="pre">'no'</span></code> – do not display URLs</li>
<li><code class="docutils literal"><span class="pre">'inline'</span></code> – display URLs inline in parentheses</li>
</ul>
<div class="versionadded">
<p><span class="versionmodified">New in version 1.1.</span></p>
</div>
</dd></dl>

<dl class="confval">
<dt id="confval-texinfo_no_detailmenu">
<code class="descname">texinfo_no_detailmenu</code><a class="headerlink" href="#confval-texinfo_no_detailmenu" title="Permalink to this definition">¶</a></dt>
<dd><p>If true, do not generate a <code class="docutils literal"><span class="pre">&#64;detailmenu</span></code> in the “Top” node’s menu
containing entries for each sub-node in the document.  Default is <code class="docutils literal"><span class="pre">False</span></code>.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 1.2.</span></p>
</div>
</dd></dl>

<dl class="confval">
<dt id="confval-texinfo_elements">
<code class="descname">texinfo_elements</code><a class="headerlink" href="#confval-texinfo_elements" title="Permalink to this definition">¶</a></dt>
<dd><p>A dictionary that contains Texinfo snippets that override those Sphinx
usually puts into the generated <code class="docutils literal"><span class="pre">.texi</span></code> files.</p>
<ul>
<li><p class="first">Keys that you may want to override include:</p>
<dl class="docutils">
<dt><code class="docutils literal"><span class="pre">'paragraphindent'</span></code></dt>
<dd><p class="first last">Number of spaces to indent the first line of each paragraph, default
<code class="docutils literal"><span class="pre">2</span></code>.  Specify <code class="docutils literal"><span class="pre">0</span></code> for no indentation.</p>
</dd>
<dt><code class="docutils literal"><span class="pre">'exampleindent'</span></code></dt>
<dd><p class="first last">Number of spaces to indent the lines for examples or literal blocks,
default <code class="docutils literal"><span class="pre">4</span></code>.  Specify <code class="docutils literal"><span class="pre">0</span></code> for no indentation.</p>
</dd>
<dt><code class="docutils literal"><span class="pre">'preamble'</span></code></dt>
<dd><p class="first last">Texinfo markup inserted near the beginning of the file.</p>
</dd>
<dt><code class="docutils literal"><span class="pre">'copying'</span></code></dt>
<dd><p class="first last">Texinfo markup inserted within the <code class="docutils literal"><span class="pre">&#64;copying</span></code> block and displayed
after the title.  The default value consists of a simple title page
identifying the project.</p>
</dd>
</dl>
</li>
<li><p class="first">Keys that are set by other options and therefore should not be overridden
are:</p>
<p><code class="docutils literal"><span class="pre">'author'</span></code>
<code class="docutils literal"><span class="pre">'body'</span></code>
<code class="docutils literal"><span class="pre">'date'</span></code>
<code class="docutils literal"><span class="pre">'direntry'</span></code>
<code class="docutils literal"><span class="pre">'filename'</span></code>
<code class="docutils literal"><span class="pre">'project'</span></code>
<code class="docutils literal"><span class="pre">'release'</span></code>
<code class="docutils literal"><span class="pre">'title'</span></code></p>
</li>
</ul>
<div class="versionadded">
<p><span class="versionmodified">New in version 1.1.</span></p>
</div>
</dd></dl>

</div>
<div class="section" id="options-for-the-linkcheck-builder">
<h2>Options for the linkcheck builder<a class="headerlink" href="#options-for-the-linkcheck-builder" title="Permalink to this headline">¶</a></h2>
<dl class="confval">
<dt id="confval-linkcheck_ignore">
<code class="descname">linkcheck_ignore</code><a class="headerlink" href="#confval-linkcheck_ignore" title="Permalink to this definition">¶</a></dt>
<dd><p>A list of regular expressions that match URIs that should not be checked
when doing a <code class="docutils literal"><span class="pre">linkcheck</span></code> build.  Example:</p>
<div class="highlight-python"><div class="highlight"><pre><span></span><span class="n">linkcheck_ignore</span> <span class="o">=</span> <span class="p">[</span><span class="sa">r</span><span class="s1">&#39;http://localhost:\d+/&#39;</span><span class="p">]</span>
</pre></div>
</div>
<div class="versionadded">
<p><span class="versionmodified">New in version 1.1.</span></p>
</div>
</dd></dl>

<dl class="confval">
<dt id="confval-linkcheck_retries">
<code class="descname">linkcheck_retries</code><a class="headerlink" href="#confval-linkcheck_retries" title="Permalink to this definition">¶</a></dt>
<dd><p>The number of times the linkcheck builder will attempt to check a URL before
declaring it broken. Defaults to 1 attempt.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 1.4.</span></p>
</div>
</dd></dl>

<dl class="confval">
<dt id="confval-linkcheck_timeout">
<code class="descname">linkcheck_timeout</code><a class="headerlink" href="#confval-linkcheck_timeout" title="Permalink to this definition">¶</a></dt>
<dd><p>A timeout value, in seconds, for the linkcheck builder.  The default is to
use Python’s global socket timeout.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 1.1.</span></p>
</div>
</dd></dl>

<dl class="confval">
<dt id="confval-linkcheck_workers">
<code class="descname">linkcheck_workers</code><a class="headerlink" href="#confval-linkcheck_workers" title="Permalink to this definition">¶</a></dt>
<dd><p>The number of worker threads to use when checking links.  Default is 5
threads.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 1.1.</span></p>
</div>
</dd></dl>

<dl class="confval">
<dt id="confval-linkcheck_anchors">
<code class="descname">linkcheck_anchors</code><a class="headerlink" href="#confval-linkcheck_anchors" title="Permalink to this definition">¶</a></dt>
<dd><p>If true, check the validity of <code class="docutils literal"><span class="pre">#anchor</span></code>s in links. Since this requires
downloading the whole document, it’s considerably slower when enabled.
Default is <code class="docutils literal"><span class="pre">True</span></code>.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 1.2.</span></p>
</div>
</dd></dl>

<dl class="confval">
<dt id="confval-linkcheck_anchors_ignore">
<code class="descname">linkcheck_anchors_ignore</code><a class="headerlink" href="#confval-linkcheck_anchors_ignore" title="Permalink to this definition">¶</a></dt>
<dd><p>A list of regular expressions that match URIs that should skip checking
the validity of anchors in links. This allows skipping entire sites, where
anchors are used to control dynamic pages, or just specific anchors within
a page, where javascript is used to add anchors dynamically, or use the
fragment as part of to trigger an internal REST request. Default is
<code class="docutils literal"><span class="pre">[&quot;/#!&quot;]</span></code>.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 1.5.</span></p>
</div>
</dd></dl>

</div>
<div class="section" id="options-for-the-xml-builder">
<h2>Options for the XML builder<a class="headerlink" href="#options-for-the-xml-builder" title="Permalink to this headline">¶</a></h2>
<dl class="confval">
<dt id="confval-xml_pretty">
<code class="descname">xml_pretty</code><a class="headerlink" href="#confval-xml_pretty" title="Permalink to this definition">¶</a></dt>
<dd><p>If true, pretty-print the XML.  Default is <code class="docutils literal"><span class="pre">True</span></code>.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 1.2.</span></p>
</div>
</dd></dl>

<p class="rubric">Footnotes</p>
<table class="docutils footnote" frame="void" id="id10" 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="#id7">2</a>)</em> A note on available globbing syntax: you can use the standard shell
constructs <code class="docutils literal"><span class="pre">*</span></code>, <code class="docutils literal"><span class="pre">?</span></code>, <code class="docutils literal"><span class="pre">[...]</span></code> and <code class="docutils literal"><span class="pre">[!...]</span></code> with the feature that
these all don’t match slashes.  A double star <code class="docutils literal"><span class="pre">**</span></code> can be used to match
any sequence of characters <em>including</em> slashes.</td></tr>
</tbody>
</table>
</div>
<div class="section" id="options-for-the-c-domain">
<span id="cpp-config"></span><h2>Options for the C++ domain<a class="headerlink" href="#options-for-the-c-domain" title="Permalink to this headline">¶</a></h2>
<dl class="confval">
<dt id="confval-cpp_index_common_prefix">
<code class="descname">cpp_index_common_prefix</code><a class="headerlink" href="#confval-cpp_index_common_prefix" title="Permalink to this definition">¶</a></dt>
<dd><p>A list of prefixes that will be ignored when sorting C++ objects in the global index.
For example <code class="docutils literal"><span class="pre">['awesome_lib::']</span></code>.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 1.5.</span></p>
</div>
</dd></dl>

<dl class="confval">
<dt id="confval-cpp_id_attributes">
<code class="descname">cpp_id_attributes</code><a class="headerlink" href="#confval-cpp_id_attributes" title="Permalink to this definition">¶</a></dt>
<dd><p>A list of strings that the parser additionally should accept as attributes.
This can for example be used when attributes have been <code class="docutils literal"><span class="pre">#define</span></code> d for portability.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 1.5.</span></p>
</div>
</dd></dl>

<dl class="confval">
<dt id="confval-cpp_paren_attributes">
<code class="descname">cpp_paren_attributes</code><a class="headerlink" href="#confval-cpp_paren_attributes" title="Permalink to this definition">¶</a></dt>
<dd><p>A list of strings that the parser additionally should accept as attributes with one argument.
That is, if <code class="docutils literal"><span class="pre">my_align_as</span></code> is in the list, then <code class="docutils literal"><span class="pre">my_align_as(X)</span></code> is parsed as an attribute
for all strings <code class="docutils literal"><span class="pre">X</span></code> that have balanced brances (<code class="docutils literal"><span class="pre">()</span></code>, <code class="docutils literal"><span class="pre">[]</span></code>, and <code class="docutils literal"><span class="pre">{}</span></code>).
This can for example be used when attributes have been <code class="docutils literal"><span class="pre">#define</span></code> d for portability.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 1.5.</span></p>
</div>
</dd></dl>

</div>
</div>
<div class="section" id="example-of-configuration-file">
<h1>Example of configuration file<a class="headerlink" href="#example-of-configuration-file" title="Permalink to this headline">¶</a></h1>
<div class="highlight-python"><div class="highlight"><pre><span></span><span class="c1"># -*- coding: utf-8 -*-</span>
<span class="c1">#</span>
<span class="c1"># test documentation build configuration file, created by</span>
<span class="c1"># sphinx-quickstart on Sun Jun 26 00:00:43 2016.</span>
<span class="c1">#</span>
<span class="c1"># This file is execfile()d with the current directory set to its</span>
<span class="c1"># containing dir.</span>
<span class="c1">#</span>
<span class="c1"># Note that not all possible configuration values are present in this</span>
<span class="c1"># autogenerated file.</span>
<span class="c1">#</span>
<span class="c1"># All configuration values have a default; values that are commented out</span>
<span class="c1"># serve to show the default.</span>

<span class="c1"># If extensions (or modules to document with autodoc) are in another directory,</span>
<span class="c1"># add these directories to sys.path here. If the directory is relative to the</span>
<span class="c1"># documentation root, use os.path.abspath to make it absolute, like shown here.</span>
<span class="c1">#</span>
<span class="c1"># import os</span>
<span class="c1"># import sys</span>
<span class="c1"># sys.path.insert(0, os.path.abspath(&#39;.&#39;))</span>

<span class="c1"># -- General configuration ------------------------------------------------</span>

<span class="c1"># If your documentation needs a minimal Sphinx version, state it here.</span>
<span class="c1">#</span>
<span class="c1"># needs_sphinx = &#39;1.0&#39;</span>

<span class="c1"># Add any Sphinx extension module names here, as strings. They can be</span>
<span class="c1"># extensions coming with Sphinx (named &#39;sphinx.ext.*&#39;) or your custom</span>
<span class="c1"># ones.</span>
<span class="n">extensions</span> <span class="o">=</span> <span class="p">[]</span>

<span class="c1"># Add any paths that contain templates here, relative to this directory.</span>
<span class="n">templates_path</span> <span class="o">=</span> <span class="p">[</span><span class="s1">&#39;_templates&#39;</span><span class="p">]</span>

<span class="c1"># The suffix(es) of source filenames.</span>
<span class="c1"># You can specify multiple suffix as a list of string:</span>
<span class="c1">#</span>
<span class="c1"># source_suffix = [&#39;.rst&#39;, &#39;.md&#39;]</span>
<span class="n">source_suffix</span> <span class="o">=</span> <span class="s1">&#39;.rst&#39;</span>

<span class="c1"># The encoding of source files.</span>
<span class="c1">#</span>
<span class="c1"># source_encoding = &#39;utf-8-sig&#39;</span>

<span class="c1"># The master toctree document.</span>
<span class="n">master_doc</span> <span class="o">=</span> <span class="s1">&#39;index&#39;</span>

<span class="c1"># General information about the project.</span>
<span class="n">project</span> <span class="o">=</span> <span class="sa">u</span><span class="s1">&#39;test&#39;</span>
<span class="n">copyright</span> <span class="o">=</span> <span class="sa">u</span><span class="s1">&#39;2016, test&#39;</span>
<span class="n">author</span> <span class="o">=</span> <span class="sa">u</span><span class="s1">&#39;test&#39;</span>

<span class="c1"># The version info for the project you&#39;re documenting, acts as replacement for</span>
<span class="c1"># |version| and |release|, also used in various other places throughout the</span>
<span class="c1"># built documents.</span>
<span class="c1">#</span>
<span class="c1"># The short X.Y version.</span>
<span class="n">version</span> <span class="o">=</span> <span class="sa">u</span><span class="s1">&#39;test&#39;</span>
<span class="c1"># The full version, including alpha/beta/rc tags.</span>
<span class="n">release</span> <span class="o">=</span> <span class="sa">u</span><span class="s1">&#39;test&#39;</span>

<span class="c1"># The language for content autogenerated by Sphinx. Refer to documentation</span>
<span class="c1"># for a list of supported languages.</span>
<span class="c1">#</span>
<span class="c1"># This is also used if you do content translation via gettext catalogs.</span>
<span class="c1"># Usually you set &quot;language&quot; from the command line for these cases.</span>
<span class="n">language</span> <span class="o">=</span> <span class="bp">None</span>

<span class="c1"># There are two options for replacing |today|: either, you set today to some</span>
<span class="c1"># non-false value, then it is used:</span>
<span class="c1">#</span>
<span class="c1"># today = &#39;&#39;</span>
<span class="c1">#</span>
<span class="c1"># Else, today_fmt is used as the format for a strftime call.</span>
<span class="c1">#</span>
<span class="c1"># today_fmt = &#39;%B %d, %Y&#39;</span>

<span class="c1"># List of patterns, relative to source directory, that match files and</span>
<span class="c1"># directories to ignore when looking for source files.</span>
<span class="c1"># These patterns also affect html_static_path and html_extra_path</span>
<span class="n">exclude_patterns</span> <span class="o">=</span> <span class="p">[</span><span class="s1">&#39;_build&#39;</span><span class="p">,</span> <span class="s1">&#39;Thumbs.db&#39;</span><span class="p">,</span> <span class="s1">&#39;.DS_Store&#39;</span><span class="p">]</span>

<span class="c1"># The reST default role (used for this markup: `text`) to use for all</span>
<span class="c1"># documents.</span>
<span class="c1">#</span>
<span class="c1"># default_role = None</span>

<span class="c1"># If true, &#39;()&#39; will be appended to :func: etc. cross-reference text.</span>
<span class="c1">#</span>
<span class="c1"># add_function_parentheses = True</span>

<span class="c1"># If true, the current module name will be prepended to all description</span>
<span class="c1"># unit titles (such as .. function::).</span>
<span class="c1">#</span>
<span class="c1"># add_module_names = True</span>

<span class="c1"># If true, sectionauthor and moduleauthor directives will be shown in the</span>
<span class="c1"># output. They are ignored by default.</span>
<span class="c1">#</span>
<span class="c1"># show_authors = False</span>

<span class="c1"># The name of the Pygments (syntax highlighting) style to use.</span>
<span class="n">pygments_style</span> <span class="o">=</span> <span class="s1">&#39;sphinx&#39;</span>

<span class="c1"># A list of ignored prefixes for module index sorting.</span>
<span class="c1"># modindex_common_prefix = []</span>

<span class="c1"># If true, keep warnings as &quot;system message&quot; paragraphs in the built documents.</span>
<span class="c1"># keep_warnings = False</span>

<span class="c1"># If true, `todo` and `todoList` produce output, else they produce nothing.</span>
<span class="n">todo_include_todos</span> <span class="o">=</span> <span class="bp">False</span>


<span class="c1"># -- Options for HTML output ----------------------------------------------</span>

<span class="c1"># The theme to use for HTML and HTML Help pages.  See the documentation for</span>
<span class="c1"># a list of builtin themes.</span>
<span class="c1">#</span>
<span class="n">html_theme</span> <span class="o">=</span> <span class="s1">&#39;alabaster&#39;</span>

<span class="c1"># Theme options are theme-specific and customize the look and feel of a theme</span>
<span class="c1"># further.  For a list of options available for each theme, see the</span>
<span class="c1"># documentation.</span>
<span class="c1">#</span>
<span class="c1"># html_theme_options = {}</span>

<span class="c1"># Add any paths that contain custom themes here, relative to this directory.</span>
<span class="c1"># html_theme_path = []</span>

<span class="c1"># The name for this set of Sphinx documents.</span>
<span class="c1"># &quot;&lt;project&gt; v&lt;release&gt; documentation&quot; by default.</span>
<span class="c1">#</span>
<span class="c1"># html_title = u&#39;test vtest&#39;</span>

<span class="c1"># A shorter title for the navigation bar.  Default is the same as html_title.</span>
<span class="c1">#</span>
<span class="c1"># html_short_title = None</span>

<span class="c1"># The name of an image file (relative to this directory) to place at the top</span>
<span class="c1"># of the sidebar.</span>
<span class="c1">#</span>
<span class="c1"># html_logo = None</span>

<span class="c1"># The name of an image file (relative to this directory) to use as a favicon of</span>
<span class="c1"># the docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32</span>
<span class="c1"># pixels large.</span>
<span class="c1">#</span>
<span class="c1"># html_favicon = None</span>

<span class="c1"># Add any paths that contain custom static files (such as style sheets) here,</span>
<span class="c1"># relative to this directory. They are copied after the builtin static files,</span>
<span class="c1"># so a file named &quot;default.css&quot; will overwrite the builtin &quot;default.css&quot;.</span>
<span class="n">html_static_path</span> <span class="o">=</span> <span class="p">[</span><span class="s1">&#39;_static&#39;</span><span class="p">]</span>

<span class="c1"># Add any extra paths that contain custom files (such as robots.txt or</span>
<span class="c1"># .htaccess) here, relative to this directory. These files are copied</span>
<span class="c1"># directly to the root of the documentation.</span>
<span class="c1">#</span>
<span class="c1"># html_extra_path = []</span>

<span class="c1"># If not None, a &#39;Last updated on:&#39; timestamp is inserted at every page</span>
<span class="c1"># bottom, using the given strftime format.</span>
<span class="c1"># The empty string is equivalent to &#39;%b %d, %Y&#39;.</span>
<span class="c1">#</span>
<span class="c1"># html_last_updated_fmt = None</span>

<span class="c1"># If true, SmartyPants will be used to convert quotes and dashes to</span>
<span class="c1"># typographically correct entities.</span>
<span class="c1">#</span>
<span class="c1"># html_use_smartypants = True</span>

<span class="c1"># Custom sidebar templates, maps document names to template names.</span>
<span class="c1">#</span>
<span class="c1"># html_sidebars = {}</span>

<span class="c1"># Additional templates that should be rendered to pages, maps page names to</span>
<span class="c1"># template names.</span>
<span class="c1">#</span>
<span class="c1"># html_additional_pages = {}</span>

<span class="c1"># If false, no module index is generated.</span>
<span class="c1">#</span>
<span class="c1"># html_domain_indices = True</span>

<span class="c1"># If false, no index is generated.</span>
<span class="c1">#</span>
<span class="c1"># html_use_index = True</span>

<span class="c1"># If true, the index is split into individual pages for each letter.</span>
<span class="c1">#</span>
<span class="c1"># html_split_index = False</span>

<span class="c1"># If true, links to the reST sources are added to the pages.</span>
<span class="c1">#</span>
<span class="c1"># html_show_sourcelink = True</span>

<span class="c1"># If true, &quot;Created using Sphinx&quot; is shown in the HTML footer. Default is True.</span>
<span class="c1">#</span>
<span class="c1"># html_show_sphinx = True</span>

<span class="c1"># If true, &quot;(C) Copyright ...&quot; is shown in the HTML footer. Default is True.</span>
<span class="c1">#</span>
<span class="c1"># html_show_copyright = True</span>

<span class="c1"># If true, an OpenSearch description file will be output, and all pages will</span>
<span class="c1"># contain a &lt;link&gt; tag referring to it.  The value of this option must be the</span>
<span class="c1"># base URL from which the finished HTML is served.</span>
<span class="c1">#</span>
<span class="c1"># html_use_opensearch = &#39;&#39;</span>

<span class="c1"># This is the file name suffix for HTML files (e.g. &quot;.xhtml&quot;).</span>
<span class="c1"># html_file_suffix = None</span>

<span class="c1"># Language to be used for generating the HTML full-text search index.</span>
<span class="c1"># Sphinx supports the following languages:</span>
<span class="c1">#   &#39;da&#39;, &#39;de&#39;, &#39;en&#39;, &#39;es&#39;, &#39;fi&#39;, &#39;fr&#39;, &#39;hu&#39;, &#39;it&#39;, &#39;ja&#39;</span>
<span class="c1">#   &#39;nl&#39;, &#39;no&#39;, &#39;pt&#39;, &#39;ro&#39;, &#39;ru&#39;, &#39;sv&#39;, &#39;tr&#39;, &#39;zh&#39;</span>
<span class="c1">#</span>
<span class="c1"># html_search_language = &#39;en&#39;</span>

<span class="c1"># A dictionary with options for the search language support, empty by default.</span>
<span class="c1"># &#39;ja&#39; uses this config value.</span>
<span class="c1"># &#39;zh&#39; user can custom change `jieba` dictionary path.</span>
<span class="c1">#</span>
<span class="c1"># html_search_options = {&#39;type&#39;: &#39;default&#39;}</span>

<span class="c1"># The name of a javascript file (relative to the configuration directory) that</span>
<span class="c1"># implements a search results scorer. If empty, the default will be used.</span>
<span class="c1">#</span>
<span class="c1"># html_search_scorer = &#39;scorer.js&#39;</span>

<span class="c1"># Output file base name for HTML help builder.</span>
<span class="n">htmlhelp_basename</span> <span class="o">=</span> <span class="s1">&#39;testdoc&#39;</span>

<span class="c1"># -- Options for LaTeX output ---------------------------------------------</span>

<span class="n">latex_elements</span> <span class="o">=</span> <span class="p">{</span>
    <span class="c1"># The paper size (&#39;letterpaper&#39; or &#39;a4paper&#39;).</span>
    <span class="c1">#</span>
    <span class="c1"># &#39;papersize&#39;: &#39;letterpaper&#39;,</span>

    <span class="c1"># The font size (&#39;10pt&#39;, &#39;11pt&#39; or &#39;12pt&#39;).</span>
    <span class="c1">#</span>
    <span class="c1"># &#39;pointsize&#39;: &#39;10pt&#39;,</span>

    <span class="c1"># Additional stuff for the LaTeX preamble.</span>
    <span class="c1">#</span>
    <span class="c1"># &#39;preamble&#39;: &#39;&#39;,</span>

    <span class="c1"># Latex figure (float) alignment</span>
    <span class="c1">#</span>
    <span class="c1"># &#39;figure_align&#39;: &#39;htbp&#39;,</span>
<span class="p">}</span>

<span class="c1"># Grouping the document tree into LaTeX files. List of tuples</span>
<span class="c1"># (source start file, target name, title,</span>
<span class="c1">#  author, documentclass [howto, manual, or own class]).</span>
<span class="n">latex_documents</span> <span class="o">=</span> <span class="p">[</span>
    <span class="p">(</span><span class="n">master_doc</span><span class="p">,</span> <span class="s1">&#39;test.tex&#39;</span><span class="p">,</span> <span class="sa">u</span><span class="s1">&#39;test Documentation&#39;</span><span class="p">,</span>
     <span class="sa">u</span><span class="s1">&#39;test&#39;</span><span class="p">,</span> <span class="s1">&#39;manual&#39;</span><span class="p">),</span>
<span class="p">]</span>

<span class="c1"># The name of an image file (relative to this directory) to place at the top of</span>
<span class="c1"># the title page.</span>
<span class="c1">#</span>
<span class="c1"># latex_logo = None</span>

<span class="c1"># If true, show page references after internal links.</span>
<span class="c1">#</span>
<span class="c1"># latex_show_pagerefs = False</span>

<span class="c1"># If true, show URL addresses after external links.</span>
<span class="c1">#</span>
<span class="c1"># latex_show_urls = False</span>

<span class="c1"># Documents to append as an appendix to all manuals.</span>
<span class="c1">#</span>
<span class="c1"># latex_appendices = []</span>

<span class="c1"># If false, will not define \strong, \code, \titleref, \crossref ... but only</span>
<span class="c1"># \sphinxstrong, ..., \sphinxtitleref, ... to help avoid clash with user added</span>
<span class="c1"># packages.</span>
<span class="c1">#</span>
<span class="c1"># latex_keep_old_macro_names = True</span>

<span class="c1"># If false, no module index is generated.</span>
<span class="c1">#</span>
<span class="c1"># latex_domain_indices = True</span>


<span class="c1"># -- Options for manual page output ---------------------------------------</span>

<span class="c1"># One entry per manual page. List of tuples</span>
<span class="c1"># (source start file, name, description, authors, manual section).</span>
<span class="n">man_pages</span> <span class="o">=</span> <span class="p">[</span>
    <span class="p">(</span><span class="n">master_doc</span><span class="p">,</span> <span class="s1">&#39;test&#39;</span><span class="p">,</span> <span class="sa">u</span><span class="s1">&#39;test Documentation&#39;</span><span class="p">,</span>
     <span class="p">[</span><span class="n">author</span><span class="p">],</span> <span class="mi">1</span><span class="p">)</span>
<span class="p">]</span>

<span class="c1"># If true, show URL addresses after external links.</span>
<span class="c1">#</span>
<span class="c1"># man_show_urls = False</span>


<span class="c1"># -- Options for Texinfo output -------------------------------------------</span>

<span class="c1"># Grouping the document tree into Texinfo files. List of tuples</span>
<span class="c1"># (source start file, target name, title, author,</span>
<span class="c1">#  dir menu entry, description, category)</span>
<span class="n">texinfo_documents</span> <span class="o">=</span> <span class="p">[</span>
    <span class="p">(</span><span class="n">master_doc</span><span class="p">,</span> <span class="s1">&#39;test&#39;</span><span class="p">,</span> <span class="sa">u</span><span class="s1">&#39;test Documentation&#39;</span><span class="p">,</span>
     <span class="n">author</span><span class="p">,</span> <span class="s1">&#39;test&#39;</span><span class="p">,</span> <span class="s1">&#39;One line description of project.&#39;</span><span class="p">,</span>
     <span class="s1">&#39;Miscellaneous&#39;</span><span class="p">),</span>
<span class="p">]</span>

<span class="c1"># Documents to append as an appendix to all manuals.</span>
<span class="c1">#</span>
<span class="c1"># texinfo_appendices = []</span>

<span class="c1"># If false, no module index is generated.</span>
<span class="c1">#</span>
<span class="c1"># texinfo_domain_indices = True</span>

<span class="c1"># How to display URL addresses: &#39;footnote&#39;, &#39;no&#39;, or &#39;inline&#39;.</span>
<span class="c1">#</span>
<span class="c1"># texinfo_show_urls = &#39;footnote&#39;</span>

<span class="c1"># If true, do not generate a @detailmenu in the &quot;Top&quot; node&#39;s menu.</span>
<span class="c1">#</span>
<span class="c1"># texinfo_no_detailmenu = False</span>

<span class="c1"># -- A random example -----------------------------------------------------</span>

<span class="kn">import</span> <span class="nn">sys</span><span class="o">,</span> <span class="nn">os</span>
<span class="n">sys</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">insert</span><span class="p">(</span><span class="mi">0</span><span class="p">,</span> <span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">abspath</span><span class="p">(</span><span class="s1">&#39;.&#39;</span><span class="p">))</span>
<span class="n">exclude_patterns</span> <span class="o">=</span> <span class="p">[</span><span class="s1">&#39;zzz&#39;</span><span class="p">]</span>

<span class="n">numfig</span> <span class="o">=</span> <span class="bp">True</span>
<span class="c1">#language = &#39;ja&#39;</span>

<span class="n">extensions</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="s1">&#39;sphinx.ext.todo&#39;</span><span class="p">)</span>
<span class="n">extensions</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="s1">&#39;sphinx.ext.autodoc&#39;</span><span class="p">)</span>
<span class="c1">#extensions.append(&#39;sphinx.ext.autosummary&#39;)</span>
<span class="n">extensions</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="s1">&#39;sphinx.ext.intersphinx&#39;</span><span class="p">)</span>
<span class="n">extensions</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="s1">&#39;sphinx.ext.mathjax&#39;</span><span class="p">)</span>
<span class="n">extensions</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="s1">&#39;sphinx.ext.viewcode&#39;</span><span class="p">)</span>
<span class="n">extensions</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="s1">&#39;sphinx.ext.graphviz&#39;</span><span class="p">)</span>


<span class="n">autosummary_generate</span> <span class="o">=</span> <span class="bp">True</span>
<span class="n">html_theme</span> <span class="o">=</span> <span class="s1">&#39;default&#39;</span>
<span class="c1">#source_suffix = [&#39;.rst&#39;, &#39;.txt&#39;]</span>
</pre></div>
</div>
</div>


          </div>
        </div>
      </div>
      <div class="clearer"></div>
    </div>
    <div class="related" role="navigation" aria-label="related navigation">
      <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="intl.html" title="Internationalization"
             >next</a> |</li>
        <li class="right" >
          <a href="builders.html" title="Available builders"
             >previous</a> |</li>
        <li><a href="index.html">Sphinx home</a>&#160;|</li>
        <li><a href="contents.html">Documentation</a> &#187;</li>
 
      </ul>
    </div>
    <div class="footer" role="contentinfo">
        &#169; Copyright 2007-2018, Georg Brandl and the Sphinx team.
      Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.6.7.
    </div>
  </body>
</html>
sphinx-doc 1.6.7-1ubuntu1 / usr / share / doc / sphinx-doc / html / config.html
