
The build configuration file
****************************

The *configuration directory* must contain a file named "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
"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 "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 *Including content
  based on tags*).  Use "tags.has('tag')" to query, "tags.add('tag')"
  and "tags.remove('tag')" to change.


General configuration
=====================

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 "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
   *configuration directory*, use "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 "setup()" function in it.

source_suffix

   The file name extension of source files.  Only files with this
   suffix will be read as sources.  Default is "'.rst'".

source_encoding

   The encoding of all reST source files.  The recommended encoding,
   and the default value, is "'utf-8-sig'".

   New in version 0.5: Previously, Sphinx accepted only UTF-8 encoded
   sources.

master_doc

   The document name of the "master" document, that is, the document
   that contains the root "toctree" directive.  Default is
   "'contents'".

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 "unused_docs")

   * "'library/xml'" -- ignores the "library/xml" directory (replaces
     entry in "exclude_trees")

   * "'library/xml*'" -- ignores all files and directories starting
     with "library/xml"

   * "'**/.svn'" -- ignores all ".svn" directories (replaces entry in
     "exclude_dirnames")

   "exclude_patterns" is also consulted when looking for static files
   in "html_static_path".

   New in version 1.0.

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 since version 1.0: Use "exclude_patterns" instead.

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 "[]".

   New in version 0.4.

   Deprecated since version 1.0: Use "exclude_patterns" instead.

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 "[]".

   New in version 0.5.

   Deprecated since version 1.0: Use "exclude_patterns" instead.

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.

template_bridge

   A string with the fully-qualified name of a callable (or simply a
   class) that returns an instance of "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.)

rst_epilog

   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
      """

   New in version 0.6.

rst_prolog

   A string of reStructuredText that will be included at the beginning
   of every source file that is read.

   New in version 1.0.

primary_domain

   The name of the default *domain*.  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 "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").

   New in version 1.0.

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 "default-role" directive.

   New in version 0.4.

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.

   New in version 0.5.

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.

   New in version 1.0.

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 *-n* command-line switch.

   New in version 1.0.

nitpick_ignore

   A list of "(type, target)" tuples (by default empty) that should be
   ignored when generating warnings in "nitpicky mode".  Note that
   "type" should include the domain name.  An example entry would be
   "('py:func', 'int')".

   New in version 1.1.


Project information
===================

project

   The documented project's name.

copyright

   A copyright statement in the style "'2008, Author Name'".

version

   The major project version, used as the replacement for "|version|".
   For example, for the Python documentation, this may be something
   like "2.6".

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 "version" and
   "release", just set them both to the same value.

today
today_fmt

   These values determine how to format the current date, used as the
   replacement for "|today|".

   * If you set "today" to a non-empty value, it is used.

   * Otherwise, the current time is formatted using "time.strftime()"
     and the format given in "today_fmt".

   The default is no "today" and a "today_fmt" of "'%B %d, %Y'" (or,
   if translation is enabled with "language", am equivalent %format
   for the selected locale).

highlight_language

   The default language to highlight source code in.  The default is
   "'python'".  The value should be a valid Pygments lexer name, see
   *Showing code examples* for more details.

   New in version 0.5.

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.

   Changed in version 0.3: If the value is a fully-qualified name of a
   custom Pygments style class, this is then used as custom style.

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".

add_module_names

   A boolean that decides whether module names are prepended to all
   *object* names (for object types where a "module" of some kind is
   defined), e.g. for "py:function" directives.  Default is "True".

show_authors

   A boolean that decides whether "codeauthor" and "sectionauthor"
   directives produce any output in the built files.

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 "[]".

   New in version 0.6.

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.

   New in version 0.6.

trim_doctest_flags

   If true, doctest flags (comments looking like "# doctest: FLAG,
   ...") at the ends of lines and "<BLANKLINE>" markers are removed
   for all code blocks showing interactive Python sessions (i.e.
   doctests).  Default is true.  See the extension "doctest" for more
   possibilities of including doctests.

   New in version 1.0.

   Changed in version 1.1: Now also removes "<BLANKLINE>".


Options for internationalization
================================

These options influence Sphinx' *Native Language Support*.  See the
documentation on *Internationalization* for details.

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 "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.

   New in version 0.5.

   Currently supported languages by Sphinx are:

   * "bn" -- Bengali

   * "ca" -- Catalan

   * "cs" -- Czech

   * "da" -- Danish

   * "de" -- German

   * "en" -- English

   * "es" -- Spanish

   * "et" -- Estonian

   * "fa" -- Iranian

   * "fi" -- Finnish

   * "fr" -- French

   * "hr" -- Croatian

   * "it" -- Italian

   * "ja" -- Japanese

   * "ko" -- Korean

   * "lt" -- Lithuanian

   * "lv" -- Latvian

   * "ne" -- Nepali

   * "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

locale_dirs

   New in version 0.5.

   Directories in which to search for additional message catalogs (see
   "language"), relative to the source directory.  The directories on
   this path are searched by the standard "gettext" module.

   Internal messages are fetched from a text domain of "sphinx"; so if
   you add the directory "./locale" to this settting, the message
   catalogs (compiled from ".po" format using **msgfmt**) must be in
   "./locale/*language*/LC_MESSAGES/sphinx.mo".  The text domain of
   individual documents depends on "gettext_compact".

   The default is "[]".

gettext_compact

   New in version 1.1.

   If true, a document's text domain is its docname if it is a top-
   level project file and its very base directory otherwise.

   By default, the document "markup/code.rst" ends up in the "markup"
   text domain.  With this option set to "False", it is "markup/code".


Options for HTML output
=======================

These options influence HTML as well as HTML Help output, and other
builders that use Sphinx' HTMLWriter class.

html_theme

   The "theme" that the HTML output should use.  See the *section
   about theming*.  The default is "'default'".

   New in version 0.6.

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 *this section*.

   New in version 0.6.

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.

   New in version 0.6.

html_style

   The style sheet to use for HTML pages.  A file of that name must
   exist either in Sphinx' "static/" path, or in one of the custom
   paths given in "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.

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 "'*<project>* v*<revision>* documentation'", where the
   placeholders are replaced by the config values of the same name.

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 "html_title".

   New in version 0.4.

html_context

   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* command-line option of "sphinx-build".

   New in version 0.5.

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".

   New in version 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.

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".

   New in version 0.4.

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
   "default.css" will overwrite the theme's "default.css".

   Changed in version 0.4: The paths in "html_static_path" can now
   contain subdirectories.

   Changed in version 1.0: The entries in "html_static_path" can now
   be single files.

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 "strftime()" format.
   Default is "'%b %d, %Y'" (or a locale-dependent equivalent).

html_use_smartypants

   If true, *SmartyPants* will be used to convert quotes and dashes to
   typographically correct entities.  Default: "True".

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.

   New in version 0.6: Previously, this was always activated.

   Changed in version 1.1: This can now be a string to select the
   actual text of the link. Previously, only boolean values were
   accepted.

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 "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).

   New in version 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.

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".

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'".

   New in version 1.0.

html_use_modindex

   If true, add a module index to the HTML documents.   Default is
   "True".

   Deprecated since version 1.0: Use "html_domain_indices".

html_use_index

   If true, add an index to the HTML documents.  Default is "True".

   New in version 0.4.

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".

   New in version 0.4.

html_copy_source

   If true, the reST sources are included in the HTML build as
   "_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.

html_show_sourcelink

   If true (and "html_copy_source" is true as well), links to the reST
   sources will be added to the sidebar.  The default is "True".

   New in version 0.6.

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 "''".

html_file_suffix

   This is the file name suffix for generated HTML files.  The default
   is "".html"".

   New in version 0.4.

html_link_suffix

   Suffix for generated links to HTML files.  The default is whatever
   "html_file_suffix" is set to; it can be set differently (e.g. to
   support different web server setups).

   New in version 0.6.

html_translator_class

   A string with the fully-qualified name of a HTML Translator class,
   that is, a subclass of Sphinx' "HTMLTranslator", that is used to
   translate document trees to HTML.  Default is "None" (use the
   builtin translator).

html_show_copyright

   If true, "(C) Copyright ..." is shown in the HTML footer. Default
   is "True".

   New in version 1.0.

html_show_sphinx

   If true, "Created using Sphinx" is shown in the HTML footer.
   Default is "True".

   New in version 0.4.

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.

   New in version 1.0.

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".

   New in version 1.0.

html_secnumber_suffix

   Suffix for section numbers.  Default: "". "".  Set to "" "" to
   suppress the final dot on section numbers.

   New in version 1.0.

html_search_language

   Language to be used for generating the HTML full-text search index.
   This defaults to the global language selected with "language".  If
   there is no support for this language, ""en"" is used which selects
   the English language.

   Support is present for these languages:

   * "en" -- English

   * "ja" -- Japanese

   New in version 1.1.

html_search_options

   A dictionary with options for the search language support, empty by
   default. The meaning of these options depends on the language
   selected.

   The English support has no options.

   The Japanese support has these options:

   * "type" -- "'mecab'" or "'default'" (selects either MeCab or
     TinySegmenter word splitter algorithm)

   * "dic_enc" -- the encoding for the MeCab algorithm

   * "dict" -- the dictionary to use for the MeCab algorithm

   * "lib" -- the library name for finding the MeCab library via
     ctypes if the Python binding is not installed

   New in version 1.1.

htmlhelp_basename

   Output file base name for HTML help builder.  Default is "'pydoc'".


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.

epub_basename

   The basename for the epub file.  It defaults to the "project" name.

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.

epub_title

   The title of the document.  It defaults to the "html_title" option
   but can be set independently for epub creation.

epub_author

   The author of the document.  This is put in the Dublin Core
   metadata.  The default value is "'unknown'".

epub_language

   The language of the document.  This is put in the Dublin Core
   metadata.  The default is the "language" option or "'en'" if unset.

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'".

epub_copyright

   The copyright of the document.  It defaults to the "copyright"
   option but can be set independently for epub creation.

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'".

epub_scheme

   The publication scheme for the "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'".

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'".

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
   "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 "()".

   New in version 1.1.

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 "toc.ncx".
   Example:

      epub_pre_files = [
          ('index.html', 'Welcome'),
      ]

   The default value is "[]".

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 "toc.ncx".  The default value is
   "[]".

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
   "[]".

epub_tocdepth

   The depth of the table of contents in the 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.

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".


Options for LaTeX output
========================

These options influence LaTeX output.

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 "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.

   New in version 0.3: The 6th item "toctree_only".  Tuples with 5
   items are still accepted.

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".

latex_use_parts

   If true, the topmost sectioning unit is parts, else it is chapters.
   Default: "False".

   New in version 0.3.

latex_appendices

   A list of document names to append as an appendix to all manuals.

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 "html_domain_indices".

   New in version 1.0.

latex_use_modindex

   If true, add a module index to LaTeX documents.   Default is
   "True".

   Deprecated since version 1.0: Use "latex_domain_indices".

latex_show_pagerefs

   If true, add page references after internal references.  This is
   very useful for printed copies of the manual.  Default is "False".

   New in version 1.0.

latex_show_urls

   Control whether to display URL addresses.  This is very useful for
   printed copies of the manual.  The setting can have the following
   values:

   * "'no'" -- do not display URLs (default)

   * "'footnote'" -- display URLs in footnotes

   * "'inline'" -- display URLs inline in parentheses

   New in version 1.0.

   Changed in version 1.1: This value is now a string; previously it
   was a boolean value, and a true value selected the "'inline'"
   display.  For backwards compatibility, "True" is still accepted.

latex_elements

   New in version 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'"

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'".

   New in version 1.0.

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.

   New in version 0.6.

latex_preamble

   Additional LaTeX markup for the preamble.

   Deprecated since version 0.5: Use the "'preamble'" key in the
   "latex_elements" value.

latex_paper_size

   The output paper size ("'letter'" or "'a4'").  Default is
   "'letter'".

   Deprecated since version 0.5: Use the "'papersize'" key in the
   "latex_elements" value.

latex_font_size

   The font size ('10pt', '11pt' or '12pt'). Default is "'10pt'".

   Deprecated since version 0.5: Use the "'pointsize'" key in the
   "latex_elements" value.


Options for text output
=======================

These options influence text output.

text_newlines

   Determines which end-of-line character(s) are used in text output.

   * "'unix'": use Unix-style line endings ("\n")

   * "'windows'": use Windows-style line endings ("\r\n")

   * "'native'": use the line ending style of the platform the
     documentation is built on

   Default: "'unix'".

   New in version 1.1.

text_sectionchars

   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.

   The default is "'*=-~"+`'".

   New in version 1.1.


Options for manual page output
==============================

These options influence manual page output.

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 "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.

   New in version 1.0.

man_show_urls

   If true, add URL addresses after links.  Default is "False".

   New in version 1.1.


Options for Texinfo output
==========================

These options influence Texinfo output.

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 "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*.  Inserted as Texinfo markup, so special
     characters like @ and {} will need to be escaped to be inserted
     literally.

   * *author*: Author for the Texinfo document.  Inserted as Texinfo
     markup. Use "@*" to separate multiple authors, as in:
     "'John@*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.

   New in version 1.1.

texinfo_appendices

   A list of document names to append as an appendix to all manuals.

   New in version 1.1.

texinfo_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 "html_domain_indices".

   New in version 1.1.

texinfo_show_urls

   Control how to display URL addresses.

   * "'footnote'" -- display URLs in footnotes (default)

   * "'no'" -- do not display URLs

   * "'inline'" -- display URLs inline in parentheses

   New in version 1.1.

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'"
        Texinfo markup inserted near the beginning of the file.

     "'copying'"
        Texinfo markup inserted within the "@copying" block and
        displayed after the title.  The default value consists of a
        simple title page identifying the project.

   * Keys that are set by other options and therefore should not be
     overridden are:

     "'author'" "'body'" "'date'" "'direntry'" "'filename'"
     "'project'" "'release'" "'title'" "'direntry'"

   New in version 1.1.


Options for the linkcheck builder
=================================

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+/']

   New in version 1.1.

linkcheck_timeout

   A timeout value, in seconds, for the linkcheck builder.  **Only
   works in Python 2.6 and higher.**  The default is to use Python's
   global socket timeout.

   New in version 1.1.

linkcheck_workers

   The number of worker threads to use when checking links.  Default
   is 5 threads.

   New in version 1.1.

-[ 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.
