Merging upstream version 7.4.7.

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

5 files changed, 335 insertions, 145 deletions

diff --git a/doc/usage/restructuredtext/basics.rst b/doc/usage/restructuredtext/basics.rst
index 7aab544..5354748 100644
--- a/doc/usage/restructuredtext/basics.rst
+++ b/doc/usage/restructuredtext/basics.rst
@@ -9,24 +9,26 @@ reStructuredText Primer
 reStructuredText is the default plaintext markup language used by Sphinx.  This
 section is a brief introduction to reStructuredText (reST) concepts and syntax,
 intended to provide authors with enough information to author documents
-productively.  Since reST was designed to be a simple, unobtrusive markup
+productively.  Since reStructuredText was designed to be a simple, unobtrusive markup
 language, this will not take too long.
 
 .. seealso::
 
    The authoritative `reStructuredText User Documentation
-   <https://docutils.sourceforge.io/rst.html>`_.  The "ref" links in this
-   document link to the description of the individual constructs in the reST
-   reference.
+   <https://docutils.sourceforge.io/rst.html>`_.
+   The "ref" links in this document link to the description of
+   the individual constructs in the reStructuredText reference.
 
 
 Paragraphs
 ----------
 
-The paragraph (:duref:`ref <paragraphs>`) is the most basic block in a reST
-document.  Paragraphs are simply chunks of text separated by one or more blank
-lines.  As in Python, indentation is significant in reST, so all lines of the
-same paragraph must be left-aligned to the same level of indentation.
+The paragraph (:duref:`ref <paragraphs>`) is the most basic block
+in a reStructuredText document.
+Paragraphs are simply chunks of text separated by one or more blank lines.
+As in Python, indentation is significant in reStructuredText,
+so all lines of the same paragraph must be left-aligned
+to the same level of indentation.
 
 
 .. _rst-inline-markup:
@@ -34,7 +36,7 @@ same paragraph must be left-aligned to the same level of indentation.
 Inline markup
 -------------
 
-The standard reST inline markup is quite simple: use
+The standard reStructuredText inline markup is quite simple: use
 
 * one asterisk: ``*text*`` for emphasis (italics),
 * two asterisks: ``**text**`` for strong emphasis (boldface), and
@@ -53,7 +55,7 @@ Be aware of some restrictions of this markup:
 These restrictions may be lifted in future versions of the docutils.
 
 It is also possible to replace or expand upon some of this inline markup with
-roles. Refer to :ref:`rst-roles-alt` for more information.
+roles. Refer to :ref:`rst-roles` for more information.
 
 
 Lists and Quote-like blocks
@@ -220,8 +222,8 @@ You can also separate the link and the target definition (:duref:`ref
 Internal links
 ~~~~~~~~~~~~~~
 
-Internal linking is done via a special reST role provided by Sphinx, see the
-section on specific markup, :ref:`ref-role`.
+Internal linking is done via a special reStructuredText role provided by Sphinx,
+see the section on specific markup, :ref:`ref-role`.
 
 
 .. _rst-sections:
@@ -250,7 +252,7 @@ follow:
 * ``^`` for subsubsections
 * ``"`` for paragraphs
 
-Of course, you are free to use your own marker characters (see the reST
+Of course, you are free to use your own marker characters (see the reStructuredText
 documentation), and use a deeper nesting level, but keep in mind that most
 target formats (HTML, LaTeX) have a limited supported nesting depth.
 
@@ -281,10 +283,7 @@ at the beginning of documents.  Refer to :doc:`field-lists` for more
 information.
 
 
-.. TODO This ref should be 'rst-roles', but that already exists. Rename the
-.. other ones
-
-.. _rst-roles-alt:
+.. _rst-roles:
 
 Roles
 -----
@@ -311,8 +310,8 @@ Refer to :doc:`roles` for roles added by Sphinx.
 Explicit Markup
 ---------------
 
-"Explicit markup" (:duref:`ref <explicit-markup-blocks>`) is used in reST for
-most constructs that need special handling, such as footnotes,
+"Explicit markup" (:duref:`ref <explicit-markup-blocks>`) is used in
+reStructuredText for most constructs that need special handling, such as footnotes,
 specially-highlighted paragraphs, comments, and generic directives.
 
 An explicit markup block begins with a line starting with ``..`` followed by
@@ -328,8 +327,8 @@ Directives
 ----------
 
 A directive (:duref:`ref <directives>`) is a generic block of explicit markup.
-Along with roles, it is one of the extension mechanisms of reST, and Sphinx
-makes heavy use of it.
+Along with roles, it is one of the extension mechanisms of reStructuredText,
+and Sphinx makes heavy use of it.
 
 Docutils supports the following directives:
 
@@ -380,6 +379,12 @@ Docutils supports the following directives:
        When the default domain contains a ``class`` directive, this directive
        will be shadowed.  Therefore, Sphinx re-exports it as ``rst-class``.
 
+    .. tip::
+
+       If you want to add a class to a directive,
+       you may consider the ``:class:`` :dudir:`option <common-options>` instead,
+       which is supported by most directives and allows for a more compact notation.
+
 * HTML specifics:
 
   - :dudir:`meta`
@@ -444,7 +449,7 @@ it does not start with a space.
 Images
 ------
 
-reST supports an image directive (:dudir:`ref <image>`), used like so::
+reStructuredText supports an image directive (:dudir:`ref <image>`), used like so::
 
    .. image:: gnu.png
       (options)
@@ -510,9 +515,9 @@ footnotes without names (``[#]_``).
 Citations
 ---------
 
-Standard reST citations (:duref:`ref <citations>`) are supported, with the
-additional feature that they are "global", i.e. all citations can be referenced
-from all files.  Use them like so::
+Standard reStructuredText citations (:duref:`ref <citations>`) are supported,
+with the additional feature that they are "global",
+i.e. all citations can be referenced from all files.  Use them like so::
 
    Lorem ipsum [Ref]_ dolor sit amet.
 
@@ -525,9 +530,9 @@ numeric or begins with ``#``.
 Substitutions
 -------------
 
-reST supports "substitutions" (:duref:`ref <substitution-definitions>`), which
-are pieces of text and/or markup referred to in the text by ``|name|``.  They
-are defined like footnotes with explicit markup blocks, like this::
+reStructuredText supports "substitutions" (:duref:`ref <substitution-definitions>`),
+which are pieces of text and/or markup referred to in the text by ``|name|``.
+They are defined like footnotes with explicit markup blocks, like this::
 
    .. |name| replace:: replacement *text*
 
@@ -536,8 +541,8 @@ or this::
    .. |caution| image:: warning.png
                 :alt: Warning!
 
-See the :duref:`reST reference for substitutions <substitution-definitions>`
-for details.
+See the :duref:`reStructuredText reference for substitutions
+<substitution-definitions>` for details.
 
 .. index:: ! pair: global; substitutions
 
@@ -584,7 +589,7 @@ directive::
 
 will generate the following HTML output:
 
-.. code:: html
+.. code-block:: html
 
    <meta name="description" content="The Sphinx documentation builder">
    <meta name="keywords" content="Sphinx, documentation, builder">
@@ -612,7 +617,7 @@ Source encoding
 ---------------
 
 Since the easiest way to include special characters like em dashes or copyright
-signs in reST is to directly write them as Unicode characters, one has to
+signs in reStructuredText is to directly write them as Unicode characters, one has to
 specify an encoding.  Sphinx assumes source files to be encoded in UTF-8 by
 default; you can change this with the :confval:`source_encoding` config value.
 
@@ -620,7 +625,8 @@ default; you can change this with the :confval:`source_encoding` config value.
 Gotchas
 -------
 
-There are some problems one commonly runs into while authoring reST documents:
+There are some problems one commonly runs into
+while authoring reStructuredText documents:
 
 * **Separation of inline markup:** As said above, inline markup spans must be
   separated from the surrounding text by non-word characters, you have to use a
diff --git a/doc/usage/restructuredtext/directives.rst b/doc/usage/restructuredtext/directives.rst
index ff42524..19079d2 100644
--- a/doc/usage/restructuredtext/directives.rst
+++ b/doc/usage/restructuredtext/directives.rst
@@ -24,10 +24,11 @@ Table of contents
 
 .. index:: pair: table of; contents
 
-Since reST does not have facilities to interconnect several documents, or split
-documents into multiple output files, Sphinx uses a custom directive to add
-relations between the single files the documentation is made of, as well as
-tables of contents.  The ``toctree`` directive is the central element.
+Since reStructuredText does not have facilities to interconnect several documents,
+or split documents into multiple output files,
+Sphinx uses a custom directive to add relations between
+the single files the documentation is made of, as well as tables of contents.
+The ``toctree`` directive is the central element.
 
 .. note::
 
@@ -37,7 +38,7 @@ tables of contents.  The ``toctree`` directive is the central element.
 .. note::
 
    To create table of contents for current document (.rst file), use the
-   standard reST :dudir:`contents directive <table-of-contents>`.
+   standard reStructuredText :dudir:`contents directive <table-of-contents>`.
 
 .. rst:directive:: toctree
 
@@ -49,8 +50,8 @@ tables of contents.  The ``toctree`` directive is the central element.
    indicate the depth of the tree; by default, all levels are included. [#]_
 
    The representation of "TOC tree" is changed in each output format.  The
-   builders that output multiple files (ex. HTML) treat it as a collection of
-   hyperlinks.  On the other hand, the builders that output a single file (ex.
+   builders that output multiple files (e.g. HTML) treat it as a collection of
+   hyperlinks.  On the other hand, the builders that output a single file (e.g.
    LaTeX, man page, etc.) replace it with the content of the documents on the
    TOC tree.
 
@@ -79,7 +80,7 @@ tables of contents.  The ``toctree`` directive is the central element.
 
    Document titles in the :rst:dir:`toctree` will be automatically read from the
    title of the referenced document. If that isn't what you want, you can
-   specify an explicit title and target using a similar syntax to reST
+   specify an explicit title and target using a similar syntax to reStructuredText
    hyperlinks (and Sphinx's :ref:`cross-referencing syntax <xref-syntax>`). This
    looks like::
 
@@ -124,6 +125,14 @@ tables of contents.  The ``toctree`` directive is the central element.
 
          foo
 
+   As with :dudir:`most directives <common-options>`,
+   you can use the ``class`` option to assign `class attributes`_::
+
+      .. toctree::
+         :class: custom-toc
+
+   .. _class attributes: https://docutils.sourceforge.io/docs/ref/doctree.html#classes
+
    If you want only the titles of documents in the tree to show up, not other
    headings of the same level, you can use the ``titlesonly`` option::
 
@@ -223,150 +232,327 @@ tables of contents.  The ``toctree`` directive is the central element.
 Special names
 ^^^^^^^^^^^^^
 
+.. index:: pair: genindex; toctree
+           pair: modindex; toctree
+           pair: search; toctree
+
 Sphinx reserves some document names for its own use; you should not try to
 create documents with these names -- it will cause problems.
 
 The special document names (and pages generated for them) are:
 
-* ``genindex``, ``modindex``, ``search``
+* ``genindex``
 
-  These are used for the general index, the Python module index, and the search
-  page, respectively.
+  This is used for the general index,
+  which is populated with entries from :rst:dir:`index` directives
+  and all index-generating :ref:`object descriptions <basic-domain-markup>`.
+  For example, see Sphinx's :ref:`genindex`.
 
-  The general index is populated with entries from modules, all
-  index-generating :ref:`object descriptions <basic-domain-markup>`, and from
-  :rst:dir:`index` directives.
+* ``modindex``
 
-  The Python module index contains one entry per :rst:dir:`py:module`
-  directive.
+  This is used for the Python module index,
+  which contains one entry per :rst:dir:`py:module` directive.
+  For example, see Sphinx's :ref:`py-modindex`.
 
-  The search page contains a form that uses the generated JSON search index and
-  JavaScript to full-text search the generated documents for search words; it
-  should work on every major browser that supports modern JavaScript.
+* ``search``
 
-* every name beginning with ``_``
+  This is used for the search page,
+  which contains a form that uses the generated JSON search index and JavaScript
+  to full-text search the generated documents for search words;
+  it works on every major browser.
+  For example, see Sphinx's :ref:`search`.
 
-  Though few such names are currently used by Sphinx, you should not
-  create documents or document-containing directories with such names.  (Using
-  ``_`` as a prefix for a custom template directory is fine.)
+* Every name beginning with ``_``
 
-.. warning::
+  Though few such names are currently used by Sphinx,
+  you should not create documents or document-containing directories with such names.
+  (Using ``_`` as a prefix for a custom template directory is fine.)
 
-   Be careful with unusual characters in filenames.  Some formats may interpret
-   these characters in unexpected ways:
+.. warning::
 
-   * Do not use the colon ``:`` for HTML based formats.  Links to other parts
-     may not work.
+   Be careful with unusual characters in filenames.
+   Some formats may interpret these characters in unexpected ways:
 
-   * Do not use the plus ``+`` for the ePub format.  Some resources may not be
-     found.
+   * Do not use the colon ``:`` for HTML based formats.
+     Links to other parts may not work.
+   * Do not use the plus ``+`` for the ePub format.
+     Some resources may not be found.
 
 
 Paragraph-level markup
 ----------------------
 
-.. index:: note, warning
-           pair: changes; in version
-
 These directives create short paragraphs and can be used inside information
 units as well as normal text.
 
+
+Admonitions, messages, and warnings
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. index:: admonition, admonitions
+           pair: attention; admonition
+           pair: caution; admonition
+           pair: danger; admonition
+           pair: error; admonition
+           pair: hint; admonition
+           pair: important; admonition
+           pair: note; admonition
+           pair: tip; admonition
+           pair: warning; admonition
+
+The admonition directives create 'admonition' elements,
+a standardised system of communicating different types of information,
+from a helpful :rst:dir:`tip` to matters of paramount :rst:dir:`danger`.
+These directives can be used anywhere an ordinary body element can,
+and can contain arbitrary body elements.
+There are nine specific named admonitions
+and the generic :rst:dir:`admonition` directive.
+
+.. rst:directive:: .. attention::
+
+   Information that requires the reader's attention.
+   The content of the directive should be written in complete sentences
+   and include all appropriate punctuation.
+
+   Example:
+
+   .. attention::
+
+      Please may I have your attention.
+
+.. rst:directive:: .. caution::
+
+   Information with regard to which the reader should exercise care.
+   The content of the directive should be written in complete sentences
+   and include all appropriate punctuation.
+
+   Example:
+
+   .. caution::
+
+      Exercise due caution.
+
+.. rst:directive:: .. danger::
+
+   Information which may lead to near and present danger if not heeded.
+   The content of the directive should be written in complete sentences
+   and include all appropriate punctuation.
+
+   Example:
+
+   .. danger::
+
+      Let none think to fly the danger for soon or late love is his own avenger.
+
+.. rst:directive:: .. error::
+
+   Information relating to failure modes of some description.
+   The content of the directive should be written in complete sentences
+   and include all appropriate punctuation.
+
+   Example:
+
+   .. error::
+
+      ERROR 418: I'm a teapot.
+
+.. rst:directive:: .. hint::
+
+   Information that is helpful to the reader.
+   The content of the directive should be written in complete sentences
+   and include all appropriate punctuation.
+
+   Example:
+
+   .. hint::
+
+      Look under the flowerpot.
+
+.. rst:directive:: .. important::
+
+   Information that is of paramount importance
+   and which the reader must not ignore.
+   The content of the directive should be written in complete sentences
+   and include all appropriate punctuation.
+
+   Example:
+
+   .. important::
+
+      This is a statement of paramount importance.
+
 .. rst:directive:: .. note::
 
-   An especially important bit of information about an API that a user should be
-   aware of when using whatever bit of API the note pertains to.  The content of
-   the directive should be written in complete sentences and include all
-   appropriate punctuation.
+   An especially important bit of information that the reader should know.
+   The content of the directive should be written in complete sentences
+   and include all appropriate punctuation.
 
-   Example::
+   Example:
+
+   .. note::
+
+      This function is not suitable for sending tins of spam.
+
+.. rst:directive:: .. tip::
 
-      .. note::
+   Some useful tidbit of information for the reader.
+   The content of the directive should be written in complete sentences
+   and include all appropriate punctuation.
 
-         This function is not suitable for sending spam e-mails.
+   Example:
+
+   .. tip::
+
+      Remember your sun cream!
 
 .. rst:directive:: .. warning::
 
-   An important bit of information about an API that a user should be very aware
-   of when using whatever bit of API the warning pertains to.  The content of
-   the directive should be written in complete sentences and include all
-   appropriate punctuation. This differs from :rst:dir:`note` in that it is
-   recommended over :rst:dir:`note` for information regarding security.
+   An important bit of information that the reader should be very aware of.
+   The content of the directive should be written in complete sentences
+   and include all appropriate punctuation.
+
+   Example:
 
-.. rst:directive:: .. versionadded:: version
+   .. warning::
+
+      Beware of the dog.
+
+.. rst:directive:: .. admonition:: title
+
+   A generic admonition, with an optional title.
+   The content of the directive should be written in complete sentences
+   and include all appropriate punctuation.
+
+   Example:
+
+   .. admonition:: This is a title
+
+      This is the content of the admonition.
+
+
+.. rst:directive:: seealso
+
+   Many sections include a list of references to module documentation or
+   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 subsections.
+   The content of the :rst:dir:`seealso` directive should be
+   either a single line or a reStructuredText `definition list`_.
 
-   This directive documents the version of the project which added the described
-   feature to the library or C API. When this applies to an entire module, it
-   should be placed at the top of the module section before any prose.
+   .. _definition list: https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#definition-lists
+
+   Example::
+
+      .. seealso::
+
+         Python's :py:mod:`zipfile` module
+            Documentation of Python's standard :py:mod:`zipfile` module.
+
+         `GNU tar manual, Basic Tar Format <https://example.org>`_
+            Documentation for tar archive files, including GNU tar extensions.
+
+   .. seealso::
+
+      Module :py:mod:`zipfile`
+         Documentation of the :py:mod:`zipfile` standard module.
+
+      `GNU tar manual, Basic Tar Format <https://example.org>`_
+         Documentation for tar archive files, including GNU tar extensions.
+
+
+Describing changes between versions
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. index:: pair: added; in version
+           pair: changes; in version
+           pair: removed; in version
+
+.. rst:directive:: .. versionadded:: version [brief explanation]
+
+   This directive documents the version of the project
+   which added the described feature.
+   When this applies to an entire module or component,
+   it should be placed at the top of the relevant section before any prose.
 
    The first argument must be given and is the version in question; you can add
    a second argument consisting of a *brief* explanation of the change.
 
+   .. attention::
+      There must be no blank line between the directive head and the explanation;
+      this is to make these blocks visually continuous in the markup.
+
    Example::
 
       .. versionadded:: 2.5
          The *spam* parameter.
 
-   Note that there must be no blank line between the directive head and the
-   explanation; this is to make these blocks visually continuous in the markup.
+   .. versionadded:: 2.5
+      The *spam* parameter.
 
-.. rst:directive:: .. versionchanged:: version
+.. rst:directive:: .. versionchanged:: version [brief explanation]
 
    Similar to :rst:dir:`versionadded`, but describes when and what changed in
    the named feature in some way (new parameters, changed side effects, etc.).
 
-.. rst:directive:: .. deprecated:: version
+   Example::
 
-   Similar to :rst:dir:`versionchanged`, but describes when the feature was
-   deprecated.  An explanation can also be given, for example to inform the
-   reader what should be used instead.  Example::
+      .. versionchanged:: 2.8
+         The *spam* parameter is now of type *boson*.
 
-      .. deprecated:: 3.1
-         Use :func:`spam` instead.
+   .. versionchanged:: 2.8
+      The *spam* parameter is now of type *boson*.
 
-.. rst:directive:: .. versionremoved:: version
+.. rst:directive:: .. deprecated:: version [brief explanation]
+
+   Similar to :rst:dir:`versionadded`, but describes when the feature was
+   deprecated.
+   A *brief* explanation can also be given,
+   for example to tell the reader what to use instead.
 
-   Similar to :rst:dir:`versionadded`, but describes when the feature was removed.
-   An explanation may be provided to inform the reader what to use instead,
-   or why the feature was removed.
    Example::
 
-      .. versionremoved:: 4.0
-         The :func:`spam` function is more flexible, and should be used instead.
+      .. deprecated:: 3.1
+         Use :py:func:`spam` instead.
 
-   .. versionadded:: 7.3
+   .. deprecated:: 3.1
+      Use :py:func:`!spam` instead.
 
-.. rst:directive:: seealso
+.. rst:directive:: .. versionremoved:: version [brief explanation]
 
-   Many sections include a list of references to module documentation or
-   external documents.  These lists are created using the :rst:dir:`seealso`
-   directive.
+   Similar to :rst:dir:`versionadded`, but describes when the feature was removed.
+   An explanation may be provided to tell the reader what to use instead,
+   or why the feature was removed.
 
-   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.
+   .. versionadded:: 7.3
 
-   The content of the :rst:dir:`seealso` directive should be a reST definition
-   list. Example::
+   Example::
 
-      .. seealso::
+      .. versionremoved:: 4.0
+         The :py:func:`spam` function is more flexible, and should be used instead.
 
-         Module :py:mod:`zipfile`
-            Documentation of the :py:mod:`zipfile` standard module.
+   .. versionremoved:: 4.0
+      The :py:func:`!spam` function is more flexible, and should be used instead.
 
-         `GNU tar manual, Basic Tar Format <https://link>`_
-            Documentation for tar archive files, including GNU tar extensions.
 
-   There's also a "short form" allowed that looks like this::
+Presentational
+^^^^^^^^^^^^^^
+
+.. rst:directive:: .. rubric:: title
 
-      .. seealso:: modules :py:mod:`zipfile`, :py:mod:`tarfile`
+   A rubric is like an informal heading that doesn't correspond to the document's structure,
+   i.e. it does not create a table of contents node.
 
-   .. versionadded:: 0.5
-      The short form.
+   .. rst:directive:option:: heading-level: n
+      :type: number from 1 to 6
 
-.. rst:directive:: .. rubric:: title
+      .. versionadded:: 7.4.1
 
-   This directive creates a paragraph heading that is not used to create a
-   table of contents node.
+      Use this option to specify the heading level of the rubric.
+      In this case the rubric will be rendered as ``<h1>`` to ``<h6>`` for HTML output,
+      or as the corresponding non-numbered sectioning command for LaTeX
+      (see :confval:`latex_toplevel_sectioning`).
 
    .. note::
 
@@ -377,10 +563,7 @@ units as well as normal text.
 
 .. rst:directive:: centered
 
-   This directive creates a centered boldfaced line of text.  Use it as
-   follows::
-
-      .. centered:: LICENSE AGREEMENT
+   This directive creates a centered boldfaced line of text.
 
    .. deprecated:: 1.1
       This presentation-only directive is a legacy from older versions.
@@ -419,8 +602,8 @@ Showing code examples
 There are multiple ways to show syntax-highlighted literal code blocks in
 Sphinx:
 
-* using :ref:`reST doctest blocks <rst-doctest-blocks>`;
-* using :ref:`reST literal blocks <rst-literal-blocks>`, optionally in
+* using :ref:`reStructuredText doctest blocks <rst-doctest-blocks>`;
+* using :ref:`reStructuredText literal blocks <rst-literal-blocks>`, optionally in
   combination with the :rst:dir:`highlight` directive;
 * using the :rst:dir:`code-block` directive;
 * and using the :rst:dir:`literalinclude` directive.
@@ -503,6 +686,7 @@ __ https://pygments.org/docs/lexers
 
 .. rst:directive:: .. code-block:: [language]
                    .. sourcecode:: [language]
+                   .. code:: [language]
 
    Example::
 
@@ -802,8 +986,8 @@ Glossary
 
 .. rst:directive:: .. glossary::
 
-   This directive must contain a reST definition-list-like markup with terms and
-   definitions.  The definitions will then be referenceable with the
+   This directive must contain a reStructuredText definition-list-like markup
+   with terms and definitions.  The definitions will then be referenceable with the
    :rst:role:`term` role.  Example::
 
       .. glossary::
@@ -934,7 +1118,7 @@ mainly contained in information units, such as the language reference.
       (this notation is also used below to describe what entries are created).
       Examples:
 
-      .. code:: reStructuredText
+      .. code-block:: rst
 
          .. index:: single: execution
                     single: execution; context
@@ -947,7 +1131,7 @@ mainly contained in information units, such as the language reference.
       The pair of values must be separated by a semicolon.
       Example:
 
-      .. code:: reStructuredText
+      .. code-block:: rst
 
          .. index:: pair: loop; statement
 
@@ -957,7 +1141,7 @@ mainly contained in information units, such as the language reference.
       All three values must be separated by a semicolon.
       Example:
 
-      .. code:: reStructuredText
+      .. code-block:: rst
 
          .. index:: triple: module; search; path
 
@@ -967,7 +1151,7 @@ mainly contained in information units, such as the language reference.
       A shortcut to create an index entry that refers to another entry.
       Example:
 
-      .. code:: reStructuredText
+      .. code-block:: rst
 
          .. index:: see: entry; other
 
@@ -1034,7 +1218,7 @@ mainly contained in information units, such as the language reference.
    case, the "target" part can be a full entry as described for the directive
    above.  For example::
 
-      This is a normal reST :index:`paragraph` that contains several
+      This is a normal reStructuredText :index:`paragraph` that contains several
       :index:`index entries <pair: index; entry>`.
 
    .. versionadded:: 1.1
@@ -1052,10 +1236,11 @@ Including content based on tags
 
       .. only:: html and draft
 
-   Undefined tags are false, defined tags (via the ``-t`` command-line option or
-   within :file:`conf.py`, see :ref:`here <conf-tags>`) are true.  Boolean
-   expressions, also using parentheses (like ``(latex or html) and draft``) are
-   supported.
+   Undefined tags are false, defined tags are true
+   (tags can be defined via the :option:`--tag <sphinx-build --tag>`
+   command-line option or within :file:`conf.py`, see :ref:`here <conf-tags>`).
+   Boolean expressions (like ``(latex or html) and draft``) are supported
+   and may use parentheses.
 
    The *format* and the *name* of the current builder (``html``, ``latex`` or
    ``text``) are always set as a tag [#]_.  To make the distinction between
@@ -1287,8 +1472,8 @@ the definition of the symbol.  There is this directive:
    an explicit title can be given (e.g., "``myTitle <myGroup:sum>``"),
    or the target can be prefixed with a tilde (e.g., "``~myGroup:sum``").
 
-   Note that no further reST parsing is done in the production, so that you
-   don't have to escape ``*`` or ``|`` characters.
+   Note that no further reStructuredText parsing is done in the production,
+   so that you don't have to escape ``*`` or ``|`` characters.
 
 The following is an example taken from the Python Reference Manual::
 
diff --git a/doc/usage/restructuredtext/field-lists.rst b/doc/usage/restructuredtext/field-lists.rst
index 62dad5c..d352633 100644
--- a/doc/usage/restructuredtext/field-lists.rst
+++ b/doc/usage/restructuredtext/field-lists.rst
@@ -48,9 +48,9 @@ At the moment, these metadata fields are recognized:
 
    .. note::
 
-      This metadata effects to the depth of local toctree.  But it does not
-      effect to the depth of *global* toctree.  So this would not be change
-      the sidebar of some themes which uses global one.
+      This metadata affects the depth of the local toctree.  But it does not
+      affect the depth of the *global* toctree.  So this does not change
+      the sidebar of themes that use the global toctree.
 
    .. versionadded:: 0.4
 
diff --git a/doc/usage/restructuredtext/index.rst b/doc/usage/restructuredtext/index.rst
index 0fe311e..ada40c5 100644
--- a/doc/usage/restructuredtext/index.rst
+++ b/doc/usage/restructuredtext/index.rst
@@ -8,9 +8,8 @@ reStructuredText (reST) is the default plaintext markup language used by both
 Docutils and Sphinx. Docutils provides the basic reStructuredText syntax, while
 Sphinx extends this to support additional functionality.
 
-The below guides go through the most important aspects of reST. For the
-authoritative reStructuredText reference, refer to the `docutils
-documentation`__.
+The below guides go through the most important aspects of reStructuredText.
+For the authoritative reference, refer to the `docutils documentation`__.
 
 __ https://docutils.sourceforge.io/rst.html
 
diff --git a/doc/usage/restructuredtext/roles.rst b/doc/usage/restructuredtext/roles.rst
index b21a2b7..ea5d99c 100644
--- a/doc/usage/restructuredtext/roles.rst
+++ b/doc/usage/restructuredtext/roles.rst
@@ -268,7 +268,7 @@ The following roles generate external links:
    For example: :rfc:`2324`
 
 Note that there are no special roles for including hyperlinks as you can use
-the standard reST markup for that purpose.
+the standard reStructuredText markup for that purpose.
 
 
 .. _default-substitutions: