merge with 1.0

1 files changed, 272 insertions, 55 deletions

diff --git a/doc/config.rst b/doc/config.rst
index 80464768..a1f550dd 100644
--- a/doc/config.rst
+++ b/doc/config.rst
@@ -143,20 +143,6 @@ General configuration
    .. deprecated:: 1.0
       Use :confval:`exclude_patterns` instead.
 
-.. confval:: locale_dirs
-
-   .. versionadded:: 0.5
-
-   Directories in which to search for additional Sphinx message catalogs (see
-   :confval:`language`), relative to the source directory.  The directories on
-   this path are searched by the standard :mod:`gettext` module for 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 default is ``[]``.
-
 .. confval:: templates_path
 
    A list of paths that contain extra templates (or templates that overwrite
@@ -272,39 +258,6 @@ Project information
    If you don't need the separation provided between :confval:`version` and
    :confval:`release`, just set them both to the same value.
 
-.. confval:: language
-
-   The code for the language the docs are written in.  Any text automatically
-   generated by Sphinx will be in that language.  Also, in the LaTeX builder, a
-   suitable language will be selected as an option for the *Babel* package.
-   Default is ``None``, which means that no translation will be done.
-
-   .. versionadded:: 0.5
-
-   Currently supported languages are:
-
-   * ``bn`` -- Bengali
-   * ``ca`` -- Catalan
-   * ``cs`` -- Czech
-   * ``da`` -- Danish
-   * ``de`` -- German
-   * ``en`` -- English
-   * ``es`` -- Spanish
-   * ``fi`` -- Finnish
-   * ``fr`` -- French
-   * ``hr`` -- Croatian
-   * ``it`` -- Italian
-   * ``lt`` -- Lithuanian
-   * ``nl`` -- Dutch
-   * ``pl`` -- Polish
-   * ``pt_BR`` -- Brazilian Portuguese
-   * ``ru`` -- Russian
-   * ``sl`` -- Slovenian
-   * ``tr`` -- Turkish
-   * ``uk_UA`` -- Ukrainian
-   * ``zh_CN`` -- Simplified Chinese
-   * ``zh_TW`` -- Traditional Chinese
-
 .. confval:: today
              today_fmt
 
@@ -380,6 +333,69 @@ Project information
    .. 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
@@ -483,13 +499,19 @@ that use Sphinx' HTMLWriter class.
 
 .. confval:: html_add_permalinks
 
-   If true, Sphinx will add "permalinks" for each heading and description
-   environment as paragraph signs that become visible when the mouse hovers over
-   them.  Default: ``True``.
+   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
@@ -672,6 +694,38 @@ that use Sphinx' HTMLWriter class.
 
    .. versionadded:: 1.0
 
+.. confval:: html_search_language
+
+   Language to be used for generating the HTML full-text search index.  This
+   defaults to the global language selected with :confval:`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
+
+   .. versionadded:: 1.1
+
+.. confval:: 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
+
+   .. versionadded:: 1.1
+
 .. confval:: htmlhelp_basename
 
    Output file base name for HTML help builder.  Default is ``'pydoc'``.
@@ -743,6 +797,22 @@ the `Dublin Core metadata <http://dublincore.org/>`_.
    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
@@ -780,6 +850,7 @@ the `Dublin Core metadata <http://dublincore.org/>`_.
    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
@@ -862,10 +933,18 @@ These options influence LaTeX output.
 
 .. confval:: latex_show_urls
 
-   If true, add URL addresses after links.  This is very useful for printed
-   copies of the manual.  Default is ``False``.
+   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
 
    .. versionadded:: 1.0
+   .. versionchanged:: 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.
 
 .. confval:: latex_elements
 
@@ -978,6 +1057,37 @@ These options influence LaTeX output.
       Use the ``'pointsize'`` key in the :confval:`latex_elements` value.
 
 
+.. _text-options:
+
+Options for text output
+-----------------------
+
+These options influence text output.
+
+.. confval:: 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'``.
+
+   .. versionadded:: 1.1
+
+.. confval:: 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 ``'*=-~"+`'``.
+
+   .. versionadded:: 1.1
+
+
 .. _man-options:
 
 Options for manual page output
@@ -1000,14 +1110,121 @@ These options influence manual page output.
      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.
+   * *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
 
+.. confval:: man_show_urls
+
+   If true, add URL addresses after links.  Default is ``False``.
+
+   .. versionadded:: 1.1
+
+
+.. _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
+
+.. confval:: 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.
+
+   .. versionadded:: 1.1
+
+.. confval:: linkcheck_workers
+
+   The number of worker threads to use when checking links.  Default is 5
+   threads.
+
+   .. versionadded:: 1.1
+
 
 .. rubric:: Footnotes