doc: Rework "extensions" documents

This is mostly spacing and other "niceness" fixes.

Signed-off-by: Stephen Finucane <stephen@that.guru>

15 files changed, 52 insertions, 47 deletions

diff --git a/doc/ext/autodoc.rst b/doc/ext/autodoc.rst
index 9064fe1b3..385254734 100644
--- a/doc/ext/autodoc.rst
+++ b/doc/ext/autodoc.rst
@@ -405,6 +405,7 @@ There are also new config values that you can set:
 
    .. versionadded:: 1.7
 
+
 Docstring preprocessing
 -----------------------
 
diff --git a/doc/ext/autosectionlabel.rst b/doc/ext/autosectionlabel.rst
index f4a6322c3..20b15ca20 100644
--- a/doc/ext/autosectionlabel.rst
+++ b/doc/ext/autosectionlabel.rst
@@ -27,6 +27,7 @@ default. The ``autosectionlabel_prefix_document`` configuration variable can be
 used to make headings which appear multiple times but in different documents
 unique.
 
+
 Configuration
 -------------
 
diff --git a/doc/ext/autosummary.rst b/doc/ext/autosummary.rst
index 46d8e4b56..008bc5613 100644
--- a/doc/ext/autosummary.rst
+++ b/doc/ext/autosummary.rst
@@ -25,7 +25,6 @@ The :mod:`sphinx.ext.autosummary` extension does this in two parts:
    These files by default contain only the corresponding
    :mod:`sphinx.ext.autodoc` directive, but can be customized with templates.
 
-
 .. rst:directive:: autosummary
 
    Insert a table that contains links to documented items, and a short summary
@@ -59,7 +58,6 @@ The :mod:`sphinx.ext.autosummary` extension does this in two parts:
    :event:`autodoc-process-docstring` and :event:`autodoc-process-signature`
    hooks as :mod:`~sphinx.ext.autodoc`.
 
-
    **Options**
 
    * If you want the :rst:dir:`autosummary` table to also serve as a
diff --git a/doc/ext/coverage.rst b/doc/ext/coverage.rst
index 839478fe1..94d4c6fe4 100644
--- a/doc/ext/coverage.rst
+++ b/doc/ext/coverage.rst
@@ -4,7 +4,6 @@
 .. module:: sphinx.ext.coverage
    :synopsis: Check Python modules and C API for coverage in the documentation.
 
-
 This extension features one additional builder, the :class:`CoverageBuilder`.
 
 .. class:: CoverageBuilder
@@ -14,7 +13,6 @@ This extension features one additional builder, the :class:`CoverageBuilder`.
 
 .. todo:: Write this section.
 
-
 Several new configuration values can be used to specify what the builder
 should check:
 
diff --git a/doc/ext/doctest.rst b/doc/ext/doctest.rst
index 62221bf04..341b7a9a7 100644
--- a/doc/ext/doctest.rst
+++ b/doc/ext/doctest.rst
@@ -165,7 +165,6 @@ a comma-separated list of group names.
 
          Output text.
 
-
 The following is an example for the usage of the directives.  The test via
 :rst:dir:`doctest` and the test via :rst:dir:`testcode` and
 :rst:dir:`testoutput` are equivalent. ::
diff --git a/doc/ext/extlinks.rst b/doc/ext/extlinks.rst
index b809a740b..d818ba09b 100644
--- a/doc/ext/extlinks.rst
+++ b/doc/ext/extlinks.rst
@@ -7,7 +7,6 @@
 
 .. versionadded:: 1.0
 
-
 This extension is meant to help with the common pattern of having many external
 links that point to URLs on one and the same site, e.g. links to bug trackers,
 version control web interfaces, or simply subpages in other websites.  It does
diff --git a/doc/ext/githubpages.rst b/doc/ext/githubpages.rst
index 0cd76a2c9..f19666ef1 100644
--- a/doc/ext/githubpages.rst
+++ b/doc/ext/githubpages.rst
@@ -1,5 +1,3 @@
-.. highlight:: rest
-
 :mod:`sphinx.ext.githubpages` -- Publish HTML docs in GitHub Pages
 ==================================================================
 
diff --git a/doc/ext/graphviz.rst b/doc/ext/graphviz.rst
index 8b9fff90b..f87f1a4b7 100644
--- a/doc/ext/graphviz.rst
+++ b/doc/ext/graphviz.rst
@@ -13,7 +13,6 @@ your documents.
 
 It adds these directives:
 
-
 .. rst:directive:: graphviz
 
    Directive to embed graphviz code.  The input code for ``dot`` is given as the
diff --git a/doc/ext/imgconverter.rst b/doc/ext/imgconverter.rst
index 322a9b5f3..5799fc3b3 100644
--- a/doc/ext/imgconverter.rst
+++ b/doc/ext/imgconverter.rst
@@ -1,28 +1,30 @@
-.. highlight:: rest
-
 .. _sphinx.ext.imgconverter:
 
-:mod:`sphinx.ext.imgconverter` -- A reference implementation for image converter using Imagemagick
-==================================================================================================
+:mod:`sphinx.ext.imgconverter` -- A reference image converter using Imagemagick
+===============================================================================
 
 .. module:: sphinx.ext.imgconverter
    :synopsis: Convert images to appropriate format for builders
 
 .. versionadded:: 1.6
 
-This extension converts images in your document to appropriate format for builders.
-For example, it allows you to use SVG images with LaTeX builder.
+This extension converts images in your document to appropriate format for
+builders.  For example, it allows you to use SVG images with LaTeX builder.
 As a result, you don't mind what image format the builder supports.
 
 Internally, this extension uses Imagemagick_ to convert images.
 
 .. _Imagemagick: https://www.imagemagick.org/script/index.php
 
-.. note:: Imagemagick rasterizes a SVG image on conversion.  As a result, the image
-          becomes not scalable.  To avoid that, please use other image converters
-          like sphinxcontrib-svg2pdfconverter_ (which uses Inkscape or rsvg-convert).
+.. note::
+
+   Imagemagick rasterizes a SVG image on conversion.  As a result, the image
+   becomes not scalable.  To avoid that, please use other image converters like
+   `sphinxcontrib-svg2pdfconverter`__ (which uses Inkscape or
+   ``rsvg-convert``).
+
+.. __: https://github.com/missinglinkelectronics/sphinxcontrib-svg2pdfconverter
 
-.. _sphinxcontrib-svg2pdfconverter: https://github.com/missinglinkelectronics/sphinxcontrib-svg2pdfconverter
 
 Configuration
 -------------
diff --git a/doc/ext/inheritance.rst b/doc/ext/inheritance.rst
index 0062a8afa..ef78d04fe 100644
--- a/doc/ext/inheritance.rst
+++ b/doc/ext/inheritance.rst
@@ -91,7 +91,9 @@ It adds this directive:
    .. versionchanged:: 1.7
       Added ``top-classes`` option to limit the scope of inheritance graphs.
 
-New config values are:
+
+Configuration
+-------------
 
 .. confval:: inheritance_graph_attrs
 
diff --git a/doc/ext/intersphinx.rst b/doc/ext/intersphinx.rst
index b8ae104b3..cfda53e8f 100644
--- a/doc/ext/intersphinx.rst
+++ b/doc/ext/intersphinx.rst
@@ -38,8 +38,9 @@ Behind the scenes, this works as follows:
   specified individually, e.g. if the docs should be buildable without Internet
   access.
 
-Configuring Intersphinx
------------------------
+
+Configuration
+-------------
 
 To use Intersphinx linking, add ``'sphinx.ext.intersphinx'`` to your
 :confval:`extensions` config value, and use these new config values to activate
@@ -136,12 +137,14 @@ linking:
       exception is raised if the server has not issued a response for timeout
       seconds.
 
+
 Showing all links of an Intersphinx mapping file
 ------------------------------------------------
 
-To show all Intersphinx links and their targets of an Intersphinx mapping file, run
-``python -msphinx.ext.intersphinx url-or-path``.  This is helpful when searching for the root cause of a broken
-Intersphinx link in a documentation project. The following example prints the Intersphinx mapping of the Python 3
+To show all Intersphinx links and their targets of an Intersphinx mapping file,
+run ``python -msphinx.ext.intersphinx url-or-path``.  This is helpful when
+searching for the root cause of a broken Intersphinx link in a documentation
+project. The following example prints the Intersphinx mapping of the Python 3
 documentation::
 
    $ python -msphinx.ext.intersphinx https://docs.python.org/3/objects.inv
diff --git a/doc/ext/linkcode.rst b/doc/ext/linkcode.rst
index f00345fca..e65a0b780 100644
--- a/doc/ext/linkcode.rst
+++ b/doc/ext/linkcode.rst
@@ -16,6 +16,10 @@ found somewhere on the Internet.
 In your configuration, you need to specify a :confval:`linkcode_resolve`
 function that returns an URL based on the object.
 
+
+Configuration
+-------------
+
 .. confval:: linkcode_resolve
 
    This is a function ``linkcode_resolve(domain, info)``,
diff --git a/doc/ext/napoleon.rst b/doc/ext/napoleon.rst
index 6c5f0d61a..b6c8d681b 100644
--- a/doc/ext/napoleon.rst
+++ b/doc/ext/napoleon.rst
@@ -1,5 +1,5 @@
 :mod:`sphinx.ext.napoleon` -- Support for NumPy and Google style docstrings
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+===========================================================================
 
 .. module:: sphinx.ext.napoleon
    :synopsis: Support for NumPy and Google style docstrings
@@ -8,8 +8,8 @@
 
 .. versionadded:: 1.3
 
-Napoleon - *Marching toward legible docstrings*
-===============================================
+Overview
+--------
 
 .. highlight:: text
 
@@ -25,7 +25,7 @@ Are you tired of writing docstrings that look like this::
     :returns: A buffered writable file descriptor
     :rtype: BufferedFileStorage
 
-`ReStructuredText`_ is great, but it creates visually dense, hard to read
+`reStructuredText`_ is great, but it creates visually dense, hard to read
 `docstrings`_. Compare the jumble above to the same thing rewritten
 according to the `Google Python Style Guide`_::
 
@@ -40,8 +40,8 @@ according to the `Google Python Style Guide`_::
 
 Much more legible, no?
 
-Napoleon is a :doc:`../extensions` that enables Sphinx to parse both `NumPy`_
-and `Google`_ style docstrings - the style recommended by `Khan Academy`_.
+Napoleon is a :term:`extension` that enables Sphinx to parse both `NumPy`_ and
+`Google`_ style docstrings - the style recommended by `Khan Academy`_.
 
 Napoleon is a pre-processor that parses `NumPy`_ and `Google`_ style
 docstrings and converts them to reStructuredText before Sphinx attempts to
@@ -61,7 +61,7 @@ source code files.
    https://github.com/Khan/style-guides/blob/master/style/python.md#docstrings
 
 Getting Started
----------------
+~~~~~~~~~~~~~~~
 
 1. After :doc:`setting up Sphinx </usage/quickstart>` to build your docs,
    enable napoleon in the Sphinx `conf.py` file::
@@ -77,7 +77,7 @@ Getting Started
 
 
 Docstrings
-----------
+~~~~~~~~~~
 
 Napoleon interprets every docstring that :mod:`autodoc <sphinx.ext.autodoc>`
 can find, including docstrings on: ``modules``, ``classes``, ``attributes``,
@@ -91,7 +91,7 @@ All standard reStructuredText formatting still works as expected.
 .. _Sections:
 
 Docstring Sections
-------------------
+~~~~~~~~~~~~~~~~~~
 
 All of the following section headers are supported:
 
@@ -120,7 +120,7 @@ All of the following section headers are supported:
     * ``Yields``
 
 Google vs NumPy
----------------
+~~~~~~~~~~~~~~~
 
 Napoleon supports two styles of docstrings: `Google`_ and `NumPy`_. The
 main difference between the two styles is that Google uses indention to
@@ -188,7 +188,7 @@ not be mixed. Choose one style for your project and be consistent with it.
 
 
 Type Annotations
-----------------
+~~~~~~~~~~~~~~~~
 
 `PEP 484`_ introduced a standard way to express types in Python code.
 This is an alternative to expressing types directly in docstrings.
@@ -242,7 +242,7 @@ Google style with types in docstrings::
 
 
 Configuration
-=============
+-------------
 
 Listed below are all the settings used by napoleon and their default
 values. These settings can be changed in the Sphinx `conf.py` file. Make
@@ -271,8 +271,6 @@ sure that "sphinx.ext.napoleon" is enabled in `conf.py`::
 .. _NumPy style:
    https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt
 
-
-
 .. confval:: napoleon_google_docstring
 
    True to parse `Google style`_ docstrings. False to disable support
diff --git a/doc/ext/todo.rst b/doc/ext/todo.rst
index 09abfa9b8..982005bd6 100644
--- a/doc/ext/todo.rst
+++ b/doc/ext/todo.rst
@@ -27,7 +27,10 @@ There are two additional directives when using this extension:
    documentation, if :confval:`todo_include_todos` is ``True``.
 
 
-There is also an additional config value:
+These can be configured as seen below.
+
+Configuration
+-------------
 
 .. confval:: todo_include_todos
 
diff --git a/doc/ext/viewcode.rst b/doc/ext/viewcode.rst
index 87071144f..ea7d5d335 100644
--- a/doc/ext/viewcode.rst
+++ b/doc/ext/viewcode.rst
@@ -7,9 +7,8 @@
 
 .. versionadded:: 1.0
 
-
-This extension looks at your Python object descriptions (``.. class::``,
-``.. function::`` etc.) and tries to find the source files where the objects are
+This extension looks at your Python object descriptions (``.. class::``, ``..
+function::`` etc.) and tries to find the source files where the objects are
 contained.  When found, a separate HTML page will be output for each module with
 a highlighted version of the source code, and a link will be added to all object
 descriptions that leads to the source code of the described object.  A link back
@@ -33,14 +32,15 @@ This extension works only on HTML related builders like ``html``,
 ``singlehtml``. By default ``epub`` builder doesn't
 support this extension (see :confval:`viewcode_enable_epub`).
 
-There is an additional config value:
+Configuration
+-------------
 
 .. confval:: viewcode_follow_imported_members
 
    If this is ``True``, viewcode extension will follow alias objects that
-   imported from another module such as functions, classes and attributes.
-   As side effects, this option
-   else they produce nothing.  The default is ``True``.
+   imported from another module such as functions, classes and attributes.  As
+   side effects, this option else they produce nothing.  The default is
+   ``True``.
 
    .. versionadded:: 1.3