rewrapping paragraphs when over 80 characters wide

23 files changed, 120 insertions, 106 deletions

diff --git a/doc/config.rst b/doc/config.rst
index 6bd9a5a8..0edba7bb 100644
--- a/doc/config.rst
+++ b/doc/config.rst
@@ -495,9 +495,10 @@ that use Sphinx' HTMLWriter class.
 .. confval:: html_favicon
 
    If given, this must be the name of an image file (path relative to the
-   :term:`configuration directory`) 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``.
+   :term:`configuration directory`) that is the favicon of the docs.  Modern
+   browsers use this as the icon for tabs, windows and bookmarks.  It should
+   be a Windows-style icon file (``.ico``), which is 16x16 or 32x32
+   pixels large.  Default: ``None``.
 
    .. versionadded:: 0.4
       The image file will be copied to the ``_static`` directory of the output
@@ -582,7 +583,8 @@ that use Sphinx' HTMLWriter class.
 
    Builtin sidebar templates that can be rendered are:
 
-   * **localtoc.html** -- a fine-grained table of contents of the current document
+   * **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
@@ -699,13 +701,14 @@ that use Sphinx' HTMLWriter class.
 .. confval:: html_translator_class
 
    A string with the fully-qualified name of a HTML Translator class, that is, a
-   subclass of Sphinx' :class:`~sphinx.writers.html.HTMLTranslator`, that is used
-   to translate document trees to HTML.  Default is ``None`` (use the builtin
-   translator).
+   subclass of Sphinx' :class:`~sphinx.writers.html.HTMLTranslator`, that is
+   used to translate document trees to HTML.  Default is ``None`` (use the
+   builtin translator).
 
 .. confval:: html_show_copyright
 
-   If true, "(C) Copyright ..." is shown in the HTML footer. Default is ``True``.
+   If true, "(C) Copyright ..." is shown in the HTML footer. Default is
+   ``True``.
 
    .. versionadded:: 1.0
 
@@ -1033,9 +1036,9 @@ These options influence LaTeX output.
      ``'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.
+     "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
@@ -1182,7 +1185,8 @@ These options influence LaTeX output.
         ``'\\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:
+   * Keys that are set by other options and therefore should not be overridden
+     are:
 
      ``'docclass'``
      ``'classoptions'``
diff --git a/doc/develop.rst b/doc/develop.rst
index aad3ff1e..ab24c055 100644
--- a/doc/develop.rst
+++ b/doc/develop.rst
@@ -68,7 +68,8 @@ This is the current list of contributed extensions in that repository:
 - paverutils: an alternate integration of Sphinx with Paver_.
 - phpdomain: an extension for PHP support
 - plantuml: embed UML diagram by using PlantUML_
-- py_directive: Execute python code in a ``py`` directive and return a math node.
+- py_directive: Execute python code in a ``py`` directive and return a math
+  node.
 - rawfiles: copy raw files, like a CNAME.
 - requirements: declare requirements wherever you need (e.g. in test
   docstrings), mark statuses and collect them in a single list
diff --git a/doc/devguide.rst b/doc/devguide.rst
index fef5fbed..b6399ec9 100644
--- a/doc/devguide.rst
+++ b/doc/devguide.rst
@@ -113,8 +113,8 @@ These are the basic steps needed to start developing on Sphinx.
    * For bug fixes, first add a test that fails without your changes and passes
      after they are applied.
 
-#. Please add a bullet point to :file:`CHANGES` if the fix or feature is not trivial
-   (small doc updates, typo fixes).  Then commit::
+#. Please add a bullet point to :file:`CHANGES` if the fix or feature is not
+   trivial (small doc updates, typo fixes).  Then commit::
 
        hg commit -m '#42: Add useful new feature that does this.'
 
@@ -191,9 +191,9 @@ identifier and put ``sphinx.po`` in there.  Don't forget to update the possible
 values for :confval:`language` in ``doc/config.rst``.
 
 The Sphinx core messages can also be translated on `Transifex
-<https://www.transifex.com/>`_.  There exists a client tool named ``tx`` in the Python
-package "transifex_client", which can be used to pull translations in ``.po``
-format from Transifex.  To do this, go to ``sphinx/locale`` and then run
+<https://www.transifex.com/>`_.  There exists a client tool named ``tx`` in the
+Python package "transifex_client", which can be used to pull translations in
+``.po`` format from Transifex.  To do this, go to ``sphinx/locale`` and then run
 ``tx pull -f -l LANG`` where LANG is an existing language identifier.  It is
 good practice to run ``python setup.py update_catalog`` afterwards to make sure
 the ``.po`` file has the canonical Babel formatting.
diff --git a/doc/domains.rst b/doc/domains.rst
index 483052a9..f21c89e7 100644
--- a/doc/domains.rst
+++ b/doc/domains.rst
@@ -127,7 +127,8 @@ declarations:
 
    This directive marks the beginning of the description of a module (or package
    submodule, in which case the name should be fully qualified, including the
-   package name).  It does not create content (like e.g. :rst:dir:`py:class` does).
+   package name).  It does not create content (like e.g. :rst:dir:`py:class`
+   does).
 
    This directive will also cause an entry in the global module index.
 
@@ -655,9 +656,9 @@ There is a set of directives allowing documenting command-line programs:
 
 .. rst:directive:: .. program:: name
 
-   Like :rst:dir:`py:currentmodule`, this directive produces no output.  Instead, it
-   serves to notify Sphinx that all following :rst:dir:`option` directives
-   document options for the program called *name*.
+   Like :rst:dir:`py:currentmodule`, this directive produces no output.
+   Instead, it serves to notify Sphinx that all following :rst:dir:`option`
+   directives document options for the program called *name*.
 
    If you use :rst:dir:`program`, you have to qualify the references in your
    :rst:role:`option` roles by the program name, so if you have the following
diff --git a/doc/ext/autodoc.rst b/doc/ext/autodoc.rst
index 4f2e9d96..844c6368 100644
--- a/doc/ext/autodoc.rst
+++ b/doc/ext/autodoc.rst
@@ -274,13 +274,14 @@ inserting them into the page source under a suitable :rst:dir:`py:module`,
               """Docstring for instance attribute spam."""
 
    .. versionchanged:: 0.6
-      :rst:dir:`autodata` and :rst:dir:`autoattribute` can now extract docstrings.
+      :rst:dir:`autodata` and :rst:dir:`autoattribute` can now extract
+      docstrings.
    .. versionchanged:: 1.1
       Comment docs are now allowed on the same line after an assignment.
 
    .. versionchanged:: 1.2
-      :rst:dir:`autodata` and :rst:dir:`autoattribute` have
-      an ``annotation`` option
+      :rst:dir:`autodata` and :rst:dir:`autoattribute` have an ``annotation``
+      option.
 
    .. note::
 
@@ -413,8 +414,8 @@ autodoc provides the following additional events:
       ``noindex`` that are true if the flag option of same name was given to the
       auto directive
    :param signature: function signature, as a string of the form
-      ``"(parameter_1, parameter_2)"``, or ``None`` if introspection didn't succeed
-      and signature wasn't specified in the directive.
+      ``"(parameter_1, parameter_2)"``, or ``None`` if introspection didn't
+      succeed and signature wasn't specified in the directive.
    :param return_annotation: function return annotation as a string of the form
       ``" -> annotation"``, or ``None`` if there is no return annotation
 
@@ -445,8 +446,8 @@ member should be included in the documentation by using the following event:
       ``"attribute"``)
    :param name: the fully qualified name of the object
    :param obj: the object itself
-   :param skip: a boolean indicating if autodoc will skip this member if the user
-      handler does not override the decision
+   :param skip: a boolean indicating if autodoc will skip this member if the
+      user handler does not override the decision
    :param options: the options given to the directive: an object with attributes
       ``inherited_members``, ``undoc_members``, ``show_inheritance`` and
       ``noindex`` that are true if the flag option of same name was given to the
diff --git a/doc/ext/autosummary.rst b/doc/ext/autosummary.rst
index e3de1835..8548fbd5 100644
--- a/doc/ext/autosummary.rst
+++ b/doc/ext/autosummary.rst
@@ -15,15 +15,15 @@ one of them on a separate page makes them easier to read.
 
 The :mod:`sphinx.ext.autosummary` extension does this in two parts:
 
-1. There is an :rst:dir:`autosummary` directive for generating summary listings that
-   contain links to the documented items, and short summary blurbs extracted
-   from their docstrings.
+1. There is an :rst:dir:`autosummary` directive for generating summary listings
+   that contain links to the documented items, and short summary blurbs
+   extracted from their docstrings.
 
 2. Optionally, the convenience script :program:`sphinx-autogen` or the new
    :confval:`autosummary_generate` config value can be used to generate short
    "stub" files for the entries listed in the :rst:dir:`autosummary` directives.
-   These files by default contain only the corresponding :mod:`sphinx.ext.autodoc`
-   directive, but can be customized with templates.
+   These files by default contain only the corresponding
+   :mod:`sphinx.ext.autodoc` directive, but can be customized with templates.
 
 
 .. rst:directive:: autosummary
@@ -62,8 +62,8 @@ The :mod:`sphinx.ext.autosummary` extension does this in two parts:
 
    **Options**
 
-   * If you want the :rst:dir:`autosummary` table to also serve as a :rst:dir:`toctree`
-     entry, use the ``toctree`` option, for example::
+   * If you want the :rst:dir:`autosummary` table to also serve as a
+     :rst:dir:`toctree` entry, use the ``toctree`` option, for example::
 
          .. autosummary::
             :toctree: DIRNAME
@@ -78,8 +78,8 @@ The :mod:`sphinx.ext.autosummary` extension does this in two parts:
      directory. If no argument is given, output is placed in the same directory
      as the file that contains the directive.
 
-   * If you don't want the :rst:dir:`autosummary` to show function signatures in the
-     listing, include the ``nosignatures`` option::
+   * If you don't want the :rst:dir:`autosummary` to show function signatures in
+     the listing, include the ``nosignatures`` option::
 
          .. autosummary::
             :nosignatures:
@@ -112,8 +112,8 @@ For example, the command ::
 
     $ sphinx-autogen -o generated *.rst
 
-will read all :rst:dir:`autosummary` tables in the :file:`*.rst` files that have the
-``:toctree:`` option set, and output corresponding stub pages in directory
+will read all :rst:dir:`autosummary` tables in the :file:`*.rst` files that have
+the ``:toctree:`` option set, and output corresponding stub pages in directory
 ``generated`` for all documented items.  The generated pages by default contain
 text of the form::
 
diff --git a/doc/ext/doctest.rst b/doc/ext/doctest.rst
index 554987ee..9b1b4e6d 100644
--- a/doc/ext/doctest.rst
+++ b/doc/ext/doctest.rst
@@ -142,8 +142,8 @@ names.
 
 
 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. ::
+:rst:dir:`doctest` and the test via :rst:dir:`testcode` and
+:rst:dir:`testoutput` are equivalent. ::
 
    The parrot module
    =================
@@ -236,5 +236,5 @@ There are also these config values for customizing the doctest extension:
    Note though that you can't have blank lines in reST doctest blocks.  They
    will be interpreted as one block ending and another one starting.  Also,
    removal of ``<BLANKLINE>`` and ``# doctest:`` options only works in
-   :rst:dir:`doctest` blocks, though you may set :confval:`trim_doctest_flags` to
-   achieve that in all code blocks with Python console content.
+   :rst:dir:`doctest` blocks, though you may set :confval:`trim_doctest_flags`
+   to achieve that in all code blocks with Python console content.
diff --git a/doc/ext/intersphinx.rst b/doc/ext/intersphinx.rst
index 1daa658a..b3972b43 100644
--- a/doc/ext/intersphinx.rst
+++ b/doc/ext/intersphinx.rst
@@ -99,8 +99,8 @@ linking:
 
    This will read the inventory from :file:`python-inv.txt` in the source
    directory, but still generate links to the pages under
-   ``http://docs.python.org/3.2``.  It is up to you to update the inventory file as
-   new objects are added to the Python documentation.
+   ``http://docs.python.org/3.2``.  It is up to you to update the inventory file
+   as new objects are added to the Python documentation.
 
 .. confval:: intersphinx_cache_limit
 
diff --git a/doc/ext/linkcode.rst b/doc/ext/linkcode.rst
index a69a5b1c..05d2cc6d 100644
--- a/doc/ext/linkcode.rst
+++ b/doc/ext/linkcode.rst
@@ -31,7 +31,8 @@ function that returns an URL based on the object.
    - ``py``: ``module`` (name of the module), ``fullname`` (name of the object)
    - ``c``: ``names`` (list of names for the object)
    - ``cpp``: ``names`` (list of names for the object)
-   - ``javascript``: ``object`` (name of the object), ``fullname`` (name of the item)
+   - ``javascript``: ``object`` (name of the object), ``fullname``
+     (name of the item)
 
    Example:
 
diff --git a/doc/ext/napoleon.rst b/doc/ext/napoleon.rst
index 26d494db..8d4a9311 100644
--- a/doc/ext/napoleon.rst
+++ b/doc/ext/napoleon.rst
@@ -61,8 +61,8 @@ source code files.
 Getting Started
 ---------------
 
-1. After :doc:`setting up Sphinx <../tutorial>` to build your docs, enable napoleon in the
-   Sphinx `conf.py` file::
+1. After :doc:`setting up Sphinx <../tutorial>` to build your docs, enable
+   napoleon in the Sphinx `conf.py` file::
 
        # conf.py
 
diff --git a/doc/ext/todo.rst b/doc/ext/todo.rst
index 349d286a..d606a7ab 100644
--- a/doc/ext/todo.rst
+++ b/doc/ext/todo.rst
@@ -26,5 +26,5 @@ There is also an additional config value:
 
 .. confval:: todo_include_todos
 
-   If this is ``True``, :rst:dir:`todo` and :rst:dir:`todolist` produce output, else
-   they produce nothing.  The default is ``False``.
+   If this is ``True``, :rst:dir:`todo` and :rst:dir:`todolist` produce output,
+   else they produce nothing.  The default is ``False``.
diff --git a/doc/ext/viewcode.rst b/doc/ext/viewcode.rst
index ba6c8f86..6e77914d 100644
--- a/doc/ext/viewcode.rst
+++ b/doc/ext/viewcode.rst
@@ -16,4 +16,5 @@ descriptions that leads to the source code of the described object.  A link back
 from the source to the description will also be inserted.
 
 There are currently no configuration values for this extension; you just need to
-add ``'sphinx.ext.viewcode'`` to your :confval:`extensions` value for it to work.
+add ``'sphinx.ext.viewcode'`` to your :confval:`extensions` value for it to
+work.
diff --git a/doc/extdev/appapi.rst b/doc/extdev/appapi.rst
index 4edab5db..1a0b95bf 100644
--- a/doc/extdev/appapi.rst
+++ b/doc/extdev/appapi.rst
@@ -131,8 +131,8 @@ package.
      The directive class must inherit from the class
      ``docutils.parsers.rst.Directive``.
 
-   For example, the (already existing) :rst:dir:`literalinclude` directive would be
-   added like this:
+   For example, the (already existing) :rst:dir:`literalinclude` directive would
+   be added like this:
 
    .. code-block:: python
 
@@ -232,8 +232,8 @@ package.
    directive it generates must be empty, and will produce no output.
 
    That means that you can add semantic targets to your sources, and refer to
-   them using custom roles instead of generic ones (like :rst:role:`ref`).  Example
-   call::
+   them using custom roles instead of generic ones (like :rst:role:`ref`).
+   Example call::
 
       app.add_crossref_type('topic', 'topic', 'single: %s', docutils.nodes.emphasis)
 
diff --git a/doc/faq.rst b/doc/faq.rst
index 7aa35d1f..7a49aed6 100644
--- a/doc/faq.rst
+++ b/doc/faq.rst
@@ -10,9 +10,9 @@ How do I...
 -----------
 
 ... create PDF files without LaTeX?
-   You can use `rst2pdf <http://rst2pdf.googlecode.com>`_ version 0.12 or greater
-   which comes with built-in Sphinx integration.  See the :ref:`builders`
-   section for details.
+   You can use `rst2pdf <http://rst2pdf.googlecode.com>`_ version 0.12 or
+   greater which comes with built-in Sphinx integration.  See the
+   :ref:`builders` section for details.
 
 ... get section numbers?
    They are automatic in LaTeX output; for HTML, give a ``:numbered:`` option to
@@ -32,9 +32,9 @@ How do I...
    See the :ref:`extension tutorial <exttut>`.
 
 ... convert from my existing docs using MoinMoin markup?
-   The easiest way is to convert to xhtml, then convert `xhtml to reST`_.  You'll
-   still need to mark up classes and such, but the headings and code examples
-   come through cleanly.
+   The easiest way is to convert to xhtml, then convert `xhtml to reST`_.
+   You'll still need to mark up classes and such, but the headings and code
+   examples come through cleanly.
 
 ... create HTML slides from Sphinx documents?
    See the "Hieroglyph" package at https://github.com/nyergler/hieroglyph.
@@ -50,10 +50,11 @@ Using Sphinx with...
 --------------------
 
 Read the Docs
-    https://readthedocs.org is a documentation hosting service based around Sphinx.
-    They will host sphinx documentation, along with supporting a number of other
-    features including version support, PDF generation, and more. The `Getting
-    Started <http://read-the-docs.readthedocs.org/en/latest/getting_started.html>`_
+    https://readthedocs.org is a documentation hosting service based around
+    Sphinx. They will host sphinx documentation, along with supporting a number
+    of other features including version support, PDF generation, and more. The
+    `Getting Started
+    <http://read-the-docs.readthedocs.org/en/latest/getting_started.html>`_
     guide is a good place to start.
 
 Epydoc
@@ -70,8 +71,8 @@ SCons
 
 PyPI
    Jannis Leidel wrote a `setuptools command
-   <https://pypi.python.org/pypi/Sphinx-PyPI-upload>`_ that automatically uploads
-   Sphinx documentation to the PyPI package documentation area at
+   <https://pypi.python.org/pypi/Sphinx-PyPI-upload>`_ that automatically
+   uploads Sphinx documentation to the PyPI package documentation area at
    http://pythonhosted.org/.
 
 GitHub Pages
diff --git a/doc/glossary.rst b/doc/glossary.rst
index 8bc393eb..399e93a1 100644
--- a/doc/glossary.rst
+++ b/doc/glossary.rst
@@ -37,11 +37,11 @@ Glossary
    document name
       Since reST source files can have different extensions (some people like
       ``.txt``, some like ``.rst`` -- the extension can be configured with
-      :confval:`source_suffix`) and different OSes have different path separators,
-      Sphinx abstracts them: :dfn:`document names` are always relative to the
-      :term:`source directory`, the extension is stripped, and path separators
-      are converted to slashes.  All values, parameters and such referring to
-      "documents" expect such document names.
+      :confval:`source_suffix`) and different OSes have different path
+      separators, Sphinx abstracts them: :dfn:`document names` are always
+      relative to the :term:`source directory`, the extension is stripped, and
+      path separators are converted to slashes.  All values, parameters and such
+      referring to "documents" expect such document names.
 
       Examples for document names are ``index``, ``library/zipfile``, or
       ``reference/datamodel/types``.  Note that there is no leading or trailing
@@ -70,8 +70,8 @@ Glossary
 
    object
       The basic building block of Sphinx documentation.  Every "object
-      directive" (e.g. :rst:dir:`function` or :rst:dir:`object`) creates such a block;
-      and most objects can be cross-referenced to.
+      directive" (e.g. :rst:dir:`function` or :rst:dir:`object`) creates such a
+      block; and most objects can be cross-referenced to.
 
    role
       A reStructuredText markup element that allows marking a piece of text.
diff --git a/doc/intl.rst b/doc/intl.rst
index fb8c0f9b..f16ffe5f 100644
--- a/doc/intl.rst
+++ b/doc/intl.rst
@@ -38,9 +38,9 @@ task to split up paragraphs which are too large as there is no sane automated
 way to do that.
 
 After Sphinx successfully ran the
-:class:`~sphinx.builders.gettext.MessageCatalogBuilder` you will find a collection
-of ``.pot`` files in your output directory.  These are **catalog templates**
-and contain messages in your original language *only*.
+:class:`~sphinx.builders.gettext.MessageCatalogBuilder` you will find a
+collection of ``.pot`` files in your output directory.  These are **catalog
+templates** and contain messages in your original language *only*.
 
 They can be delivered to translators which will transform them to ``.po`` files
 --- so called **message catalogs** --- containing a mapping from the original
diff --git a/doc/invocation.rst b/doc/invocation.rst
index 37718fe8..206fd200 100644
--- a/doc/invocation.rst
+++ b/doc/invocation.rst
@@ -83,8 +83,8 @@ The :program:`sphinx-build` script has several options:
 
 .. option:: -t tag
 
-   Define the tag *tag*.  This is relevant for :rst:dir:`only` directives that only
-   include their content if this tag is set.
+   Define the tag *tag*.  This is relevant for :rst:dir:`only` directives that
+   only include their content if this tag is set.
 
    .. versionadded:: 0.6
 
diff --git a/doc/man/sphinx-build.rst b/doc/man/sphinx-build.rst
index aa1d71c6..13564ff4 100644
--- a/doc/man/sphinx-build.rst
+++ b/doc/man/sphinx-build.rst
@@ -102,12 +102,14 @@ Options
                       Configuration can only be set with the -D option.
 -D <setting=value>    Override a setting from the configuration file.
 -t <tag>              Define *tag* for use in "only" blocks.
--A <name=value>       Pass a value into the HTML templates (only for HTML builders).
+-A <name=value>       Pass a value into the HTML templates (only for HTML
+                      builders).
 -n                    Run in nit-picky mode, warn about all missing references.
 -v                    Increase verbosity (can be repeated).
 -N                    Prevent colored output.
 -q                    Quiet operation, just print warnings and errors on stderr.
--Q                    Very quiet operation, don't print anything except for errors.
+-Q                    Very quiet operation, don't print anything except for
+                      errors.
 -w <file>             Write warnings and errors into the given file, in addition
                       to stderr.
 -W                    Turn warnings into errors.
diff --git a/doc/markup/code.rst b/doc/markup/code.rst
index ab387c6d..9dafdb18 100644
--- a/doc/markup/code.rst
+++ b/doc/markup/code.rst
@@ -79,8 +79,8 @@ option::
 
 This will produce line numbers for all code blocks longer than five lines.
 
-For :rst:dir:`code-block` blocks, a ``linenos`` flag option can be given to switch
-on line numbers for the individual block::
+For :rst:dir:`code-block` blocks, a ``linenos`` flag option can be given to
+switch on line numbers for the individual block::
 
    .. code-block:: ruby
       :linenos:
@@ -119,10 +119,10 @@ Includes
 
 .. rst:directive:: .. literalinclude:: filename
 
-   Longer displays of verbatim text may be included by storing the example text in
-   an external file containing only plain text.  The file may be included using the
-   ``literalinclude`` directive. [1]_ For example, to include the Python source file
-   :file:`example.py`, use::
+   Longer displays of verbatim text may be included by storing the example text
+   in an external file containing only plain text.  The file may be included
+   using the ``literalinclude`` directive. [1]_ For example, to include the
+   Python source file :file:`example.py`, use::
 
       .. literalinclude:: example.py
 
diff --git a/doc/markup/inline.rst b/doc/markup/inline.rst
index 69dd832f..b782c330 100644
--- a/doc/markup/inline.rst
+++ b/doc/markup/inline.rst
@@ -102,9 +102,10 @@ Cross-referencing arbitrary locations
      to, but you must give the link an explicit title, using this syntax:
      ``:ref:`Link title <label-name>```.
 
-   Using :rst:role:`ref` is advised over standard reStructuredText links to sections
-   (like ```Section title`_``) because it works across files, when section
-   headings are changed, and for all builders that support cross-references.
+   Using :rst:role:`ref` is advised over standard reStructuredText links to
+   sections (like ```Section title`_``) because it works across files, when
+   section headings are changed, and for all builders that support
+   cross-references.
 
 
 Cross-referencing documents
@@ -349,8 +350,8 @@ the standard reST markup for that purpose.
 Substitutions
 ~~~~~~~~~~~~~
 
-The documentation system provides three substitutions that are defined by default.
-They are set in the build configuration file.
+The documentation system provides three substitutions that are defined by
+default. They are set in the build configuration file.
 
 .. describe:: |release|
 
diff --git a/doc/markup/misc.rst b/doc/markup/misc.rst
index 2b069601..53478806 100644
--- a/doc/markup/misc.rst
+++ b/doc/markup/misc.rst
@@ -58,10 +58,10 @@ Meta-information markup
 
 .. rst:directive:: .. codeauthor:: name <email>
 
-   The :rst:dir:`codeauthor` directive, which can appear multiple times, names the
-   authors of the described code, just like :rst:dir:`sectionauthor` names the
-   author(s) of a piece of documentation.  It too only produces output if the
-   :confval:`show_authors` configuration value is True.
+   The :rst:dir:`codeauthor` directive, which can appear multiple times, names
+   the authors of the described code, just like :rst:dir:`sectionauthor` names
+   the author(s) of a piece of documentation.  It too only produces output if
+   the :confval:`show_authors` configuration value is True.
 
 
 Index-generating markup
diff --git a/doc/markup/para.rst b/doc/markup/para.rst
index b532bc63..c6a49b15 100644
--- a/doc/markup/para.rst
+++ b/doc/markup/para.rst
@@ -70,12 +70,12 @@ units as well as normal text:
    external documents.  These lists are created using the :rst:dir:`seealso`
    directive.
 
-   The :rst:dir:`seealso` directive is typically placed in a section just before any
-   sub-sections.  For the HTML output, it is shown boxed off from the main flow
-   of the text.
+   The :rst:dir:`seealso` directive is typically placed in a section just before
+   any subsections.  For the HTML output, it is shown boxed off from the main
+   flow of the text.
 
-   The content of the :rst:dir:`seealso` directive should be a reST definition list.
-   Example::
+   The content of the :rst:dir:`seealso` directive should be a reST definition
+   list. Example::
 
       .. seealso::
 
@@ -206,8 +206,8 @@ the definition of the symbol.  There is this directive:
    continuation line must begin with a colon placed at the same column as in the
    first line.
 
-   The argument to :rst:dir:`productionlist` serves to distinguish different sets of
-   production lists that belong to different grammars.
+   The argument to :rst:dir:`productionlist` serves to distinguish different
+   sets of production lists that belong to different grammars.
 
    Blank lines are not allowed within ``productionlist`` directive arguments.
 
diff --git a/doc/rest.rst b/doc/rest.rst
index b35ebc91..1493db83 100644
--- a/doc/rest.rst
+++ b/doc/rest.rst
@@ -484,5 +484,6 @@ There are some problems one commonly runs into while authoring reST documents:
 
 .. rubric:: Footnotes
 
-.. [1] When the default domain contains a :rst:dir:`class` directive, this directive
-       will be shadowed.  Therefore, Sphinx re-exports it as :rst:dir:`rst-class`.
+.. [1] When the default domain contains a :rst:dir:`class` directive, this
+       directive will be shadowed.  Therefore, Sphinx re-exports it as
+       :rst:dir:`rst-class`.