Commits

Zoom Quiet  committed 2e5354c

make pure doc branch

  • Participants
  • Parent commits e7527bd
  • Branches doc-zh

Comments (0)

Files changed (69)

File doc/Makefile

-# Makefile for Sphinx documentation
-#
-
-# You can set these variables from the command line.
-SPHINXOPTS   =
-SPHINXBUILD  = python ../sphinx-build.py
-PAPER        =
-
-PAPEROPT_a4      = -D latex_paper_size=a4
-PAPEROPT_letter  = -D latex_paper_size=letter
-ALLSPHINXOPTS = -d _build/doctrees $(PAPEROPT_$(PAPER)) \
-                $(SPHINXOPTS) $(O) .
-
-.PHONY: help clean html dirhtml singlehtml text man pickle json htmlhelp \
-	qthelp devhelp epub latex latexpdf changes linkcheck doctest
-
-help:
-	@echo "Please use \`make <target>' where <target> is one of"
-	@echo "  html       to make standalone HTML files"
-	@echo "  dirhtml    to make HTML files called index.html in directories"
-	@echo "  singlehtml to make one big HTML file"
-	@echo "  text       to make text files"
-	@echo "  man        to make manual pages"
-	@echo "  pickle     to make pickle files"
-	@echo "  json       to make json files"
-	@echo "  htmlhelp   to make HTML files and a HTML help project"
-	@echo "  qthelp     to make Qt help files and project"
-	@echo "  devhelp    to make Devhelp files and project"
-	@echo "  epub       to make an epub file"
-	@echo "  latex      to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
-	@echo "  latexpdf   to make LaTeX files and run pdflatex"
-	@echo "  texinfo    to make Texinfo files"
-	@echo "  info       to make Texinfo files and run them through makeinfo"
-	@echo "  gettext    to make PO message catalogs"
-	@echo "  changes    to make an overview over all changed/added/deprecated items"
-	@echo "  linkcheck  to check all external links for integrity"
-
-clean:
-	-rm -rf _build/*
-
-html:
-	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) _build/html
-	@echo
-	@echo "Build finished. The HTML pages are in _build/html."
-
-dirhtml:
-	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) _build/dirhtml
-	@echo
-	@echo "Build finished. The HTML pages are in _build/dirhtml."
-
-singlehtml:
-	$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) _build/singlehtml
-	@echo
-	@echo "Build finished. The HTML page is in _build/singlehtml."
-
-text:
-	$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) _build/text
-	@echo
-	@echo "Build finished."
-
-man:
-	$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) _build/man
-	@echo
-	@echo "Build finished."
-
-pickle:
-	$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) _build/pickle
-	@echo
-	@echo "Build finished."
-
-json:
-	$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) _build/json
-	@echo
-	@echo "Build finished."
-
-htmlhelp:
-	$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) _build/htmlhelp
-	@echo
-	@echo "Build finished; now you can run HTML Help Workshop with the" \
-	      ".hhp project file in _build/htmlhelp."
-
-qthelp:
-	$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) _build/qthelp
-	@echo
-	@echo "Build finished; now you can run qcollectiongenerator with the" \
-	      ".qhcp project file in build/qthelp."
-	@echo "# qcollectiongenerator _build/qthelp/Sphinx.qhcp"
-	@echo "To view the help collection:"
-	@echo "# assistant -collectionFile _build/qthelp/Sphinx.qhc"
-
-devhelp:
-	$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) _build/devhelp
-	@echo
-	@echo "Build finished."
-	@echo "To view the help file:"
-	@echo "# mkdir -p $$HOME/.local/share/devhelp/sphinx"
-	@echo "# ln -s _build/devhelp $$HOME/.local/share/devhelp/sphinx"
-	@echo "# devhelp"
-
-epub:
-	$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) _build/epub
-	@echo
-	@echo "Build finished. The epub file is in _build/epub."
-
-latex:
-	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) _build/latex
-	@echo
-	@echo "Build finished; the LaTeX files are in _build/latex."
-	@echo "Run \`make all-pdf' or \`make all-ps' in that directory to" \
-	      "run these through (pdf)latex."
-
-latexpdf:
-	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) _build/latex
-	@echo "Running LaTeX files through pdflatex..."
-	make -C _build/latex all-pdf
-	@echo "pdflatex finished; the PDF files are in _build/latex."
-
-gettext:
-	$(SPHINXBUILD) -b gettext $(ALLSPHINXOPTS) _build/locale
-	@echo
-	@echo "Build finished. The message catalogs are in _build/locale."
-
-changes:
-	$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) _build/changes
-	@echo
-	@echo "The overview file is in _build/changes."
-
-linkcheck:
-	$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) _build/linkcheck
-	@echo
-	@echo "Link check complete; look for any errors in the above output " \
-	      "or in _build/linkcheck/output.txt."
-
-doctest:
-	$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) _build/doctest
-
-texinfo:
-	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) _build/texinfo
-	@echo
-	@echo "Build finished. The Texinfo files are in _build/texinfo."
-	@echo "Run \`make' in that directory to run these through makeinfo" \
-	      "(use \`make info' here to do that automatically)."
-
-info:
-	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) _build/texinfo
-	@echo "Running Texinfo files through makeinfo..."
-	make -C _build/texinfo info
-	@echo "makeinfo finished; the Info files are in _build/texinfo."

File doc/_static/pocoo.png

Removed
Old image

File doc/_static/sphinx.png

Removed
Old image

File doc/_templates/index.html

-{% extends "layout.html" %}
-{% set title = 'Overview' %}
-{% block body %}
-  <h1>Welcome</h1>
-
-  <div class="quotebar">
-    <p><em>What users say:</em></p>
-    <p>&ldquo;Cheers for a great tool that actually makes programmers <b>want</b>
-      to write documentation!&rdquo;</p>
-  </div>
-
-  <p>
-    Sphinx is a tool that makes it easy to create intelligent and beautiful
-    documentation, written by Georg Brandl and licensed under the BSD license.</p>
-  <p>It was originally created for <a href="http://docs.python.org/dev/">the
-    new Python documentation</a>, and it has excellent facilities for the
-    documentation of Python projects, but C/C++ is already supported as well,
-    and it is planned to add special support for other languages as well.  Of
-    course, this site is also created from reStructuredText sources using
-    Sphinx!
-  </p>
-  <p>
-    Sphinx is under constant development.  The following features are present,
-    work fine and can be seen &#8220;in action&#8221; in the Python docs:
-  </p>
-  <ul>
-    <li><b>Output formats:</b> HTML (including Windows HTML Help), LaTeX (for
-      printable PDF versions), manual pages, plain text</li>
-    <li><b>Extensive cross-references:</b> semantic markup and automatic links
-      for functions, classes, citations, glossary terms and similar pieces of
-      information</li>
-    <li><b>Hierarchical structure:</b> easy definition of a document tree, with
-      automatic links to siblings, parents and children</li>
-    <li><b>Automatic indices:</b> general index as well as a module index</li>
-    <li><b>Code handling:</b> automatic highlighting using the <a
-      href="http://pygments.org">Pygments</a> highlighter</li>
-    <li><b>Extensions:</b> automatic testing of code snippets, inclusion of
-      docstrings from Python modules (API docs), and more</li>
-  </ul>
-  <p>
-    Sphinx uses <a href="http://docutils.sf.net/rst.html">reStructuredText</a>
-    as its markup language, and many of its strengths come from the power and
-    straightforwardness of reStructuredText and its parsing and translating
-    suite, the <a href="http://docutils.sf.net/">Docutils</a>.
-  </p>
-
-  <h2>Documentation</h2>
-
-  <table class="contentstable" align="center" style="margin-left: 30px"><tr>
-    <td width="50%">
-      <p class="biglink"><a class="biglink" href="{{ pathto("tutorial") }}">First steps with Sphinx</a><br/>
-         <span class="linkdescr">overview of basic tasks</span></p>
-      <p class="biglink"><a class="biglink" href="{{ pathto("contents") }}">Contents</a><br/>
-         <span class="linkdescr">for a complete overview</span></p>
-    </td><td width="50%">
-      <p class="biglink"><a class="biglink" href="{{ pathto("search") }}">Search page</a><br/>
-         <span class="linkdescr">search the documentation</span></p>
-      <p class="biglink"><a class="biglink" href="{{ pathto("genindex") }}">General Index</a><br/>
-         <span class="linkdescr">all functions, classes, terms</span></p>
-    </td></tr>
-  </table>
-
-  <p>
-    You can also download PDF versions of the Sphinx documentation:
-    a <a href="http://sphinx.pocoo.org/sphinx.pdf">version</a> generated from
-    the LaTeX Sphinx produces, and
-    a <a href="http://sphinx.pocoo.org/sphinx-rst2pdf.pdf">version</a> generated
-    by rst2pdf.
-  </p>
-
-  <h2>Examples</h2>
-  <p>Links to documentation generated with Sphinx can be found on the
-    <a href="{{ pathto("examples") }}">Projects using Sphinx</a> page.
-  </p>
-  <p>
-    For examples of how Sphinx source files look, use the &#8220;Show
-    source&#8221; links on all pages of the documentation apart from this
-    welcome page.
-  </p>
-
-  <p>You may also be interested in the very nice
-    <a href="http://matplotlib.sourceforge.net/sampledoc/">tutorial</a> on how to
-    create a customized documentation using Sphinx written by the matplotlib
-    developers.</p>
-
-  <p>There is a <a href="http://sphinx-users.jp/doc10/">Japanese translation</a>
-    of this documentation, thanks to Yoshiki Shibukawa.</p>
-
-  <h2>Get Sphinx</h2>
-  <p>
-    Sphinx is available as an <a
-    href="http://peak.telecommunity.com/DevCenter/EasyInstall">easy-install</a>able
-    package on the <a href="http://pypi.python.org/pypi/Sphinx">Python Package
-    Index</a>.
-  </p>
-  <p>The code can be found in a Mercurial repository, at
-    <tt>http://bitbucket.org/birkenfeld/sphinx/</tt>.</p>
-
-{% endblock %}

File doc/_templates/indexsidebar.html

-<p class="logo"><a href="http://pocoo.org/">
-  <img src="{{ pathto("_static/pocoo.png", 1) }}" /></a></p>
-
-<h3>Download</h3>
-{% if version.endswith('(hg)') %}
-<p>This documentation is for version <b>{{ version }}</b>, which is
-  not released yet.</p>
-<p>You can use it from the
-  <a href="http://bitbucket.org/birkenfeld/sphinx/">Mercurial repo</a> or look for
-  released versions in the <a href="http://pypi.python.org/pypi/Sphinx">Python
-    Package Index</a>.</p>
-{% else %}
-<p>Current version: <b>{{ version }}</b></p>
-<p>Get Sphinx from the <a href="http://pypi.python.org/pypi/Sphinx">Python Package
-Index</a>, or install it with:</p>
-<pre>easy_install -U Sphinx</pre>
-<p>Latest <a href="http://sphinx.pocoo.org/latest/">development version docs</a>
-are also available.</p>
-{% endif %}
-
-<h3>Questions? Suggestions?</h3>
-
-<p>Join the <a href="http://groups.google.com/group/sphinx-dev">Google group</a>:</p>
-<form action="http://groups.google.com/group/sphinx-dev/boxsubscribe"
-      style="padding-left: 1em">
-  <input type="text" name="email" value="your@email"/>
-  <input type="submit" name="sub" value="Subscribe" />
-</form>
-<p>or come to the <tt>#pocoo</tt> channel on FreeNode.</p>
-<p>You can also open an issue at the
-  <a href="http://www.bitbucket.org/birkenfeld/sphinx/issues/">tracker</a>.</p>

File doc/_templates/layout.html

-{% extends "!layout.html" %}
-
-{% block extrahead %}
-{{ super() }}
-{%- if not embedded %}
-<style type="text/css">
-  table.right { float: right; margin-left: 20px; }
-  table.right td { border: 1px solid #ccc; }
-</style>
-{%- endif %}
-{% endblock %}
-
-{% block rootrellink %}
-        <li><a href="{{ pathto('index') }}">Sphinx home</a>&nbsp;|&nbsp;</li>
-        <li><a href="{{ pathto('contents') }}">Documentation</a>
-          &raquo;</li>
-{% endblock %}
-
-{% block header %}
-<div style="background-color: white; text-align: left; padding: 10px 10px 15px 15px">
-<img src="{{ pathto("_static/sphinx.png", 1) }}" alt="Sphinx logo" />
-</div>
-{% endblock %}

File doc/builders.rst

-.. _builders:
-
-Available builders
-==================
-
-.. module:: sphinx.builders
-   :synopsis: Available built-in builder classes.
-
-These are the built-in Sphinx builders.  More builders can be added by
-:ref:`extensions <extensions>`.
-
-The builder's "name" must be given to the **-b** command-line option of
-:program:`sphinx-build` to select a builder.
-
-
-.. module:: sphinx.builders.html
-.. class:: StandaloneHTMLBuilder
-
-   This is the standard HTML builder.  Its output is a directory with HTML
-   files, complete with style sheets and optionally the reST sources.  There are
-   quite a few configuration values that customize the output of this builder,
-   see the chapter :ref:`html-options` for details.
-
-   Its name is ``html``.
-
-.. class:: DirectoryHTMLBuilder
-
-   This is a subclass of the standard HTML builder.  Its output is a directory
-   with HTML files, where each file is called ``index.html`` and placed in a
-   subdirectory named like its page name.  For example, the document
-   ``markup/rest.rst`` will not result in an output file ``markup/rest.html``,
-   but ``markup/rest/index.html``.  When generating links between pages, the
-   ``index.html`` is omitted, so that the URL would look like ``markup/rest/``.
-
-   Its name is ``dirhtml``.
-
-   .. versionadded:: 0.6
-
-.. class:: SingleFileHTMLBuilder
-
-   This is an HTML builder that combines the whole project in one output file.
-   (Obviously this only works with smaller projects.)  The file is named like
-   the master document.  No indices will be generated.
-
-   Its name is ``singlehtml``.
-
-   .. versionadded:: 1.0
-
-.. module:: sphinx.builders.htmlhelp
-.. class:: HTMLHelpBuilder
-
-   This builder produces the same output as the standalone HTML builder, but
-   also generates HTML Help support files that allow the Microsoft HTML Help
-   Workshop to compile them into a CHM file.
-
-   Its name is ``htmlhelp``.
-
-.. module:: sphinx.builders.qthelp
-.. class:: QtHelpBuilder
-
-   This builder produces the same output as the standalone HTML builder, but
-   also generates `Qt help`_ collection support files that allow
-   the Qt collection generator to compile them.
-
-   Its name is ``qthelp``.
-
-   .. _Qt help: http://doc.trolltech.com/4.6/qthelp-framework.html
-
-.. module:: sphinx.builders.devhelp
-.. class:: DevhelpBuilder
-
-   This builder produces the same output as the standalone HTML builder, but
-   also generates `GNOME Devhelp <http://live.gnome.org/devhelp>`__
-   support file that allows the GNOME Devhelp reader to view them.
-
-   Its name is ``devhelp``.
-
-.. module:: sphinx.builders.epub
-.. class:: EpubBuilder
-
-   This builder produces the same output as the standalone HTML builder, but
-   also generates an *epub* file for ebook readers.  See :ref:`epub-faq` for
-   details about it.  For definition of the epub format, have a look at
-   `<http://www.idpf.org/specs.htm>`_ or `<http://en.wikipedia.org/wiki/EPUB>`_.
-
-   Some ebook readers do not show the link targets of references.  Therefore
-   this builder adds the targets after the link when necessary.  The display
-   of the URLs can be customized by adding CSS rules for the class
-   ``link-target``.
-
-   Its name is ``epub``.
-
-.. module:: sphinx.builders.latex
-.. class:: LaTeXBuilder
-
-   This builder produces a bunch of LaTeX files in the output directory.  You
-   have to specify which documents are to be included in which LaTeX files via
-   the :confval:`latex_documents` configuration value.  There are a few
-   configuration values that customize the output of this builder, see the
-   chapter :ref:`latex-options` for details.
-
-   .. note::
-
-      The produced LaTeX file uses several LaTeX packages that may not be
-      present in a "minimal" TeX distribution installation.  For TeXLive,
-      the following packages need to be installed:
-
-      * latex-recommended
-      * latex-extra
-      * fonts-recommended
-
-   Its name is ``latex``.
-
-Note that a direct PDF builder using ReportLab is available in `rst2pdf
-<http://rst2pdf.googlecode.com>`_ version 0.12 or greater.  You need to add
-``'rst2pdf.pdfbuilder'`` to your :confval:`extensions` to enable it, its name is
-``pdf``.  Refer to the `rst2pdf manual
-<http://lateral.netmanagers.com.ar/static/manual.pdf>`_ for details.
-
-.. module:: sphinx.builders.text
-.. class:: TextBuilder
-
-   This builder produces a text file for each reST file -- this is almost the
-   same as the reST source, but with much of the markup stripped for better
-   readability.
-
-   Its name is ``text``.
-
-   .. versionadded:: 0.4
-
-.. module:: sphinx.builders.manpage
-.. class:: ManualPageBuilder
-
-   This builder produces manual pages in the groff format.  You have to specify
-   which documents are to be included in which manual pages via the
-   :confval:`man_pages` configuration value.
-
-   Its name is ``man``.
-
-   .. note::
-
-      This builder requires the docutils manual page writer, which is only
-      available as of docutils 0.6.
-
-   .. versionadded:: 1.0
-
-
-.. module:: sphinx.builders.texinfo
-.. class:: TexinfoBuilder
-
-   This builder produces Texinfo files that can be processed into Info files by
-   the :program:`makeinfo` program.  You have to specify which documents are to
-   be included in which Texinfo files via the :confval:`texinfo_documents`
-   configuration value.
-
-   The Info format is the basis of the on-line help system used by GNU Emacs and
-   the terminal-based program :program:`info`.  See :ref:`texinfo-faq` for more
-   details.  The Texinfo format is the official documentation system used by the
-   GNU project.  More information on Texinfo can be found at
-   `<http://www.gnu.org/software/texinfo/>`_.
-
-   Its name is ``texinfo``.
-
-   .. versionadded:: 1.1
-
-
-.. currentmodule:: sphinx.builders.html
-.. class:: SerializingHTMLBuilder
-
-   This builder uses a module that implements the Python serialization API
-   (`pickle`, `simplejson`, `phpserialize`, and others) to dump the generated
-   HTML documentation.  The pickle builder is a subclass of it.
-
-   A concrete subclass of this builder serializing to the `PHP serialization`_
-   format could look like this::
-
-        import phpserialize
-
-        class PHPSerializedBuilder(SerializingHTMLBuilder):
-            name = 'phpserialized'
-            implementation = phpserialize
-            out_suffix = '.file.phpdump'
-            globalcontext_filename = 'globalcontext.phpdump'
-            searchindex_filename = 'searchindex.phpdump'
-
-   .. _PHP serialization: http://pypi.python.org/pypi/phpserialize
-
-   .. attribute:: implementation
-
-      A module that implements `dump()`, `load()`, `dumps()` and `loads()`
-      functions that conform to the functions with the same names from the
-      pickle module.  Known modules implementing this interface are
-      `simplejson` (or `json` in Python 2.6), `phpserialize`, `plistlib`,
-      and others.
-
-   .. attribute:: out_suffix
-
-      The suffix for all regular files.
-
-   .. attribute:: globalcontext_filename
-
-      The filename for the file that contains the "global context".  This
-      is a dict with some general configuration values such as the name
-      of the project.
-
-   .. attribute:: searchindex_filename
-
-      The filename for the search index Sphinx generates.
-
-
-   See :ref:`serialization-details` for details about the output format.
-
-   .. versionadded:: 0.5
-
-.. class:: PickleHTMLBuilder
-
-   This builder produces a directory with pickle files containing mostly HTML
-   fragments and TOC information, for use of a web application (or custom
-   postprocessing tool) that doesn't use the standard HTML templates.
-
-   See :ref:`serialization-details` for details about the output format.
-
-   Its name is ``pickle``.  (The old name ``web`` still works as well.)
-
-   The file suffix is ``.fpickle``.  The global context is called
-   ``globalcontext.pickle``, the search index ``searchindex.pickle``.
-
-.. class:: JSONHTMLBuilder
-
-   This builder produces a directory with JSON files containing mostly HTML
-   fragments and TOC information, for use of a web application (or custom
-   postprocessing tool) that doesn't use the standard HTML templates.
-
-   See :ref:`serialization-details` for details about the output format.
-
-   Its name is ``json``.
-
-   The file suffix is ``.fjson``.  The global context is called
-   ``globalcontext.json``, the search index ``searchindex.json``.
-
-   .. versionadded:: 0.5
-
-.. module:: sphinx.builders.intl
-.. class:: MessageCatalogBuilder
-
-   This builder produces gettext-style message catalos.  Each top-level file or
-   subdirectory grows a single ``.pot`` catalog template.
-
-   See the documentation on :ref:`intl` for further reference.
-
-   Its name is ``gettext``.
-
-   .. versionadded:: 1.1
-
-.. module:: sphinx.builders.changes
-.. class:: ChangesBuilder
-
-   This builder produces an HTML overview of all :rst:dir:`versionadded`,
-   :rst:dir:`versionchanged` and :rst:dir:`deprecated` directives for the current
-   :confval:`version`.  This is useful to generate a ChangeLog file, for
-   example.
-
-   Its name is ``changes``.
-
-.. module:: sphinx.builders.linkcheck
-.. class:: CheckExternalLinksBuilder
-
-   This builder scans all documents for external links, tries to open them with
-   :mod:`urllib2`, and writes an overview which ones are broken and redirected
-   to standard output and to :file:`output.txt` in the output directory.
-
-   Its name is ``linkcheck``.
-
-
-Built-in Sphinx extensions that offer more builders are:
-
-* :mod:`~sphinx.ext.doctest`
-* :mod:`~sphinx.ext.coverage`
-
-
-.. _serialization-details:
-
-Serialization builder details
------------------------------
-
-All serialization builders outputs one file per source file and a few special
-files.  They also copy the reST source files in the directory ``_sources``
-under the output directory.
-
-The :class:`.PickleHTMLBuilder` is a builtin subclass that implements the pickle
-serialization interface.
-
-The files per source file have the extensions of
-:attr:`~.SerializingHTMLBuilder.out_suffix`, and are arranged in directories
-just as the source files are.  They unserialize to a dictionary (or dictionary
-like structure) with these keys:
-
-``body``
-   The HTML "body" (that is, the HTML rendering of the source file), as rendered
-   by the HTML translator.
-
-``title``
-   The title of the document, as HTML (may contain markup).
-
-``toc``
-   The table of contents for the file, rendered as an HTML ``<ul>``.
-
-``display_toc``
-   A boolean that is ``True`` if the ``toc`` contains more than one entry.
-
-``current_page_name``
-   The document name of the current file.
-
-``parents``, ``prev`` and ``next``
-   Information about related chapters in the TOC tree.  Each relation is a
-   dictionary with the keys ``link`` (HREF for the relation) and ``title``
-   (title of the related document, as HTML).  ``parents`` is a list of
-   relations, while ``prev`` and ``next`` are a single relation.
-
-``sourcename``
-   The name of the source file under ``_sources``.
-
-The special files are located in the root output directory.  They are:
-
-:attr:`.SerializingHTMLBuilder.globalcontext_filename`
-   A pickled dict with these keys:
-
-   ``project``, ``copyright``, ``release``, ``version``
-      The same values as given in the configuration file.
-
-   ``style``
-      :confval:`html_style`.
-
-   ``last_updated``
-      Date of last build.
-
-   ``builder``
-      Name of the used builder, in the case of pickles this is always
-      ``'pickle'``.
-
-   ``titles``
-      A dictionary of all documents' titles, as HTML strings.
-
-:attr:`.SerializingHTMLBuilder.searchindex_filename`
-   An index that can be used for searching the documentation.  It is a pickled
-   list with these entries:
-
-   * A list of indexed docnames.
-   * A list of document titles, as HTML strings, in the same order as the first
-     list.
-   * A dict mapping word roots (processed by an English-language stemmer) to a
-     list of integers, which are indices into the first list.
-
-``environment.pickle``
-   The build environment.  This is always a pickle file, independent of the
-   builder and a copy of the environment that was used when the builder was
-   started.
-
-   .. todo:: Document common members.
-
-   Unlike the other pickle files this pickle file requires that the ``sphinx``
-   package is available on unpickling.

File doc/changes.rst

-:tocdepth: 2
-
-.. _changes:
-
-Changes in Sphinx
-*****************
-
-.. include:: ../CHANGES

File doc/conf.py

-# -*- coding: utf-8 -*-
-#
-# Sphinx documentation build configuration file
-
-import re
-import sphinx
-
-extensions = ['sphinx.ext.autodoc', 'sphinx.ext.doctest', 'sphinx.ext.todo',
-              'sphinx.ext.autosummary', 'sphinx.ext.extlinks']
-
-master_doc = 'contents'
-templates_path = ['_templates']
-exclude_patterns = ['_build']
-
-project = 'Sphinx'
-copyright = '2007-2010, Georg Brandl'
-version = sphinx.__released__
-release = version
-show_authors = True
-
-html_theme = 'sphinxdoc'
-modindex_common_prefix = ['sphinx.']
-html_static_path = ['_static']
-html_sidebars = {'index': ['indexsidebar.html', 'searchbox.html']}
-html_additional_pages = {'index': 'index.html'}
-html_use_opensearch = 'http://sphinx.pocoo.org'
-
-htmlhelp_basename = 'Sphinxdoc'
-
-epub_theme = 'epub'
-epub_basename = 'sphinx'
-epub_author = 'Georg Brandl'
-epub_publisher = 'http://sphinx.pocoo.org/'
-epub_scheme = 'url'
-epub_identifier = epub_publisher
-epub_pre_files = [('index.html', 'Welcome')]
-epub_exclude_files = ['_static/opensearch.xml', '_static/doctools.js',
-    '_static/jquery.js', '_static/searchtools.js', '_static/underscore.js',
-    '_static/basic.css', 'search.html']
-
-latex_documents = [('contents', 'sphinx.tex', 'Sphinx Documentation',
-                    'Georg Brandl', 'manual', 1)]
-latex_logo = '_static/sphinx.png'
-latex_elements = {
-    'fontpkg': '\\usepackage{palatino}',
-}
-
-autodoc_member_order = 'groupwise'
-todo_include_todos = True
-extlinks = {'duref': ('http://docutils.sourceforge.net/docs/ref/rst/'
-                      'restructuredtext.html#%s', ''),
-            'durole': ('http://docutils.sourceforge.net/docs/ref/rst/'
-                       'roles.html#%s', ''),
-            'dudir': ('http://docutils.sourceforge.net/docs/ref/rst/'
-                      'directives.html#%s', '')}
-
-man_pages = [
-    ('contents', 'sphinx-all', 'Sphinx documentation generator system manual',
-     'Georg Brandl', 1),
-    ('man/sphinx-build', 'sphinx-build', 'Sphinx documentation generator tool',
-     '', 1),
-    ('man/sphinx-quickstart', 'sphinx-quickstart', 'Sphinx documentation '
-     'template generator', '', 1),
-]
-
-texinfo_documents = [
-    ('contents', 'sphinx', 'Sphinx Documentation', 'Georg Brandl',
-     'Sphinx', 'The Sphinx documentation builder.', 'Documentation tools',
-     1),
-]
-
-# We're not using intersphinx right now, but if we did, this would be part of
-# the mapping:
-intersphinx_mapping = {'python': ('http://docs.python.org/dev', None)}
-
-
-# -- Extension interface -------------------------------------------------------
-
-from sphinx import addnodes
-
-
-event_sig_re = re.compile(r'([a-zA-Z-]+)\s*\((.*)\)')
-
-def parse_event(env, sig, signode):
-    m = event_sig_re.match(sig)
-    if not m:
-        signode += addnodes.desc_name(sig, sig)
-        return sig
-    name, args = m.groups()
-    signode += addnodes.desc_name(name, name)
-    plist = addnodes.desc_parameterlist()
-    for arg in args.split(','):
-        arg = arg.strip()
-        plist += addnodes.desc_parameter(arg, arg)
-    signode += plist
-    return name
-
-
-def setup(app):
-    from sphinx.ext.autodoc import cut_lines
-    app.connect('autodoc-process-docstring', cut_lines(4, what=['module']))
-    app.add_description_unit('confval', 'confval',
-                             objname='configuration value',
-                             indextemplate='pair: %s; configuration value')
-    app.add_description_unit('event', 'event', 'pair: %s; event', parse_event)

File doc/config.rst

-.. highlightlang:: python
-
-.. _build-config:
-
-The build configuration file
-============================
-
-.. module:: conf
-   :synopsis: Build configuration file.
-
-The :term:`configuration directory` must contain a file named :file:`conf.py`.
-This file (containing Python code) is called the "build configuration file" and
-contains all configuration needed to customize Sphinx input and output behavior.
-
-The configuration file is executed as Python code at build time (using
-:func:`execfile`, 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.
-
-Important points to note:
-
-* If not otherwise documented, values must be strings, and their default is the
-  empty string.
-
-* The term "fully-qualified name" refers to a string that names an importable
-  Python object inside a module; for example, the FQN
-  ``"sphinx.builders.Builder"`` means the ``Builder`` class in the
-  ``sphinx.builders`` module.
-
-* Remember that document names use ``/`` as the path separator and don't contain
-  the file name extension.
-
-* Since :file:`conf.py` 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 ``# -*- coding: utf-8 -*-``) and use Unicode string literals
-  when you include non-ASCII characters in configuration values.
-
-* 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 ``del`` if appropriate.  Modules are
-  removed automatically, so you don't need to ``del`` your imports after use.
-
-* There is a special object named ``tags`` available in the config file.
-  It can be used to query and change the tags (see :ref:`tags`).  Use
-  ``tags.has('tag')`` to query, ``tags.add('tag')`` and ``tags.remove('tag')``
-  to change.
-
-
-General configuration
----------------------
-
-.. confval:: extensions
-
-   A list of strings that are module names of Sphinx extensions.  These can be
-   extensions coming with Sphinx (named ``sphinx.ext.*``) or custom ones.
-
-   Note that you can extend :data:`sys.path` 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 :term:`configuration directory`,
-   use :func:`os.path.abspath` like so::
-
-      import sys, os
-
-      sys.path.append(os.path.abspath('sphinxext'))
-
-      extensions = ['extname']
-
-   That way, you can load an extension called ``extname`` from the subdirectory
-   ``sphinxext``.
-
-   The configuration file itself can be an extension; for that, you only need to
-   provide a :func:`setup` function in it.
-
-.. confval:: source_suffix
-
-   The file name extension of source files.  Only files with this suffix will be
-   read as sources.  Default is ``'.rst'``.
-
-.. confval:: source_encoding
-
-   The encoding of all reST source files.  The recommended encoding, and the
-   default value, is ``'utf-8-sig'``.
-
-   .. versionadded:: 0.5
-      Previously, Sphinx accepted only UTF-8 encoded sources.
-
-.. confval:: master_doc
-
-   The document name of the "master" document, that is, the document that
-   contains the root :rst:dir:`toctree` directive.  Default is ``'contents'``.
-
-.. confval:: exclude_patterns
-
-   A list of glob-style patterns that should be excluded when looking for source
-   files. [1]_ They are matched against the source file names relative to the
-   source directory, using slashes as directory separators on all platforms.
-
-   Example patterns:
-
-   - ``'library/xml.rst'`` -- ignores the ``library/xml.rst`` file (replaces
-     entry in :confval:`unused_docs`)
-   - ``'library/xml'`` -- ignores the ``library/xml`` directory (replaces entry
-     in :confval:`exclude_trees`)
-   - ``'library/xml*'`` -- ignores all files and directories starting with
-     ``library/xml``
-   - ``'**/.svn'`` -- ignores all ``.svn`` directories (replaces entry in
-     :confval:`exclude_dirnames`)
-
-   :confval:`exclude_patterns` is also consulted when looking for static files
-   in :confval:`html_static_path`.
-
-   .. versionadded:: 1.0
-
-.. confval:: unused_docs
-
-   A list of document names that are present, but not currently included in the
-   toctree.  Use this setting to suppress the warning that is normally emitted
-   in that case.
-
-   .. deprecated:: 1.0
-      Use :confval:`exclude_patterns` instead.
-
-.. confval:: exclude_trees
-
-   A list of directory paths, relative to the source directory, that are to be
-   recursively excluded from the search for source files, that is, their
-   subdirectories won't be searched too.  The default is ``[]``.
-
-   .. versionadded:: 0.4
-
-   .. deprecated:: 1.0
-      Use :confval:`exclude_patterns` instead.
-
-.. confval:: exclude_dirnames
-
-   A list of directory names that are to be excluded from any recursive
-   operation Sphinx performs (e.g. searching for source files or copying static
-   files).  This is useful, for example, to exclude version-control-specific
-   directories like ``'CVS'``.  The default is ``[]``.
-
-   .. versionadded:: 0.5
-
-   .. deprecated:: 1.0
-      Use :confval:`exclude_patterns` instead.
-
-.. confval:: templates_path
-
-   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.
-
-.. confval:: template_bridge
-
-   A string with the fully-qualified name of a callable (or simply a class) that
-   returns an instance of :class:`~sphinx.application.TemplateBridge`.  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.)
-
-.. confval:: rst_epilog
-
-   .. index:: pair: global; substitutions
-
-   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::
-
-      rst_epilog = """
-      .. |psf| replace:: Python Software Foundation
-      """
-
-   .. versionadded:: 0.6
-
-.. confval:: rst_prolog
-
-   A string of reStructuredText that will be included at the beginning of every
-   source file that is read.
-
-   .. versionadded:: 1.0
-
-.. confval:: primary_domain
-
-   .. index:: default; domain
-              primary; domain
-
-   The name of the default :ref:`domain <domains>`.  Can also be ``None`` to
-   disable a default domain.  The default is ``'py'``.  Those objects in other
-   domains (whether the domain name is given explicitly, or selected by a
-   :rst:dir:`default-domain` 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").
-
-   .. versionadded:: 1.0
-
-.. confval:: default_role
-
-   .. index:: default; role
-
-   The name of a reST role (builtin or Sphinx extension) to use as the default
-   role, that is, for text marked up ```like this```.  This can be set to
-   ``'py:obj'`` to make ```filter``` a cross-reference to the Python function
-   "filter".  The default is ``None``, which doesn't reassign the default role.
-
-   The default role can always be set within individual documents using the
-   standard reST :rst:dir:`default-role` directive.
-
-   .. versionadded:: 0.4
-
-.. confval:: keep_warnings
-
-   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 ``sphinx-build`` is run.
-
-   The default is ``False``, the pre-0.5 behavior was to always keep them.
-
-   .. versionadded:: 0.5
-
-.. confval:: needs_sphinx
-
-   If set to a ``major.minor`` version string like ``'1.1'``, Sphinx will
-   compare it with its version and refuse to build if it is too old.  Default is
-   no requirement.
-
-   .. versionadded:: 1.0
-
-.. confval:: nitpicky
-
-   If true, Sphinx will warn about *all* references where the target cannot be
-   found.  Default is ``False``.  You can activate this mode temporarily using
-   the :option:`-n` command-line switch.
-
-   .. versionadded:: 1.0
-
-
-Project information
--------------------
-
-.. confval:: project
-
-   The documented project's name.
-
-.. confval:: copyright
-
-   A copyright statement in the style ``'2008, Author Name'``.
-
-.. confval:: version
-
-   The major project version, used as the replacement for ``|version|``.  For
-   example, for the Python documentation, this may be something like ``2.6``.
-
-.. confval:: release
-
-   The full project version, used as the replacement for ``|release|`` and
-   e.g. in the HTML templates.  For example, for the Python documentation, this
-   may be something like ``2.6.0rc1``.
-
-   If you don't need the separation provided between :confval:`version` and
-   :confval:`release`, just set them both to the same value.
-
-.. confval:: today
-             today_fmt
-
-   These values determine how to format the current date, used as the
-   replacement for ``|today|``.
-
-   * If you set :confval:`today` to a non-empty value, it is used.
-   * Otherwise, the current time is formatted using :func:`time.strftime` and
-     the format given in :confval:`today_fmt`.
-
-   The default is no :confval:`today` and a :confval:`today_fmt` of ``'%B %d,
-   %Y'`` (or, if translation is enabled with :confval:`language`, am equivalent
-   %format for the selected locale).
-
-.. confval:: highlight_language
-
-   The default language to highlight source code in.  The default is
-   ``'python'``.  The value should be a valid Pygments lexer name, see
-   :ref:`code-examples` for more details.
-
-   .. versionadded:: 0.5
-
-.. confval:: pygments_style
-
-   The style name to use for Pygments highlighting of source code.  The default
-   style is selected by the theme for HTML output, and ``'sphinx'`` otherwise.
-
-   .. versionchanged:: 0.3
-      If the value is a fully-qualified name of a custom Pygments style class,
-      this is then used as custom style.
-
-.. confval:: add_function_parentheses
-
-   A boolean that decides whether parentheses are appended to function and
-   method role text (e.g. the content of ``:func:`input```) to signify that the
-   name is callable.  Default is ``True``.
-
-.. confval:: add_module_names
-
-   A boolean that decides whether module names are prepended to all
-   :term:`object` names (for object types where a "module" of some kind is
-   defined), e.g. for :rst:dir:`py:function` directives.  Default is ``True``.
-
-.. confval:: show_authors
-
-   A boolean that decides whether :rst:dir:`codeauthor` and
-   :rst:dir:`sectionauthor` directives produce any output in the built files.
-
-.. confval:: modindex_common_prefix
-
-   A list of prefixes that are ignored for sorting the Python module index
-   (e.g., if this is set to ``['foo.']``, then ``foo.bar`` is shown under ``B``,
-   not ``F``). This can be handy if you document a project that consists of a
-   single package.  Works only for the HTML builder currently.  Default is
-   ``[]``.
-
-   .. versionadded:: 0.6
-
-.. confval:: trim_footnote_reference_space
-
-   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.
-
-   .. versionadded:: 0.6
-
-.. confval:: trim_doctest_flags
-
-   If true, doctest flags (comments looking like ``# doctest: FLAG, ...``) at
-   the ends of lines are removed for all code blocks showing interactive Python
-   sessions (i.e. doctests).  Default is true.  See the extension
-   :mod:`~sphinx.ext.doctest` for more possibilities of including doctests.
-
-   .. versionadded:: 1.0
-
-
-.. _intl-options:
-
-Options for internationalization
---------------------------------
-
-These options influence Sphinx' *Native Language Support*.  See the
-documentation on :ref:`intl` for details.
-
-.. confval:: language
-
-   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 :confval:`locale_dirs`.  In the LaTeX builder, a suitable
-   language will be selected as an option for the *Babel* package.  Default is
-   ``None``, which means that no translation will be done.
-
-   .. versionadded:: 0.5
-
-   Currently supported languages by Sphinx are:
-
-   * ``bn`` -- Bengali
-   * ``ca`` -- Catalan
-   * ``cs`` -- Czech
-   * ``da`` -- Danish
-   * ``de`` -- German
-   * ``en`` -- English
-   * ``es`` -- Spanish
-   * ``fa`` -- Iranian
-   * ``fi`` -- Finnish
-   * ``fr`` -- French
-   * ``hr`` -- Croatian
-   * ``it`` -- Italian
-   * ``lt`` -- Lithuanian
-   * ``nl`` -- Dutch
-   * ``pl`` -- Polish
-   * ``pt_BR`` -- Brazilian Portuguese
-   * ``ru`` -- Russian
-   * ``sl`` -- Slovenian
-   * ``sv`` -- Swedish
-   * ``tr`` -- Turkish
-   * ``uk_UA`` -- Ukrainian
-   * ``zh_CN`` -- Simplified Chinese
-   * ``zh_TW`` -- Traditional Chinese
-
-.. confval:: locale_dirs
-
-   .. versionadded:: 0.5
-
-   Directories in which to search for additional message catalogs (see
-   :confval:`language`), relative to the source directory.  The directories on
-   this path are searched by the standard :mod:`gettext` module.
-
-   Internal messages are fetched from a text domain of ``sphinx``; so if you
-   add the directory :file:`./locale` to this settting, the message catalogs
-   (compiled from ``.po`` format using :program:`msgfmt`) must be in
-   :file:`./locale/{language}/LC_MESSAGES/sphinx.mo`.  The text domain of
-   individual documents depends on their docname if they are top-level project
-   files and on their base directory otherwise.
-
-   The default is ``[]``.
-
-
-.. _html-options:
-
-Options for HTML output
------------------------
-
-These options influence HTML as well as HTML Help output, and other builders
-that use Sphinx' HTMLWriter class.
-
-.. XXX document html_context
-
-.. confval:: html_theme
-
-   The "theme" that the HTML output should use.  See the :doc:`section about
-   theming <theming>`.  The default is ``'default'``.
-
-   .. versionadded:: 0.6
-
-.. confval:: html_theme_options
-
-   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 :ref:`this section <builtin-themes>`.
-
-   .. versionadded:: 0.6
-
-.. confval:: html_theme_path
-
-   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.
-
-   .. versionadded:: 0.6
-
-.. confval:: html_style
-
-   The style sheet to use for HTML pages.  A file of that name must exist either
-   in Sphinx' :file:`static/` path, or in one of the custom paths given in
-   :confval:`html_static_path`.  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 ``@import`` to import the theme's stylesheet.
-
-.. confval:: html_title
-
-   The "title" for HTML documentation generated with Sphinx' own templates.
-   This is appended to the ``<title>`` tag of individual pages, and used in the
-   navigation bar as the "topmost" element.  It defaults to :samp:`'{<project>}
-   v{<revision>} documentation'`, where the placeholders are replaced by the
-   config values of the same name.
-
-.. confval:: html_short_title
-
-   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
-   :confval:`html_title`.
-
-   .. versionadded:: 0.4
-
-.. confval:: html_logo
-
-   If given, this must be the name of an image file that is the logo of the
-   docs.  It is placed at the top of the sidebar; its width should therefore not
-   exceed 200 pixels.  Default: ``None``.
-
-   .. versionadded:: 0.4.1
-      The image file will be copied to the ``_static`` directory of the output
-      HTML, so an already existing file with that name will be overwritten.
-
-.. confval:: html_favicon
-
-   If given, this must be the name of an image file (within the static path, see
-   below) that is the favicon of the docs.  Modern browsers use this as icon for
-   tabs, windows and bookmarks.  It should be a Windows-style icon file
-   (``.ico``), which is 16x16 or 32x32 pixels large.  Default: ``None``.
-
-   .. versionadded:: 0.4
-
-.. confval:: html_static_path
-
-   A list of paths that contain custom static files (such as style sheets or
-   script files).  Relative paths are taken as relative to the configuration
-   directory.  They are copied to the output directory after the theme's static
-   files, so a file named :file:`default.css` will overwrite the theme's
-   :file:`default.css`.
-
-   .. versionchanged:: 0.4
-      The paths in :confval:`html_static_path` can now contain subdirectories.
-
-   .. versionchanged:: 1.0
-      The entries in :confval:`html_static_path` can now be single files.
-
-.. confval:: html_last_updated_fmt
-
-   If this is not the empty string, a 'Last updated on:' timestamp is inserted
-   at every page bottom, using the given :func:`strftime` format.  Default is
-   ``'%b %d, %Y'`` (or a locale-dependent equivalent).
-
-.. confval:: html_use_smartypants
-
-   If true, *SmartyPants* will be used to convert quotes and dashes to
-   typographically correct entities.  Default: ``True``.
-
-.. confval:: html_add_permalinks
-
-   Sphinx will add "permalinks" for each heading and description environment as
-   paragraph signs that become visible when the mouse hovers over them.
-
-   This value determines the text for the permalink; it defaults to ``"¶"``.
-   Set it to ``None`` or the empty string to disable permalinks.
-
-   .. versionadded:: 0.6
-      Previously, this was always activated.
-
-   .. versionchanged:: 1.1
-      This can now be a string to select the actual text of the link.
-      Previously, only boolean values were accepted.
-
-.. confval:: html_sidebars
-
-   Custom sidebar templates, must be a dictionary that maps document names to
-   template names.
-
-   The keys can contain glob-style patterns [1]_, 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.)
-
-   The values can be either lists or single strings.
-
-   * 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.
-
-     The default sidebars (for documents that don't match any pattern) are:
-     ``['localtoc.html', 'relations.html', 'sourcelink.html',
-     'searchbox.html']``.
-
-   * If a value is a single string, it specifies a custom sidebar to be added
-     between the ``'sourcelink.html'`` and ``'searchbox.html'`` entries.  This
-     is for compatibility with Sphinx versions before 1.0.
-
-   Builtin sidebar templates that can be rendered are:
-
-   * **localtoc.html** -- a fine-grained table of contents of the current document
-   * **globaltoc.html** -- a coarse-grained table of contents for the whole
-     documentation set, collapsed
-   * **relations.html** -- two links to the previous and next documents
-   * **sourcelink.html** -- a link to the source of the current document, if
-     enabled in :confval:`html_show_sourcelink`
-   * **searchbox.html** -- the "quick search" box
-
-   Example::
-
-      html_sidebars = {
-         '**': ['globaltoc.html', 'sourcelink.html', 'searchbox.html'],
-         'using/windows': ['windowssidebar.html', 'searchbox.html'],
-      }
-
-   This will render the custom template ``windowssidebar.html`` 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).
-
-   .. versionadded:: 1.0
-      The ability to use globbing keys and to specify multiple sidebars.
-
-   Note that this value only has no effect if the chosen theme does not possess
-   a sidebar, like the builtin **scrolls** and **haiku** themes.
-
-.. confval:: html_additional_pages
-
-   Additional templates that should be rendered to HTML pages, must be a
-   dictionary that maps document names to template names.
-
-   Example::
-
-      html_additional_pages = {
-          'download': 'customdownload.html',
-      }
-
-   This will render the template ``customdownload.html`` as the page
-   ``download.html``.
-
-.. confval:: html_domain_indices
-
-   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
-   ``True``.
-
-   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 ``'py-modindex'``.
-
-   .. versionadded:: 1.0
-
-.. confval:: html_use_modindex
-
-   If true, add a module index to the HTML documents.   Default is ``True``.
-
-   .. deprecated:: 1.0
-      Use :confval:`html_domain_indices`.
-
-.. confval:: html_use_index
-
-   If true, add an index to the HTML documents.  Default is ``True``.
-
-   .. versionadded:: 0.4
-
-.. confval:: html_split_index
-
-   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 ``False``.
-
-   .. versionadded:: 0.4
-
-.. confval:: html_copy_source
-
-   If true, the reST sources are included in the HTML build as
-   :file:`_sources/{name}`.  The default is ``True``.
-
-   .. warning::
-
-      If this config value is set to ``False``, the JavaScript search function
-      will only display the titles of matching documents, and no excerpt from
-      the matching contents.
-
-.. confval:: html_show_sourcelink
-
-   If true (and :confval:`html_copy_source` is true as well), links to the
-   reST sources will be added to the sidebar.  The default is ``True``.
-
-   .. versionadded:: 0.6
-
-.. confval:: html_use_opensearch
-
-   If nonempty, an `OpenSearch <http://opensearch.org>` description file will be
-   output, and all pages will contain a ``<link>`` 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. ``"http://docs.python.org"``.  The
-   default is ``''``.
-
-.. confval:: html_file_suffix
-
-   This is the file name suffix for generated HTML files.  The default is
-   ``".html"``.
-
-   .. versionadded:: 0.4
-
-.. confval:: html_link_suffix
-
-   Suffix for generated links to HTML files.  The default is whatever
-   :confval:`html_file_suffix` is set to; it can be set differently (e.g. to
-   support different web server setups).
-
-   .. versionadded:: 0.6
-
-.. confval:: html_translator_class
-
-   A string with the fully-qualified name of a HTML Translator class, that is, a
-   subclass of Sphinx' :class:`~sphinx.writers.html.HTMLTranslator`, that is used
-   to translate document trees to HTML.  Default is ``None`` (use the builtin
-   translator).
-
-.. confval:: html_show_copyright
-
-   If true, "(C) Copyright ..." is shown in the HTML footer. Default is ``True``.
-
-   .. versionadded:: 1.0
-
-.. confval:: html_show_sphinx
-
-   If true, "Created using Sphinx" is shown in the HTML footer.  Default is
-   ``True``.
-
-   .. versionadded:: 0.4
-
-.. confval:: html_output_encoding
-
-   Encoding of HTML output files. Default is ``'utf-8'``.  Note that this
-   encoding name must both be a valid Python encoding name and a valid HTML
-   ``charset`` value.
-
-   .. versionadded:: 1.0
-
-.. confval:: html_compact_lists
-
-   If true, list items containing only a single paragraph will not be rendered
-   with a ``<p>`` element.  This is standard docutils behavior.  Default:
-   ``True``.
-
-   .. versionadded:: 1.0
-
-.. confval:: html_secnumber_suffix
-
-   Suffix for section numbers.  Default: ``". "``.  Set to ``" "`` to suppress
-   the final dot on section numbers.
-
-   .. versionadded:: 1.0
-
-.. confval:: htmlhelp_basename
-
-   Output file base name for HTML help builder.  Default is ``'pydoc'``.
-
-
-.. _epub-options:
-
-Options for epub output
------------------------
-
-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 `Dublin Core metadata <http://dublincore.org/>`_.
-
-.. confval:: epub_basename
-
-   The basename for the epub file.  It defaults to the :confval:`project` name.
-
-.. confval:: epub_theme
-
-   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 ``'epub'``, a theme designed to
-   save visual space.
-
-.. confval:: epub_title
-
-   The title of the document.  It defaults to the :confval:`html_title` option
-   but can be set independently for epub creation.
-
-.. confval:: epub_author
-
-   The author of the document.  This is put in the Dublin Core metadata.  The
-   default value is ``'unknown'``.
-
-.. confval:: epub_language
-
-   The language of the document.  This is put in the Dublin Core metadata.  The
-   default is the :confval:`language` option or ``'en'`` if unset.
-
-.. confval:: epub_publisher
-
-   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
-   ``'unknown'``.
-
-.. confval:: epub_copyright
-
-   The copyright of the document.  It defaults to the :confval:`copyright`
-   option but can be set independently for epub creation.
-
-.. confval:: epub_identifier
-
-   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
-   ``'unknown'``.
-
-.. confval:: epub_scheme
-
-   The publication scheme for the :confval:`epub_identifier`.  This is put in
-   the Dublin Core metadata.  For published books the scheme is ``'ISBN'``.  If
-   you use the project homepage, ``'URL'`` seems reasonable.  The default value
-   is ``'unknown'``.
-
-.. confval:: epub_uid
-
-   A unique identifier for the document.  This is put in the Dublin Core
-   metadata.  You may use a random string.  The default value is ``'unknown'``.
-
-.. confval:: epub_cover
-
-   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 :file:`content.opf`.  If the
-   template filename is empty, no html cover page is created.  No cover at all
-   is created if the tuple is empty.  Examples::
-
-      epub_cover = ('_static/cover.png', 'epub-cover.html')
-      epub_cover = ('_static/cover.png', '')
-      epub_cover = ()
-
-   The default value is ``()``.
-
-   .. versionadded:: 1.1
-
-.. confval:: epub_pre_files
-
-   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 :file:`toc.ncx`.  Example::
-
-      epub_pre_files = [
-          ('index.html', 'Welcome'),
-      ]
-
-   The default value is ``[]``.
-
-.. confval:: epub_post_files
-
-   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 :file:`toc.ncx`.  The default value is ``[]``.
-
-.. confval:: epub_exclude_files
-
-   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 ``[]``.
-
-.. confval:: epub_tocdepth
-
-   The depth of the table of contents in the file :file:`toc.ncx`.  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.
-
-.. confval:: epub_tocdup
-
-   This flag determines if a toc entry is inserted again at the beginning of
-   it's nested toc listing.  This allows easier navitation to the top of
-   a chapter, but can be confusing because it mixes entries of differnet
-   depth in one list.  The default value is ``True``.
-
-.. _latex-options:
-
-Options for LaTeX output
-------------------------
-
-These options influence LaTeX output.
-
-.. confval:: latex_documents
-
-   This value determines how to group the document tree into LaTeX source files.
-   It must be a list of tuples ``(startdocname, targetname, title, author,
-   documentclass, toctree_only)``, where the items are:
-
-   * *startdocname*: 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 :confval:`master_doc`
-     here.)
-   * *targetname*: file name of the LaTeX file in the output directory.
-   * *title*: LaTeX document title.  Can be empty to use the title of the
-     *startdoc*.  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.
-   * *author*: Author for the LaTeX document.  The same LaTeX markup caveat as
-     for *title* applies.  Use ``\and`` to separate multiple authors, as in:
-     ``'John \and Sarah'``.
-   * *documentclass*: Normally, one of ``'manual'`` or ``'howto'`` (provided by
-     Sphinx).  Other document classes can be given, but they must include the
-     "sphinx" package in order to define Sphinx' custom LaTeX commands.
-     "howto" documents will not get appendices.  Also, howtos will have a simpler
-     title page.
-   * *toctree_only*: Must be ``True`` or ``False``.  If ``True``, the *startdoc*
-     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.
-
-   .. versionadded:: 0.3
-      The 6th item ``toctree_only``.  Tuples with 5 items are still accepted.
-
-.. confval:: latex_logo
-
-   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: ``None``.
-
-.. confval:: latex_use_parts
-
-   If true, the topmost sectioning unit is parts, else it is chapters.  Default:
-   ``False``.
-
-   .. versionadded:: 0.3
-
-.. confval:: latex_appendices
-
-   A list of document names to append as an appendix to all manuals.
-
-.. confval:: latex_domain_indices
-
-   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
-   ``True``.
-
-   This value can be a bool or a list of index names that should be generated,
-   like for :confval:`html_domain_indices`.
-
-   .. versionadded:: 1.0
-
-.. confval:: latex_use_modindex
-
-   If true, add a module index to LaTeX documents.   Default is ``True``.
-
-   .. deprecated:: 1.0
-      Use :confval:`latex_domain_indices`.
-
-.. confval:: latex_show_pagerefs
-
-   If true, add page references after internal references.  This is very useful
-   for printed copies of the manual.  Default is ``False``.
-
-   .. versionadded:: 1.0
-
-.. confval:: latex_show_urls
-
-   If true, add URL addresses after links.  This is very useful for printed
-   copies of the manual.  Default is ``False``.
-
-   .. versionadded:: 1.0
-
-.. confval:: latex_elements
-
-   .. versionadded:: 0.5
-
-   A dictionary that contains LaTeX snippets that override those Sphinx usually
-   puts into the generated ``.tex`` files.
-
-   Keep in mind that backslashes must be doubled in Python string literals to
-   avoid interpretation as escape sequences.
-
-   * Keys that you may want to override include:
-
-     ``'papersize'``
-        Paper size option of the document class (``'a4paper'`` or
-        ``'letterpaper'``), default ``'letterpaper'``.
-     ``'pointsize'``
-        Point size option of the document class (``'10pt'``, ``'11pt'`` or
-        ``'12pt'``), default ``'10pt'``.
-     ``'babel'``
-        "babel" package inclusion, default ``'\\usepackage{babel}'``.
-     ``'fontpkg'``
-        Font package inclusion, default ``'\\usepackage{times}'`` (which uses
-        Times and Helvetica).  You can set this to ``''`` to use the Computer
-        Modern fonts.
-     ``'fncychap'``
-        Inclusion of the "fncychap" package (which makes fancy chapter titles),
-        default ``'\\usepackage[Bjarne]{fncychap}'`` for English documentation,
-        ``'\\usepackage[Sonny]{fncychap}'`` for internationalized docs (because
-        the "Bjarne" style uses numbers spelled out in English).  Other
-        "fncychap" styles you can try include "Lenny", "Glenn", "Conny" and
-        "Rejne".  You can also set this to ``''`` to disable fncychap.
-     ``'preamble'``
-        Additional preamble content, default empty.
-     ``'footer'```
-        Additional footer content (before the indices), default empty.
-
-   * Keys that don't need be overridden unless in special cases are:
-
-     ``'inputenc'``
-        "inputenc" package inclusion, default
-        ``'\\usepackage[utf8]{inputenc}'``.
-     ``'fontenc'``
-        "fontenc" package inclusion, default ``'\\usepackage[T1]{fontenc}'``.
-     ``'maketitle'``
-        "maketitle" call, default ``'\\maketitle'``.  Override if you want to
-        generate a differently-styled title page.
-     ``'tableofcontents'``
-        "tableofcontents" call, default ``'\\tableofcontents'``.  Override if
-        you want to generate a different table of contents or put content
-        between the title page and the TOC.
-     ``'printindex'``
-        "printindex" call, the last thing in the file, default
-        ``'\\printindex'``.  Override if you want to generate the index
-        differently or append some content after the index.
-
-   * Keys that are set by other options and therefore should not be overridden are:
-
-     ``'docclass'``
-     ``'classoptions'``
-     ``'title'``
-     ``'date'``
-     ``'release'``
-     ``'author'``
-     ``'logo'``
-     ``'releasename'``
-     ``'makeindex'``
-     ``'shorthandoff'``
-
-.. confval:: latex_docclass
-
-   A dictionary mapping ``'howto'`` and ``'manual'`` to names of real document
-   classes that will be used as the base for the two Sphinx classes.  Default
-   is to use ``'article'`` for ``'howto'`` and ``'report'`` for ``'manual'``.
-
-   .. versionadded:: 1.0
-
-.. confval:: latex_additional_files
-
-   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 ``latex_elements``.  Image files that are referenced in source
-   files (e.g. via ``.. image::``) are copied automatically.
-
-   You have to make sure yourself that the filenames don't collide with those of
-   any automatically copied files.
-
-   .. versionadded:: 0.6
-
-.. confval:: latex_preamble
-
-   Additional LaTeX markup for the preamble.
-
-   .. deprecated:: 0.5
-      Use the ``'preamble'`` key in the :confval:`latex_elements` value.
-
-.. confval:: latex_paper_size
-
-   The output paper size (``'letter'`` or ``'a4'``).  Default is ``'letter'``.
-
-   .. deprecated:: 0.5
-      Use the ``'papersize'`` key in the :confval:`latex_elements` value.
-
-.. confval:: latex_font_size
-
-   The font size ('10pt', '11pt' or '12pt'). Default is ``'10pt'``.
-
-   .. deprecated:: 0.5
-      Use the ``'pointsize'`` key in the :confval:`latex_elements` value.
-
-
-.. _man-options:
-
-Options for manual page output
-------------------------------
-
-These options influence manual page output.
-
-.. confval:: man_pages
-
-   This value determines how to group the document tree into manual pages.  It
-   must be a list of tuples ``(startdocname, name, description, authors,
-   section)``, where the items are:
-
-   * *startdocname*: 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 :confval:`master_doc`
-     here.)
-   * *name*: 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).
-   * *description*: description of the manual page.  This is used in the NAME
-     section.
-   * *authors*: 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.
-   * *section*: The manual page section.  Used for the output file name as well
-     as in the manual page header.
-
-   .. versionadded:: 1.0
-
-
-.. _texinfo-options:
-
-Options for Texinfo output
---------------------------
-
-These options influence Texinfo output.
-
-.. confval:: texinfo_documents
-
-   This value determines how to group the document tree into Texinfo source
-   files.  It must be a list of tuples ``(startdocname, targetname, title,
-   author, dir_entry, description, category, toctree_only)``, where the items
-   are:
-
-   * *startdocname*: 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
-     :confval:`master_doc` here.)
-   * *targetname*: file name (no extension) of the Texinfo file in the output
-     directory.
-   * *title*: Texinfo document title.  Can be empty to use the title of the
-     *startdoc*.
-   * *author*: Author for the Texinfo document.  Use ``\and`` to separate
-     multiple authors, as in: ``'John \and Sarah'``.
-   * *dir_entry*: The name that will appear in the top-level ``DIR`` menu file.
-   * *description*: Descriptive text to appear in the top-level ``DIR`` menu
-     file.
-   * *category*: Specifies the section which this entry will appear in the
-     top-level ``DIR`` menu file.
-   * *toctree_only*: Must be ``True`` or ``False``.  If ``True``, the *startdoc*
-     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.
-
-   .. versionadded:: 1.1
-
-
-.. confval:: texinfo_appendices
-
-   A list of document names to append as an appendix to all manuals.
-
-   .. versionadded:: 1.1
-
-
-.. confval:: texinfo_elements
-
-   A dictionary that contains Texinfo snippets that override those Sphinx
-   usually puts into the generated ``.texi`` files.
-
-   * Keys that you may want to override include:
-
-     ``'paragraphindent'``
-        Number of spaces to indent the first line of each paragraph, default
-        ``2``.  Specify ``0`` for no indentation.
-
-     ``'exampleindent'``
-        Number of spaces to indent the lines for examples or literal blocks,
-        default ``4``.  Specify ``0`` for no indentation.
-
-     ``'preamble'``
-        Text inserted as is near the beginning of the file.
-
-   * Keys that are set by other options and therefore should not be overridden
-     are:
-
-     ``'filename'``
-     ``'title'``
-     ``'direntry'``
-
-   .. versionadded:: 1.1
-
-
-Options for the linkcheck builder
----------------------------------
-
-.. confval:: linkcheck_ignore
-
-   A list of regular expressions that match URIs that should not be checked
-   when doing a ``linkcheck`` build.  Example::
-
-      linkcheck_ignore = [r'http://localhost:\d+/']
-
-   .. versionadded:: 1.1
-
-
-.. rubric:: Footnotes
-
-.. [1] A note on available globbing syntax: you can use the standard shell
-       constructs ``*``, ``?``, ``[...]`` and ``[!...]`` with the feature that
-       these all don't match slashes.  A double star ``**`` can be used to match
-       any sequence of characters *including* slashes.

File doc/contents.rst

-.. _contents:
-
-Sphinx documentation contents
-=============================
-
-.. toctree::
-   :maxdepth: 2
-
-   intro
-   tutorial
-   invocation
-   rest
-   markup/index
-   domains
-   builders
-   config
-   intl
-   theming
-   templating
-   extensions
-   websupport
-
-   faq
-   glossary
-   changes
-   examples
-
-
-Indices and tables
-==================
-
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
-* :ref:`glossary`

File doc/domains.rst

-.. highlight:: rst
-
-.. _domains:
-
-Sphinx Domains
-==============
-
-.. versionadded:: 1.0
-
-What is a Domain?
------------------
-
-Originally, Sphinx was conceived for a single project, the documentation of the
-Python language.  Shortly afterwards, it was made available for everyone as a
-documentation tool, but the documentation of Python modules remained deeply
-built in -- the most fundamental directives, like ``function``, were designed
-for Python objects.  Since Sphinx has become somewhat popular, interest
-developed in using it for many different purposes: C/C++ projects, JavaScript,
-or even reStructuredText markup (like in this documentation).
-
-While this was always possible, it is now much easier to easily support
-documentation of projects using different programming languages or even ones not
-supported by the main Sphinx distribution, by providing a **domain** for every
-such purpose.
-
-A domain is a collection of markup (reStructuredText :term:`directive`\ s and
-:term:`role`\ s) to describe and link to :term:`object`\ s belonging together,
-e.g. elements of a programming language.  Directive and role names in a domain
-have names like ``domain:name``, e.g. ``py:function``.  Domains can also provide
-custom indices (like the Python Module Index).
-
-Having domains means that there are no naming problems when one set of
-documentation wants to refer to e.g. C++ and Python classes.  It also means that
-extensions that support the documentation of whole new languages are much easier
-to write.
-
-This section describes what the domains that come with Sphinx provide.  The
-domain API is documented as well, in the section :ref:`domain-api`.
-
-
-.. _basic-domain-markup:
-
-Basic Markup
-------------
-
-Most domains provide a number of :dfn:`object description directives`, used to
-describe specific objects provided by modules.  Each directive requires one or
-more signatures to provide basic information about what is being described, and
-the content should be the description.  The basic version makes entries in the
-general index; if no index entry is desired, you can give the directive option
-flag ``:noindex:``.  An example using a Python domain directive::
-
-   .. py:function:: spam(eggs)
-                    ham(eggs)
-
-      Spam or ham the foo.
-
-This describes the two Python functions ``spam`` and ``ham``.  (Note that when
-signatures become too long, you can break them if you add a backslash to lines
-that are continued in the next line.  Example::
-
-   .. py:function:: filterwarnings(action, message='', category=Warning, \
-                                   module='', lineno=0, append=False)
-      :noindex:
-
-(This example also shows how to use the ``:noindex:`` flag.)
-
-The domains also provide roles that link back to these object descriptions.  For
-example, to link to one of the functions described in the example above, you
-could say ::
-
-   The function :py:func:`spam` does a similar thing.
-
-As you can see, both directive and role names contain the domain name and the
-directive name.
-
-.. rubric:: Default Domain
-
-To avoid having to writing the domain name all the time when you e.g. only
-describe Python objects, a default domain can be selected with either the config
-value :confval:`primary_domain` or this directive:
-
-.. rst:directive:: .. default-domain:: name
-
-   Select a new default domain.  While the :confval:`primary_domain` selects a
-   global default, this only has an effect within the same file.
-
-If no other default is selected, the Python domain (named ``py``) is the default
-one, mostly for compatibility with documentation written for older versions of
-Sphinx.
-
-Directives and roles that belong to the default domain can be mentioned without
-giving the domain name, i.e. ::
-
-   .. function:: pyfunc()
-
-      Describes a Python function.
-
-   Reference to :func:`pyfunc`.
-
-
-Cross-referencing syntax
-~~~~~~~~~~~~~~~~~~~~~~~~
-
-For cross-reference roles provided by domains, the same facilities exist as for
-general cross-references.  See :ref:`xref-syntax`.
-
-In short:
-
-* You may supply an explicit title and reference target: ``:role:`title
-  <target>``` will refer to *target*, but the link text will be *title*.
-
-* If you prefix the content with ``!``, no reference/hyperlink will be created.
-
-* If you prefix the content with ``~``, the link text will only be the last
-  component of the target.  For example, ``:py:meth:`~Queue.Queue.get``` will
-  refer to ``Queue.Queue.get`` but only display ``get`` as the link text.
-
-
-The Python Domain
------------------
-
-The Python domain (name **py**) provides the following directives for module
-declarations:
-
-.. rst:directive:: .. py:module:: name
-