Merge pull request #5643 from stephenfin/doc-rework

Doc rework (user guide, part 5)

doc/contents.rst

@@ -14,16 +14,17 @@ Sphinx documentation contents
    usage/configuration
    usage/builders/index
    usage/extensions/index
+   usage/theming
+   usage/advanced/intl
+   usage/advanced/setuptools
+   usage/advanced/websupport/index
 
    intro
    man/index
-   intl
    theming
-   setuptools
    templating
    latex
    extdev/index
-   websupport
 
    faq
    glossary

doc/faq.rst

@@ -20,7 +20,7 @@ How do I...
    the :rst:dir:`toctree` directive where you want to start numbering.
 
 ... customize the look of the built HTML files?
-   Use themes, see :doc:`theming`.
+   Use themes, see :doc:`/usage/theming`.
 
 ... add global substitutions or includes?
    Add them in the :confval:`rst_prolog` or :confval:`rst_epilog` config value.

doc/theming.rst

@@ -5,6 +5,12 @@ HTML theming support
 
 .. versionadded:: 0.6
 
+.. note::
+
+   This document provides information about creating your own theme. If you
+   simply wish to use a pre-existing HTML themes, refer to
+   :doc:`/usage/theming`.
+
 Sphinx supports changing the appearance of its HTML output via *themes*.  A
 theme is a collection of HTML templates, stylesheet(s) and other static files.
 Additionally, it has a configuration file which specifies from which theme to
@@ -15,265 +21,13 @@ Themes are meant to be project-unaware, so they can be used for different
 projects without change.
 
 
-Using a theme
--------------
-
-Using an existing theme is easy.  If the theme is builtin to Sphinx, you only
-need to set the :confval:`html_theme` config value.  With the
-:confval:`html_theme_options` config value you can set theme-specific options
-that change the look and feel.  For example, you could have the following in
-your :file:`conf.py`::
-
-    html_theme = "classic"
-    html_theme_options = {
-        "rightsidebar": "true",
-        "relbarbgcolor": "black"
-    }
-
-That would give you the classic theme, but with a sidebar on the right side and
-a black background for the relation bar (the bar with the navigation links at
-the page's top and bottom).
-
-If the theme does not come with Sphinx, it can be in two static forms: either a
-directory (containing :file:`theme.conf` and other needed files), or a zip file
-with the same contents.  Either of them must be put where Sphinx can find it;
-for this there is the config value :confval:`html_theme_path`.  It gives a list
-of directories, relative to the directory containing :file:`conf.py`, that can
-contain theme directories or zip files.  For example, if you have a theme in the
-file :file:`blue.zip`, you can put it right in the directory containing
-:file:`conf.py` and use this configuration::
-
-    html_theme = "blue"
-    html_theme_path = ["."]
-
-The third form is a python package.  If a theme you want to use is distributed
-as a python package, you can use it after installing
-
-.. code-block:: bash
-
-    # installing theme package
-    $ pip install sphinxjp.themes.dotted
-
-    # use it in your conf.py
-    html_theme = "dotted"
-
-
-.. _builtin-themes:
-
-Builtin themes
---------------
-
-.. cssclass:: longtable
-
-+--------------------+--------------------+
-| **Theme overview** |                    |
-+--------------------+--------------------+
-| |alabaster|        | |classic|          |
-|                    |                    |
-| *alabaster*        | *classic*          |
-+--------------------+--------------------+
-| |sphinxdoc|        | |scrolls|          |
-|                    |                    |
-| *sphinxdoc*        | *scrolls*          |
-+--------------------+--------------------+
-| |agogo|            | |traditional|      |
-|                    |                    |
-| *agogo*            | *traditional*      |
-+--------------------+--------------------+
-| |nature|           | |haiku|            |
-|                    |                    |
-| *nature*           | *haiku*            |
-+--------------------+--------------------+
-| |pyramid|          | |bizstyle|         |
-|                    |                    |
-| *pyramid*          | *bizstyle*         |
-+--------------------+--------------------+
-
-.. |alabaster|        image:: themes/alabaster.png
-.. |classic|          image:: themes/classic.png
-.. |sphinxdoc|        image:: themes/sphinxdoc.png
-.. |scrolls|          image:: themes/scrolls.png
-.. |agogo|            image:: themes/agogo.png
-.. |traditional|      image:: themes/traditional.png
-.. |nature|           image:: themes/nature.png
-.. |haiku|            image:: themes/haiku.png
-.. |pyramid|          image:: themes/pyramid.png
-.. |bizstyle|         image:: themes/bizstyle.png
-
-Sphinx comes with a selection of themes to choose from.
-
-.. cssclass:: clear
-
-These themes are:
-
-* **basic** -- This is a basically unstyled layout used as the base for the
-  other themes, and usable as the base for custom themes as well.  The HTML
-  contains all important elements like sidebar and relation bar.  There are
-  these options (which are inherited by the other themes):
-
-  - **nosidebar** (true or false): Don't include the sidebar.  Defaults to
-    ``False``.
-
-  - **sidebarwidth** (int or str): Width of the sidebar in pixels.
-    This can be an int, which is interpreted as pixels or a valid CSS
-    dimension string such as '70em' or '50%'.  Defaults to 230 pixels.
-
-  - **body_min_width** (int or str): Minimal width of the document body.
-    This can be an int, which is interpreted as pixels or a valid CSS
-    dimension string such as '70em' or '50%'. Use 0 if you don't want
-    a width limit. Defaults may depend on the theme (often 450px).
-
-  - **body_max_width** (int or str): Maximal width of the document body.
-    This can be an int, which is interpreted as pixels or a valid CSS
-    dimension string such as '70em' or '50%'. Use 'none' if you don't
-    want a width limit. Defaults may depend on the theme (often 800px).
-
-* **alabaster** -- `Alabaster theme`_ is a modified "Kr" Sphinx theme from @kennethreitz
-  (especially as used in his Requests project), which was itself originally based on
-  @mitsuhiko's theme used for Flask & related projects.
-  Check out at its `installation page`_ how to set up properly
-  :confval:`html_sidebars` for its use.
-
-  .. _Alabaster theme: https://pypi.org/project/alabaster/
-  .. _installation page: https://alabaster.readthedocs.io/en/latest/installation.html
-
-* **classic** -- This is the classic theme, which looks like `the Python 2
-  documentation <https://docs.python.org/2/>`_.  It can be customized via
-  these options:
-
-  - **rightsidebar** (true or false): Put the sidebar on the right side.
-    Defaults to ``False``.
-
-  - **stickysidebar** (true or false): Make the sidebar "fixed" so that it
-    doesn't scroll out of view for long body content.  This may not work well
-    with all browsers.  Defaults to ``False``.
-
-  - **collapsiblesidebar** (true or false): Add an *experimental* JavaScript
-    snippet that makes the sidebar collapsible via a button on its side.
-    Defaults to ``False``.
-
-  - **externalrefs** (true or false): Display external links differently from
-    internal links.  Defaults to ``False``.
-
-  There are also various color and font options that can change the color scheme
-  without having to write a custom stylesheet:
-
-  - **footerbgcolor** (CSS color): Background color for the footer line.
-  - **footertextcolor** (CSS color): Text color for the footer line.
-  - **sidebarbgcolor** (CSS color): Background color for the sidebar.
-  - **sidebarbtncolor** (CSS color): Background color for the sidebar collapse
-    button (used when *collapsiblesidebar* is ``True``).
-  - **sidebartextcolor** (CSS color): Text color for the sidebar.
-  - **sidebarlinkcolor** (CSS color): Link color for the sidebar.
-  - **relbarbgcolor** (CSS color): Background color for the relation bar.
-  - **relbartextcolor** (CSS color): Text color for the relation bar.
-  - **relbarlinkcolor** (CSS color): Link color for the relation bar.
-  - **bgcolor** (CSS color): Body background color.
-  - **textcolor** (CSS color): Body text color.
-  - **linkcolor** (CSS color): Body link color.
-  - **visitedlinkcolor** (CSS color): Body color for visited links.
-  - **headbgcolor** (CSS color): Background color for headings.
-  - **headtextcolor** (CSS color): Text color for headings.
-  - **headlinkcolor** (CSS color): Link color for headings.
-  - **codebgcolor** (CSS color): Background color for code blocks.
-  - **codetextcolor** (CSS color): Default text color for code blocks, if not
-    set differently by the highlighting style.
-
-  - **bodyfont** (CSS font-family): Font for normal text.
-  - **headfont** (CSS font-family): Font for headings.
-
-* **sphinxdoc** -- The theme originally used by this documentation. It features
-  a sidebar on the right side. There are currently no options beyond
-  *nosidebar* and *sidebarwidth*.
-
-  .. note::
-
-    The Sphinx documentation now uses
-    `an adjusted version of the sphinxdoc theme
-    <https://github.com/sphinx-doc/sphinx/tree/master/doc/_themes/sphinx13>`_.
-
-* **scrolls** -- A more lightweight theme, based on `the Jinja documentation
-  <http://jinja.pocoo.org/>`_.  The following color options are available:
-
-  - **headerbordercolor**
-  - **subheadlinecolor**
-  - **linkcolor**
-  - **visitedlinkcolor**
-  - **admonitioncolor**
-
-* **agogo** -- A theme created by Andi Albrecht.  The following options are
-  supported:
-
-  - **bodyfont** (CSS font family): Font for normal text.
-  - **headerfont** (CSS font family): Font for headings.
-  - **pagewidth** (CSS length): Width of the page content, default 70em.
-  - **documentwidth** (CSS length): Width of the document (without sidebar),
-    default 50em.
-  - **sidebarwidth** (CSS length): Width of the sidebar, default 20em.
-  - **bgcolor** (CSS color): Background color.
-  - **headerbg** (CSS value for "background"): background for the header area,
-    default a grayish gradient.
-  - **footerbg** (CSS value for "background"): background for the footer area,
-    default a light gray gradient.
-  - **linkcolor** (CSS color): Body link color.
-  - **headercolor1**, **headercolor2** (CSS color): colors for <h1> and <h2>
-    headings.
-  - **headerlinkcolor** (CSS color): Color for the backreference link in
-    headings.
-  - **textalign** (CSS *text-align* value): Text alignment for the body, default
-    is ``justify``.
-
-* **nature** -- A greenish theme.  There are currently no options beyond
-  *nosidebar* and *sidebarwidth*.
-
-* **pyramid** -- A theme from the Pyramid web framework project, designed by
-  Blaise Laflamme.  There are currently no options beyond *nosidebar* and
-  *sidebarwidth*.
-
-* **haiku** -- A theme without sidebar inspired by the `Haiku OS user guide
-  <https://www.haiku-os.org/docs/userguide/en/contents.html>`_.  The following
-  options are supported:
-
-  - **full_logo** (true or false, default ``False``): If this is true, the
-    header will only show the :confval:`html_logo`.  Use this for large logos.
-    If this is false, the logo (if present) will be shown floating right, and
-    the documentation title will be put in the header.
-  - **textcolor**, **headingcolor**, **linkcolor**, **visitedlinkcolor**,
-    **hoverlinkcolor** (CSS colors): Colors for various body elements.
-
-* **traditional** -- A theme resembling the old Python documentation.  There are
-  currently no options beyond *nosidebar* and *sidebarwidth*.
-
-* **epub** -- A theme for the epub builder.  This theme tries to save visual
-  space which is a sparse resource on ebook readers.  The following options
-  are supported:
-
-  - **relbar1** (true or false, default ``True``): If this is true, the
-    `relbar1` block is inserted in the epub output, otherwise it is omitted.
-  - **footer**  (true or false, default ``True``): If this is true, the
-    `footer` block is inserted in the epub output, otherwise it is omitted.
-
-- **bizstyle** -- A simple bluish theme. The following options are supported
-  beyond *nosidebar* and *sidebarwidth*:
-
-  - **rightsidebar** (true or false): Put the sidebar on the right side.
-    Defaults to ``False``.
-
-.. versionadded:: 1.3
-   'alabaster', 'sphinx_rtd_theme' and 'bizstyle' theme.
-
-.. versionchanged:: 1.3
-   The 'default' theme has been renamed to 'classic'. 'default' is still
-   available, however it will emit a notice that it is an alias for the new
-   'alabaster' theme.
-
 Creating themes
 ---------------
 
-As said, themes are either a directory or a zipfile (whose name is the theme
-name), containing the following:
+Themes take the form of either a directory or a zipfile (whose name is the
+theme name), containing the following:
 
-* A :file:`theme.conf` file, see below.
+* A :file:`theme.conf` file.
 * HTML templates, if needed.
 * A ``static/`` directory containing any static files that will be copied to the
   output static directory on build.  These can be images, styles, script files.
@@ -318,16 +72,17 @@ Python :mod:`ConfigParser` module) and has the following structure:
 .. versionadded:: 1.7
    sidebar settings
 
+
 .. _distribute-your-theme:
 
-Distribute your theme as a python package
+Distribute your theme as a Python package
 -----------------------------------------
 
-As a way to distribute your theme, you can use python package.  Python package
+As a way to distribute your theme, you can use Python package.  Python package
 brings to users easy setting up ways.
 
-To distribute your theme as a python package, please define an entry point
-called ``sphinx.html_themes`` in your setup.py file, and write a ``setup()``
+To distribute your theme as a Python package, please define an entry point
+called ``sphinx.html_themes`` in your ``setup.py`` file, and write a ``setup()``
 function to register your themes using ``add_html_theme()`` API in it::
 
     # 'setup.py'
@@ -347,9 +102,8 @@ function to register your themes using ``add_html_theme()`` API in it::
     def setup(app):
         app.add_html_theme('name_of_theme', path.abspath(path.dirname(__file__)))
 
-
-If your theme package contains two or more themes, please call ``add_html_theme()``
-twice or more.
+If your theme package contains two or more themes, please call
+``add_html_theme()`` twice or more.
 
 .. versionadded:: 1.2
    'sphinx_themes' entry_points feature.
@@ -360,8 +114,9 @@ twice or more.
 .. versionadded:: 1.6
    ``sphinx.html_themes`` entry_points feature.
 
+
 Templating
-~~~~~~~~~~
+----------
 
 The :doc:`guide to templating <templating>` is helpful if you want to write your
 own templates.  What is important to keep in mind is the order in which Sphinx
@@ -376,7 +131,6 @@ name as an explicit directory: ``{% extends "basic/layout.html" %}``.  From a
 user ``templates_path`` template, you can still use the "exclamation mark"
 syntax as described in the templating document.
 
-
 Static templates
 ~~~~~~~~~~~~~~~~
 
@@ -393,40 +147,6 @@ templating to put the color options into the stylesheet.  When a documentation
 is built with the classic theme, the output directory will contain a
 ``_static/classic.css`` file where all template tags have been processed.
 
-
 .. [1] It is not an executable Python file, as opposed to :file:`conf.py`,
        because that would pose an unnecessary security risk if themes are
        shared.
-
-Third Party Themes
-------------------
-
-.. cssclass:: longtable
-
-+--------------------+--------------------+
-| **Theme overview** |                    |
-+--------------------+--------------------+
-| |sphinx_rtd_theme| |                    |
-|                    |                    |
-| *sphinx_rtd_theme* |                    |
-+--------------------+--------------------+
-
-.. |sphinx_rtd_theme| image:: themes/sphinx_rtd_theme.png
-
-* **sphinx_rtd_theme** -- `Read the Docs Sphinx Theme`_.
-  This is a mobile-friendly sphinx theme that was made for readthedocs.org.
-  View a working demo over on readthedocs.org. You can get install and options
-  information at `Read the Docs Sphinx Theme`_ page.
-
-  .. _Read the Docs Sphinx Theme: https://pypi.org/project/sphinx_rtd_theme/
-
-  .. versionchanged:: 1.4
-     **sphinx_rtd_theme** has become optional.
-
-
-Besides this, there are a lot of third party themes.  You can find them on
-PyPI__, GitHub__, sphinx-themes.org__ and so on.
-
-.. __: https://pypi.org/search/?q=&o=&c=Framework+%3A%3A+Sphinx+%3A%3A+Theme
-.. __: https://github.com/search?utf8=%E2%9C%93&q=sphinx+theme&type=
-.. __: https://sphinx-themes.org/

doc/usage/advanced/intl.rst

@@ -9,7 +9,7 @@ Complementary to translations provided for Sphinx-generated messages such as
 navigation bars, Sphinx provides mechanisms facilitating *document* translations
 in itself.  See the :ref:`intl-options` for details on configuration.
 
-.. figure:: translation.png
+.. figure:: /_static/translation.png
    :width: 100%
 
    Workflow visualization of translations in Sphinx.  (The stick-figure is taken
@@ -46,14 +46,14 @@ They can be delivered to translators which will transform them to ``.po`` files
 --- so called **message catalogs** --- containing a mapping from the original
 messages to foreign-language strings.
 
-Gettext compiles them into a binary format known as **binary catalogs** through
-:program:`msgfmt` for efficiency reasons.  If you make these files discoverable
-with :confval:`locale_dirs` for your :confval:`language`, Sphinx will pick them
-up automatically.
+*gettext* compiles them into a binary format known as **binary catalogs**
+through :program:`msgfmt` for efficiency reasons.  If you make these files
+discoverable with :confval:`locale_dirs` for your :confval:`language`, Sphinx
+will pick them up automatically.
 
 An example: you have a document ``usage.rst`` in your Sphinx project.  The
-gettext builder will put its messages into ``usage.pot``.  Imagine you have
-Spanish translations [2]_ on your hands in ``usage.po`` --- for your builds to
+*gettext* builder will put its messages into ``usage.pot``.  Imagine you have
+Spanish translations [2]_ stored in ``usage.po`` --- for your builds to
 be translated you need to follow these instructions:
 
 * Compile your message catalog to a locale directory, say ``locale``, so it
@@ -63,7 +63,8 @@ be translated you need to follow these instructions:
         msgfmt "usage.po" -o "locale/es/LC_MESSAGES/usage.mo"
 
 * Set :confval:`locale_dirs` to ``["locale/"]``.
-* Set :confval:`language` to ``es`` (also possible via :option:`-D <sphinx-build -D>`).
+* Set :confval:`language` to ``es`` (also possible via
+  :option:`-D <sphinx-build -D>`).
 * Run your desired build.
 
 
@@ -71,117 +72,124 @@ Translating with sphinx-intl
 ----------------------------
 
 Quick guide
-^^^^^^^^^^^
+~~~~~~~~~~~
 
-`sphinx-intl`_ is a useful tool to work with Sphinx translation flow.
-This section describe an easy way to translate with sphinx-intl.
+`sphinx-intl`_ is a useful tool to work with Sphinx translation flow.  This
+section describe an easy way to translate with *sphinx-intl*.
 
-#. Install `sphinx-intl`_ by :command:`pip install sphinx-intl`.
+#. Install `sphinx-intl`_.
 
-#. Add configurations to your `conf.py`::
+   .. code-block:: console
+
+      $ pip install sphinx-intl
+
+#. Add configurations to ``conf.py``.
+
+   ::
 
       locale_dirs = ['locale/']   # path is example but recommended.
       gettext_compact = False     # optional.
 
-   This case-study assumes that :confval:`locale_dirs` is set to 'locale/' and
-   :confval:`gettext_compact` is set to `False` (the Sphinx document is
+   This case-study assumes that :confval:`locale_dirs` is set to ``locale/`` and
+   :confval:`gettext_compact` is set to ``False`` (the Sphinx document is
    already configured as such).
 
-#. Extract document's translatable messages into pot files:
+#. Extract translatable messages into pot files.
 
    .. code-block:: console
 
       $ make gettext
 
-   As a result, many pot files are generated under ``_build/gettext``
-   directory.
+   The generated pot files will be placed in the ``_build/gettext`` directory.
 
-#. Setup/Update your `locale_dir`:
+#. Generate po files.
+
+   We'll use the pot files generated in the above step.
 
    .. code-block:: console
 
       $ sphinx-intl update -p _build/gettext -l de -l ja
 
-   Done. You got these directories that contain po files:
+   Once completed, the generated po files will be placed in the below
+   directories:
 
-   * `./locale/de/LC_MESSAGES/`
-   * `./locale/ja/LC_MESSAGES/`
+   * ``./locale/de/LC_MESSAGES/``
+   * ``./locale/ja/LC_MESSAGES/``
 
-#. Translate your po files under `./locale/<lang>/LC_MESSAGES/`.
+#. Translate po files.
 
-#. make translated document.
+   AS noted above, these are located in the ``./locale/<lang>/LC_MESSAGES``
+   directory.  An example of one such file, from Sphinx, ``builders.po``, is
+   given below.
+
+   .. code-block:: po
+
+      # a5600c3d2e3d48fc8c261ea0284db79b
+      #: ../../builders.rst:4
+      msgid "Available builders"
+      msgstr "<FILL HERE BY TARGET LANGUAGE>"
+
+   Another case, msgid is multi-line text and contains reStructuredText syntax:
+
+   .. code-block:: po
+
+      # 302558364e1d41c69b3277277e34b184
+      #: ../../builders.rst:9
+      msgid ""
+      "These are the built-in Sphinx builders. More builders can be added by "
+      ":ref:`extensions <extensions>`."
+      msgstr ""
+      "FILL HERE BY TARGET LANGUAGE FILL HERE BY TARGET LANGUAGE FILL HERE "
+      "BY TARGET LANGUAGE :ref:`EXTENSIONS <extensions>` FILL HERE."
+
+   Please be careful not to break reST notation.  Most po-editors will help you
+   with that.
+
+#. Build translated document.
 
    You need a :confval:`language` parameter in ``conf.py`` or you may also
-   specify the parameter on the command line (for BSD/GNU make):
+   specify the parameter on the command line.
+
+   For for BSD/GNU make, run:
 
    .. code-block:: console
 
       $ make -e SPHINXOPTS="-D language='de'" html
 
-   command line (for Windows cmd.exe):
+   For Windows :command:`cmd.exe`, run:
 
    .. code-block:: console
 
       > set SPHINXOPTS=-D language=de
       > .\make.bat html
 
-   command line (for PowerShell):
+   For PowerShell, run:
 
    .. code-block:: console
 
       > Set-Item env:SPHINXOPTS "-D language=de"
       > .\make.bat html
 
-
 Congratulations! You got the translated documentation in the ``_build/html``
 directory.
 
 .. versionadded:: 1.3
 
-   sphinx-build that is invoked by make command will build po files into mo files.
-
-   If you are using 1.2.x or earlier, please invoke ``sphinx-intl build`` command
-   before make command.
+   :program:`sphinx-build` that is invoked by make command will build po files
+   into mo files.
 
+   If you are using 1.2.x or earlier, please invoke :command:`sphinx-intl build`
+   command before :command:`make` command.
 
 Translating
-^^^^^^^^^^^
-
-Translate po file under ``./locale/de/LC_MESSAGES`` directory.
-The case of builders.po file for sphinx document:
-
-.. code-block:: po
-
-   # a5600c3d2e3d48fc8c261ea0284db79b
-   #: ../../builders.rst:4
-   msgid "Available builders"
-   msgstr "<FILL HERE BY TARGET LANGUAGE>"
-
-Another case, msgid is multi-line text and contains reStructuredText
-syntax:
-
-.. code-block:: po
-
-   # 302558364e1d41c69b3277277e34b184
-   #: ../../builders.rst:9
-   msgid ""
-   "These are the built-in Sphinx builders. More builders can be added by "
-   ":ref:`extensions <extensions>`."
-   msgstr ""
-   "FILL HERE BY TARGET LANGUAGE FILL HERE BY TARGET LANGUAGE FILL HERE "
-   "BY TARGET LANGUAGE :ref:`EXTENSIONS <extensions>` FILL HERE."
-
-Please be careful not to break reST notation.  Most po-editors will help you
-with that.
-
+~~~~~~~~~~~
 
 Update your po files by new pot files
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-If a document is updated, it is necessary to generate updated pot files
-and to apply differences to translated po files.
-In order to apply the updating difference of a pot file to po file,
-use the :command:`sphinx-intl update` command.
+If a document is updated, it is necessary to generate updated pot files and to
+apply differences to translated po files.  In order to apply the updates from a
+pot file to the po file, use the :command:`sphinx-intl update` command.
 
 .. code-block:: console
 
@@ -198,7 +206,7 @@ easy to fetch and push translations.
 .. TODO: why use transifex?
 
 
-#. Install `transifex-client`_
+#. Install `transifex-client`_.
 
    You need :command:`tx` command to upload resources (pot files).
 
@@ -208,8 +216,7 @@ easy to fetch and push translations.
 
    .. seealso:: `Transifex Client documentation`_
 
-
-#. Create your transifex_ account and create new project for your document
+#. Create your transifex_ account and create new project for your document.
 
    Currently, transifex does not allow for a translation project to have more
    than one version of the document, so you'd better include a version number in
@@ -220,8 +227,7 @@ easy to fetch and push translations.
    :Project ID: ``sphinx-document-test_1_0``
    :Project URL: ``https://www.transifex.com/projects/p/sphinx-document-test_1_0/``
 
-
-#. Create config files for tx command
+#. Create config files for :command:`tx` command.
 
    This process will create ``.tx/config`` in the current directory, as well as
    a ``~/.transifexrc`` file that includes auth information.
@@ -237,7 +243,7 @@ easy to fetch and push translations.
       ...
       Done.
 
-#. Upload pot files to transifex service
+#. Upload pot files to transifex service.
 
    Register pot files to ``.tx/config`` file:
 
@@ -258,15 +264,14 @@ easy to fetch and push translations.
       ...
       Done.
 
-
-#. Forward the translation on transifex
+#. Forward the translation on transifex.
 
    .. TODO: write this section
 
+#. Pull translated po files and make translated HTML.
 
-#. Pull translated po files and make translated html
-
-   Get translated catalogs and build mo files (ex. for 'de'):
+   Get translated catalogs and build mo files. For example, to build mo files
+   for German (de):
 
    .. code-block:: console
 
@@ -277,32 +282,29 @@ easy to fetch and push translations.
       ...
       Done.
 
-   Invoke make html (for BSD/GNU make):
+   Invoke :command:`make html` (for BSD/GNU make):
 
    .. code-block:: console
 
       $ make -e SPHINXOPTS="-D language='de'" html
 
-
 That's all!
 
-
 .. tip:: Translating locally and on Transifex
 
    If you want to push all language's po files, you can be done by using
-   :command:`tx push -t` command.
-   Watch out! This operation overwrites translations in transifex.
+   :command:`tx push -t` command.  Watch out! This operation overwrites
+   translations in transifex.
 
    In other words, if you have updated each in the service and local po files,
    it would take much time and effort to integrate them.
 
 
-
 Contributing to Sphinx reference translation
 --------------------------------------------
 
-The recommended way for new contributors to translate Sphinx reference
-is to join the translation team on Transifex.
+The recommended way for new contributors to translate Sphinx reference is to
+join the translation team on Transifex.
 
 There is `sphinx translation page`_ for Sphinx (master) documentation.
 
@@ -310,8 +312,7 @@ There is `sphinx translation page`_ for Sphinx (master) documentation.
 2. Go to `sphinx translation page`_.
 3. Click ``Request language`` and fill form.
 4. Wait acceptance by transifex sphinx translation maintainers.
-5. (after acceptance) translate on transifex.
-
+5. (After acceptance) Translate on transifex.
 
 .. rubric:: Footnotes
 
@@ -320,7 +321,6 @@ There is `sphinx translation page`_ for Sphinx (master) documentation.
        for details on that software suite.
 .. [2] Because nobody expects the Spanish Inquisition!
 
-
 .. _`transifex-client`: https://pypi.org/project/transifex-client/
 .. _`sphinx-intl`: https://pypi.org/project/sphinx-intl/
 .. _Transifex: https://www.transifex.com/

doc/usage/advanced/websupport/api.rst

@@ -65,7 +65,7 @@ The WebSupport Class
 
 
 Methods
-~~~~~~~
+-------
 
 .. automethod:: sphinxcontrib.websupport.WebSupport.build
 

doc/usage/advanced/websupport/index.rst

@@ -10,7 +10,7 @@ web application.  To learn more read the :ref:`websupportquickstart`.
 
 .. toctree::
 
-   web/quickstart
-   web/api
-   web/searchadapters
-   web/storagebackends
+   quickstart
+   api
+   searchadapters
+   storagebackends

doc/usage/advanced/websupport/quickstart.rst

@@ -4,7 +4,7 @@ Web Support Quick Start
 =======================
 
 Building Documentation Data
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
+----------------------------
 
 To make use of the web support package in your application you'll need to build
 the data it uses.  This data includes pickle files representing documents,
@@ -20,11 +20,11 @@ things are in a document.  To do this you will need to create an instance of the
 
    support.build()
 
-This will read reStructuredText sources from `srcdir` and place the necessary
-data in `builddir`.  The `builddir` will contain two sub-directories: one named
-"data" that contains all the data needed to display documents, search through
-documents, and add comments to documents.  The other directory will be called
-"static" and contains static files that should be served from "/static".
+This will read reStructuredText sources from ``srcdir`` and place the necessary
+data in ``builddir``.  The ``builddir`` will contain two sub-directories: one
+named "data" that contains all the data needed to display documents, search
+through documents, and add comments to documents.  The other directory will be
+called "static" and contains static files that should be served from "/static".
 
 .. note::
 
@@ -34,7 +34,7 @@ documents, and add comments to documents.  The other directory will be called
 
 
 Integrating Sphinx Documents Into Your Webapp
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+----------------------------------------------
 
 Now that the data is built, it's time to do something useful with it.  Start off
 by creating a :class:`~.WebSupport` object for your application::
@@ -96,7 +96,7 @@ integrate with your existing templating system.  An example using `Jinja2
 
 
 Authentication
---------------
+~~~~~~~~~~~~~~
 
 To use certain features such as voting, it must be possible to authenticate
 users.  The details of the authentication are left to your application.  Once a
@@ -146,13 +146,14 @@ add this data to the ``COMMENT_OPTIONS`` that are used in the template.
 
 
 Performing Searches
-~~~~~~~~~~~~~~~~~~~
+-------------------
 
 To use the search form built-in to the Sphinx sidebar, create a function to
-handle requests to the url 'search' relative to the documentation root.  The
+handle requests to the URL 'search' relative to the documentation root.  The
 user's search query will be in the GET parameters, with the key `q`.  Then use
-the :meth:`~sphinxcontrib.websupport.WebSupport.get_search_results` method to retrieve
-search results. In `Flask <http://flask.pocoo.org/>`_ that would be like this::
+the :meth:`~sphinxcontrib.websupport.WebSupport.get_search_results` method to
+retrieve search results. In `Flask <http://flask.pocoo.org/>`_ that would be
+like this::
 
    @app.route('/search')
    def search():
@@ -167,7 +168,7 @@ does.
 
 
 Comments & Proposals
-~~~~~~~~~~~~~~~~~~~~
+--------------------
 
 Now that this is done it's time to define the functions that handle the AJAX
 calls from the script.  You will need three functions.  The first function is
@@ -186,9 +187,9 @@ used to add a new comment, and will call the web support method
                                      username=username, proposal=proposal)
        return jsonify(comment=comment)
 
-You'll notice that both a `parent_id` and `node_id` are sent with the
-request. If the comment is being attached directly to a node, `parent_id`
-will be empty. If the comment is a child of another comment, then `node_id`
+You'll notice that both a ``parent_id`` and ``node_id`` are sent with the
+request. If the comment is being attached directly to a node, ``parent_id``
+will be empty. If the comment is a child of another comment, then ``node_id``
 will be empty. Then next function handles the retrieval of comments for a
 specific node, and is aptly named
 :meth:`~sphinxcontrib.websupport.WebSupport.get_data`::
@@ -217,11 +218,11 @@ and will handle user votes on comments::
 
 
 Comment Moderation
-~~~~~~~~~~~~~~~~~~
+------------------
 
 By default, all comments added through :meth:`~.WebSupport.add_comment` are
 automatically displayed.  If you wish to have some form of moderation, you can
-pass the `displayed` keyword argument::
+pass the ``displayed`` keyword argument::
 
    comment = support.add_comment(text, node_id='node_id',
                                  parent_id='parent_id',

doc/usage/advanced/websupport/searchadapters.rst

@@ -26,13 +26,13 @@ documentation of the :class:`BaseSearch` class below.
    BaseSearch class is moved to sphinxcontrib.websupport.search from
    sphinx.websupport.search.
 
-BaseSearch Methods
-~~~~~~~~~~~~~~~~~~
+Methods
+-------
 
-   The following methods are defined in the BaseSearch class. Some methods do
-   not need to be overridden, but some (:meth:`~BaseSearch.add_document` and
-   :meth:`~BaseSearch.handle_query`) must be overridden in your subclass. For a
-   working example, look at the built-in adapter for whoosh.
+The following methods are defined in the BaseSearch class. Some methods do not
+need to be overridden, but some (:meth:`~BaseSearch.add_document` and
+:meth:`~BaseSearch.handle_query`) must be overridden in your subclass. For a
+working example, look at the built-in adapter for whoosh.
 
 .. automethod:: BaseSearch.init_indexing
 

doc/usage/advanced/websupport/storagebackends.rst

@@ -27,8 +27,8 @@ documentation of the :class:`StorageBackend` class below.
    sphinx.websupport.storage.
 
 
-StorageBackend Methods
-~~~~~~~~~~~~~~~~~~~~~~
+Methods
+-------
 
 .. automethod:: StorageBackend.pre_build
 

doc/usage/configuration.rst

@@ -816,7 +816,7 @@ that use Sphinx's HTMLWriter class.
 .. confval:: html_theme
 
    The "theme" that the HTML output should use.  See the :doc:`section about
-   theming </theming>`.  The default is ``'alabaster'``.
+   theming </usage/theming>`.  The default is ``'alabaster'``.
 
    .. versionadded:: 0.6
 

doc/usage/quickstart.rst

@@ -320,8 +320,8 @@ More topics to be covered
 
 - :doc:`Other extensions </usage/extensions/index>`:
 - Static files
-- :doc:`Selecting a theme </theming>`
-- :doc:`/setuptools`
+- :doc:`Selecting a theme </usage/theming>`
+- :doc:`/usage/advanced/setuptools`
 - :ref:`Templating <templating>`
 - Using extensions
 - :ref:`Writing extensions <dev-extensions>`

doc/usage/theming.rst

@@ -0,0 +1,339 @@
+.. highlight:: python
+
+HTML
+====
+
+Sphinx provides a number of builders for HTML and HTML-based formats.
+
+Builders
+--------
+
+.. todo:: Populate when the 'builders' document is split up.
+
+
+Themes
+------
+
+.. versionadded:: 0.6
+
+.. note::
+
+   This section provides information about using pre-existing HTML themes. If
+   you wish to create your own theme, refer to :doc:`/theming`.
+
+Sphinx supports changing the appearance of its HTML output via *themes*.  A
+theme is a collection of HTML templates, stylesheet(s) and other static files.
+Additionally, it has a configuration file which specifies from which theme to
+inherit, which highlighting style to use, and what options exist for customizing
+the theme's look and feel.
+
+Themes are meant to be project-unaware, so they can be used for different
+projects without change.
+
+Using a theme
+~~~~~~~~~~~~~
+
+Using a :ref:`theme provided with Sphinx <builtin-themes>` is easy. Since these
+do not need to be installed, you only need to set the :confval:`html_theme`
+config value. For example, to enable the ``classic`` theme, add the following
+to :file:`conf.py`::
+
+    html_theme = "classic"
+
+You can also set theme-specific options using the :confval:`html_theme_options`
+config value.  These options are generally used to change the look and feel of
+the theme. For example, to place the sidebar on the right side and a black
+background for the relation bar (the bar with the navigation links at the
+page's top and bottom), add the following :file:`conf.py`::
+
+    html_theme_options = {
+        "rightsidebar": "true",
+        "relbarbgcolor": "black"
+    }
+
+If the theme does not come with Sphinx, it can be in two static forms or as a
+Python package. For the static forms, either a directory (containing
+:file:`theme.conf` and other needed files), or a zip file with the same
+contents is supported. The directory or zipfile must be put where Sphinx can
+find it; for this there is the config value :confval:`html_theme_path`. This
+can be a list of directories, relative to the directory containing
+:file:`conf.py`, that can contain theme directories or zip files.  For example,
+if you have a theme in the file :file:`blue.zip`, you can put it right in the
+directory containing :file:`conf.py` and use this configuration::
+
+    html_theme = "blue"
+    html_theme_path = ["."]
+
+The third form is a Python package.  If a theme you want to use is distributed
+as a Python package, you can use it after installing
+
+.. code-block:: bash
+
+    # installing theme package
+    $ pip install sphinxjp.themes.dotted
+
+Once installed, this can be used in the same manner as a directory or
+zipfile-based theme::
+
+    html_theme = "dotted"
+
+For more information on the design of themes, including information about
+writing your own themes, refer to :doc:`/theming`.
+
+.. _builtin-themes:
+
+Builtin themes
+~~~~~~~~~~~~~~
+
+.. cssclass:: longtable
+
++--------------------+--------------------+
+| **Theme overview** |                    |
++--------------------+--------------------+
+| |alabaster|        | |classic|          |
+|                    |                    |
+| *alabaster*        | *classic*          |
++--------------------+--------------------+
+| |sphinxdoc|        | |scrolls|          |
+|                    |                    |
+| *sphinxdoc*        | *scrolls*          |
++--------------------+--------------------+
+| |agogo|            | |traditional|      |
+|                    |                    |
+| *agogo*            | *traditional*      |
++--------------------+--------------------+
+| |nature|           | |haiku|            |
+|                    |                    |
+| *nature*           | *haiku*            |
++--------------------+--------------------+
+| |pyramid|          | |bizstyle|         |
+|                    |                    |
+| *pyramid*          | *bizstyle*         |
++--------------------+--------------------+
+
+.. |alabaster|        image:: /_static/themes/alabaster.png
+.. |classic|          image:: /_static/themes/classic.png
+.. |sphinxdoc|        image:: /_static/themes/sphinxdoc.png
+.. |scrolls|          image:: /_static/themes/scrolls.png
+.. |agogo|            image:: /_static/themes/agogo.png
+.. |traditional|      image:: /_static/themes/traditional.png
+.. |nature|           image:: /_static/themes/nature.png
+.. |haiku|            image:: /_static/themes/haiku.png
+.. |pyramid|          image:: /_static/themes/pyramid.png
+.. |bizstyle|         image:: /_static/themes/bizstyle.png
+
+Sphinx comes with a selection of themes to choose from.
+
+.. cssclass:: clear
+
+These themes are:
+
+**basic**
+  This is a basically unstyled layout used as the base for the
+  other themes, and usable as the base for custom themes as well.  The HTML
+  contains all important elements like sidebar and relation bar.  There are
+  these options (which are inherited by the other themes):
+
+  - **nosidebar** (true or false): Don't include the sidebar.  Defaults to
+    ``False``.
+
+  - **sidebarwidth** (int or str): Width of the sidebar in pixels.
+    This can be an int, which is interpreted as pixels or a valid CSS
+    dimension string such as '70em' or '50%'.  Defaults to 230 pixels.
+
+  - **body_min_width** (int or str): Minimal width of the document body.
+    This can be an int, which is interpreted as pixels or a valid CSS
+    dimension string such as '70em' or '50%'. Use 0 if you don't want
+    a width limit. Defaults may depend on the theme (often 450px).
+
+  - **body_max_width** (int or str): Maximal width of the document body.
+    This can be an int, which is interpreted as pixels or a valid CSS
+    dimension string such as '70em' or '50%'. Use 'none' if you don't
+    want a width limit. Defaults may depend on the theme (often 800px).
+
+**alabaster**
+  `Alabaster theme`_ is a modified "Kr" Sphinx theme from @kennethreitz
+  (especially as used in his Requests project), which was itself originally
+  based on @mitsuhiko's theme used for Flask & related projects.  Refer to its
+  `installation page`_ for information on how to configure
+  :confval:`html_sidebars` for its use.
+
+  .. _Alabaster theme: https://pypi.org/project/alabaster/
+  .. _installation page: https://alabaster.readthedocs.io/en/latest/installation.html
+
+**classic**
+  This is the classic theme, which looks like `the Python 2
+  documentation <https://docs.python.org/2/>`_.  It can be customized via
+  these options:
+
+  - **rightsidebar** (true or false): Put the sidebar on the right side.
+    Defaults to ``False``.
+
+  - **stickysidebar** (true or false): Make the sidebar "fixed" so that it
+    doesn't scroll out of view for long body content.  This may not work well
+    with all browsers.  Defaults to ``False``.
+
+  - **collapsiblesidebar** (true or false): Add an *experimental* JavaScript
+    snippet that makes the sidebar collapsible via a button on its side.
+    Defaults to ``False``.
+
+  - **externalrefs** (true or false): Display external links differently from
+    internal links.  Defaults to ``False``.
+
+  There are also various color and font options that can change the color scheme
+  without having to write a custom stylesheet:
+
+  - **footerbgcolor** (CSS color): Background color for the footer line.
+  - **footertextcolor** (CSS color): Text color for the footer line.
+  - **sidebarbgcolor** (CSS color): Background color for the sidebar.
+  - **sidebarbtncolor** (CSS color): Background color for the sidebar collapse
+    button (used when *collapsiblesidebar* is ``True``).
+  - **sidebartextcolor** (CSS color): Text color for the sidebar.
+  - **sidebarlinkcolor** (CSS color): Link color for the sidebar.
+  - **relbarbgcolor** (CSS color): Background color for the relation bar.
+  - **relbartextcolor** (CSS color): Text color for the relation bar.
+  - **relbarlinkcolor** (CSS color): Link color for the relation bar.
+  - **bgcolor** (CSS color): Body background color.
+  - **textcolor** (CSS color): Body text color.
+  - **linkcolor** (CSS color): Body link color.
+  - **visitedlinkcolor** (CSS color): Body color for visited links.
+  - **headbgcolor** (CSS color): Background color for headings.
+  - **headtextcolor** (CSS color): Text color for headings.
+  - **headlinkcolor** (CSS color): Link color for headings.
+  - **codebgcolor** (CSS color): Background color for code blocks.
+  - **codetextcolor** (CSS color): Default text color for code blocks, if not
+    set differently by the highlighting style.
+
+  - **bodyfont** (CSS font-family): Font for normal text.
+  - **headfont** (CSS font-family): Font for headings.
+
+**sphinxdoc**
+  The theme originally used by this documentation. It features
+  a sidebar on the right side. There are currently no options beyond
+  *nosidebar* and *sidebarwidth*.
+
+  .. note::
+
+    The Sphinx documentation now uses
+    `an adjusted version of the sphinxdoc theme
+    <https://github.com/sphinx-doc/sphinx/tree/master/doc/_themes/sphinx13>`_.
+
+**scrolls**
+  A more lightweight theme, based on `the Jinja documentation
+  <http://jinja.pocoo.org/>`_.  The following color options are available:
+
+  - **headerbordercolor**
+  - **subheadlinecolor**
+  - **linkcolor**
+  - **visitedlinkcolor**
+  - **admonitioncolor**
+
+**agogo**
+  A theme created by Andi Albrecht.  The following options are supported:
+
+  - **bodyfont** (CSS font family): Font for normal text.
+  - **headerfont** (CSS font family): Font for headings.
+  - **pagewidth** (CSS length): Width of the page content, default 70em.
+  - **documentwidth** (CSS length): Width of the document (without sidebar),
+    default 50em.
+  - **sidebarwidth** (CSS length): Width of the sidebar, default 20em.
+  - **bgcolor** (CSS color): Background color.
+  - **headerbg** (CSS value for "background"): background for the header area,
+    default a grayish gradient.
+  - **footerbg** (CSS value for "background"): background for the footer area,
+    default a light gray gradient.
+  - **linkcolor** (CSS color): Body link color.
+  - **headercolor1**, **headercolor2** (CSS color): colors for <h1> and <h2>
+    headings.
+  - **headerlinkcolor** (CSS color): Color for the backreference link in
+    headings.
+  - **textalign** (CSS *text-align* value): Text alignment for the body, default
+    is ``justify``.
+
+**nature**
+  A greenish theme.  There are currently no options beyond
+  *nosidebar* and *sidebarwidth*.
+
+**pyramid**
+  A theme from the Pyramid web framework project, designed by Blaise Laflamme.
+  There are currently no options beyond *nosidebar* and *sidebarwidth*.
+
+**haiku**
+  A theme without sidebar inspired by the `Haiku OS user guide
+  <https://www.haiku-os.org/docs/userguide/en/contents.html>`_.  The following
+  options are supported:
+
+  - **full_logo** (true or false, default ``False``): If this is true, the
+    header will only show the :confval:`html_logo`.  Use this for large logos.
+    If this is false, the logo (if present) will be shown floating right, and
+    the documentation title will be put in the header.
+
+  - **textcolor**, **headingcolor**, **linkcolor**, **visitedlinkcolor**,
+    **hoverlinkcolor** (CSS colors): Colors for various body elements.
+
+**traditional**
+  A theme resembling the old Python documentation.  There are
+  currently no options beyond *nosidebar* and *sidebarwidth*.
+
+**epub**
+  A theme for the epub builder.  This theme tries to save visual
+  space which is a sparse resource on ebook readers.  The following options
+  are supported:
+
+  - **relbar1** (true or false, default ``True``): If this is true, the
+    `relbar1` block is inserted in the epub output, otherwise it is omitted.
+
+  - **footer**  (true or false, default ``True``): If this is true, the
+    `footer` block is inserted in the epub output, otherwise it is omitted.
+
+**bizstyle**
+  A simple bluish theme. The following options are supported
+  beyond *nosidebar* and *sidebarwidth*:
+
+  - **rightsidebar** (true or false): Put the sidebar on the right side.
+    Defaults to ``False``.
+
+.. versionadded:: 1.3
+   'alabaster', 'sphinx_rtd_theme' and 'bizstyle' theme.
+
+.. versionchanged:: 1.3
+   The 'default' theme has been renamed to 'classic'. 'default' is still
+   available, however it will emit a notice that it is an alias for the new
+   'alabaster' theme.
+
+Third Party Themes
+~~~~~~~~~~~~~~~~~~
+
+.. cssclass:: longtable
+
++--------------------+--------------------+
+| **Theme overview** |                    |
++--------------------+--------------------+
+| |sphinx_rtd_theme| |                    |
+|                    |                    |
+| *sphinx_rtd_theme* |                    |
++--------------------+--------------------+
+
+.. |sphinx_rtd_theme| image:: /_static/themes/sphinx_rtd_theme.png
+
+There are many third-party themes available. Some of these are general use,
+while others are specific to an individual project. A section of third-party
+themes is listed below. Many more can be found on PyPI__, GitHub__ and
+sphinx-themes.org__.
+
+.. cssclass:: clear
+
+**sphinx_rtd_theme**
+  `Read the Docs Sphinx Theme`_.
+  This is a mobile-friendly sphinx theme that was made for readthedocs.org.
+  View a working demo over on readthedocs.org. You can get install and options
+  information at `Read the Docs Sphinx Theme`_ page.
+
+  .. _Read the Docs Sphinx Theme: https://pypi.org/project/sphinx_rtd_theme/
+
+  .. versionchanged:: 1.4
+     **sphinx_rtd_theme** has become optional.
+
+.. __: https://pypi.org/search/?q=&o=&c=Framework+%3A%3A+Sphinx+%3A%3A+Theme
+.. __: https://github.com/search?utf8=%E2%9C%93&q=sphinx+theme&type=
+.. __: https://sphinx-themes.org/