12 files changed, 85 insertions, 38 deletions
diff --git a/doc/usage/advanced/setuptools.rst b/doc/usage/advanced/setuptools.rst
index f4dfb7f66..7f993e10c 100644
--- a/doc/usage/advanced/setuptools.rst
+++ b/doc/usage/advanced/setuptools.rst
@@ -164,7 +164,7 @@ Options for setuptools integration
 
 .. setuptools-confval:: link-index
 
-   A boolean that ensures index.html will be linked to the master doc. Default
+   A boolean that ensures index.html will be linked to the root doc. Default
    is false.
 
    This can also be set by passing the `-i` flag to ``setup.py``:
diff --git a/doc/usage/advanced/websupport/quickstart.rst b/doc/usage/advanced/websupport/quickstart.rst
index 1c7e7cd35..5fa5b00f1 100644
--- a/doc/usage/advanced/websupport/quickstart.rst
+++ b/doc/usage/advanced/websupport/quickstart.rst
@@ -112,8 +112,8 @@ must update the websupport package's data::
 should be a boolean representing whether the user has moderation privileges.
 The default value for *moderator* is ``False``.
 
-An example `Flask <https://flask.palletsprojects.com/>`_ function that checks whether a
-user is logged in and then retrieves a document is::
+An example `Flask <https://flask.palletsprojects.com/>`_ function that checks
+whether a user is logged in and then retrieves a document is::
 
    from sphinxcontrib.websupport.errors import *
 
@@ -152,8 +152,8 @@ 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
 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 <https://flask.palletsprojects.com/>`_ that would be
-like this::
+retrieve search results. In `Flask <https://flask.palletsprojects.com/>`_ that
+would be like this::
 
    @app.route('/search')
    def search():
diff --git a/doc/usage/builders/index.rst b/doc/usage/builders/index.rst
index 74853fee9..4d5315227 100644
--- a/doc/usage/builders/index.rst
+++ b/doc/usage/builders/index.rst
@@ -51,7 +51,7 @@ The builder's "name" must be given to the **-b** command-line option of
 
    This is an HTML builder that combines the whole project in one output file.
    (Obviously this only works with smaller projects.)  The file is named like
-   the master document.  No indices will be generated.
+   the root document.  No indices will be generated.
 
    .. autoattribute:: name
 
diff --git a/doc/usage/configuration.rst b/doc/usage/configuration.rst
index 73ca1b600..18eae9c19 100644
--- a/doc/usage/configuration.rst
+++ b/doc/usage/configuration.rst
@@ -2712,6 +2712,14 @@ Options for the C domain
 
    .. versionadded:: 3.0
 
+.. confval:: c_extra_keywords
+
+  A list of identifiers to be recognized as keywords by the C parser.
+  It defaults to ``['alignas', 'alignof', 'bool', 'complex', 'imaginary',
+  'noreturn', 'static_assert', 'thread_local']``.
+
+  .. versionadded:: 4.0.3
+
 .. confval:: c_allow_pre_v3
 
    A boolean (default ``False``) controlling whether to parse and try to
diff --git a/doc/usage/extensions/index.rst b/doc/usage/extensions/index.rst
index 0d446cb61..37d71c503 100644
--- a/doc/usage/extensions/index.rst
+++ b/doc/usage/extensions/index.rst
@@ -10,6 +10,8 @@ This chapter describes the extensions bundled with Sphinx.  For the API
 documentation on writing your own extension, refer to :ref:`dev-extensions`.
 
 
+.. _builtin-extensions:
+
 Built-in extensions
 -------------------
 
@@ -38,6 +40,8 @@ These extensions are built in and can be activated by respective entries in the
    viewcode
 
 
+.. _third-party-extensions:
+
 Third-party extensions
 ----------------------
 
diff --git a/doc/usage/extensions/napoleon.rst b/doc/usage/extensions/napoleon.rst
index 2752b1479..68ff98acc 100644
--- a/doc/usage/extensions/napoleon.rst
+++ b/doc/usage/extensions/napoleon.rst
@@ -267,14 +267,9 @@ Google style with types in docstrings::
    `Python 2/3 compatible annotations`_ aren't currently
    supported by Sphinx and won't show up in the docs.
 
-.. _PEP 484:
-   https://www.python.org/dev/peps/pep-0484/
-
-.. _PEP 526:
-    https://www.python.org/dev/peps/pep-0526/
-
-.. _Python 2/3 compatible annotations:
-   https://www.python.org/dev/peps/pep-0484/#suggested-syntax-for-python-2-7-and-straddling-code
+.. _PEP 484: https://www.python.org/dev/peps/pep-0484/
+.. _PEP 526: https://www.python.org/dev/peps/pep-0526/
+.. _Python 2/3 compatible annotations: https://www.python.org/dev/peps/pep-0484/#suggested-syntax-for-python-2-7-and-straddling-code
 
 
 Configuration
@@ -330,9 +325,9 @@ sure that "sphinx.ext.napoleon" is enabled in `conf.py`::
    **If True**::
 
        def __init__(self):
-           \"\"\"
+           """
            This will be included in the docs because it has a docstring
-           \"\"\"
+           """
 
        def __init__(self):
            # This will NOT be included in the docs
@@ -514,7 +509,7 @@ sure that "sphinx.ext.napoleon" is enabled in `conf.py`::
 .. confval:: napoleon_preprocess_types
 
    True to convert the type definitions in the docstrings as references.
-   Defaults to *True*.
+   Defaults to *False*.
 
    .. versionadded:: 3.2.1
    .. versionchanged:: 3.5
diff --git a/doc/usage/installation.rst b/doc/usage/installation.rst
index f0384ea9d..8cf56b501 100644
--- a/doc/usage/installation.rst
+++ b/doc/usage/installation.rst
@@ -185,30 +185,67 @@ the ``--pre`` flag.
 
    $ pip install -U --pre sphinx
 
+Using virtual environments
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+When installing Sphinx using pip,
+it is highly recommended to use *virtual environments*,
+which isolate the installed packages from the system packages,
+thus removing the need to use administrator privileges.
+To create a virtual environment in the ``.venv`` directory,
+use the following command.
+
+::
+
+   $ python -m venv .venv
+
+You can read more about them in the `Python Packaging User Guide`_.
+
+.. _Python Packaging User Guide: https://packaging.python.org/guides/installing-using-pip-and-virtual-environments/#creating-a-virtual-environment
+
+.. warning::
+
+   Note that in some Linux distributions, such as Debian and Ubuntu,
+   this might require an extra installation step as follows.
+
+    .. code-block:: console
+
+       $ apt-get install python3-venv
 
 Docker
 ------
 
-Docker images for Sphinx are published on the `Docker Hub <https://hub.docker.com/>`_. There are two kind of images:
+Docker images for Sphinx are published on the `Docker Hub`_.  There are two kind
+of images:
 
-- `sphinxdoc/sphinx <https://hub.docker.com/repository/docker/sphinxdoc/sphinx>`_
-- `sphinxdoc/sphinx-latexpdf <https://hub.docker.com/repository/docker/sphinxdoc/sphinx-latexpdf>`_
+- `sphinxdoc/sphinx`_
+- `sphinxdoc/sphinx-latexpdf`_
 
-Former one is used for standard usage of Sphinx, and latter one is mainly used for PDF builds using LaTeX.
-Please choose one for your purpose.
+.. _Docker Hub: https://hub.docker.com/
+.. _sphinxdoc/sphinx: https://hub.docker.com/repository/docker/sphinxdoc/sphinx
+.. _sphinxdoc/sphinx-latexpdf: https://hub.docker.com/repository/docker/sphinxdoc/sphinx-latexpdf>
+
+Former one is used for standard usage of Sphinx, and latter one is mainly used for
+PDF builds using LaTeX.  Please choose one for your purpose.
 
 .. note::
 
-   sphinxdoc/sphinx-latexpdf contains TeXLive packages. So the image is very large (over 2GB!).
+   sphinxdoc/sphinx-latexpdf contains TeXLive packages. So the image is very large
+   (over 2GB!).
 
 .. hint::
 
-   When using docker images, please use ``docker run`` command to invoke sphinx commands.  For example,
-   you can use following command to create a Sphinx project::
+   When using docker images, please use ``docker run`` command to invoke sphinx
+   commands.  For example, you can use following command to create a Sphinx
+   project:
+
+   .. code-block:: bash
 
       $ docker run -it --rm -v /path/to/document:/docs sphinxdoc/sphinx sphinx-quickstart
 
-   And you can following command this to build HTML document::
+   And you can following command this to build HTML document:
+
+   .. code-block:: bash
 
       $ docker run --rm -v /path/to/document:/docs sphinxdoc/sphinx make html
 
diff --git a/doc/usage/quickstart.rst b/doc/usage/quickstart.rst
index 83b5211bd..8644a0021 100644
--- a/doc/usage/quickstart.rst
+++ b/doc/usage/quickstart.rst
@@ -48,8 +48,8 @@ Defining document structure
 ---------------------------
 
 Let's assume you've run :program:`sphinx-quickstart`.  It created a source
-directory with :file:`conf.py` and a master document, :file:`index.rst`.  The
-main function of the :term:`master document` is to serve as a welcome page, and
+directory with :file:`conf.py` and a root document, :file:`index.rst`.  The
+main function of the :term:`root document` is to serve as a welcome page, and
 to contain the root of the "table of contents tree" (or *toctree*).  This is one
 of the main things that Sphinx adds to reStructuredText, a way to connect
 multiple files to a single hierarchy of documents.
@@ -74,14 +74,14 @@ multiple files to a single hierarchy of documents.
 
 The ``toctree`` directive initially is empty, and looks like so:
 
-.. code-block:: rest
+.. code-block:: rst
 
    .. toctree::
       :maxdepth: 2
 
 You add documents listing them in the *content* of the directive:
 
-.. code-block:: rest
+.. code-block:: rst
 
    .. toctree::
       :maxdepth: 2
@@ -172,7 +172,7 @@ The most prominent domain is the Python domain. For example, to document
 Python's built-in function ``enumerate()``, you would add this to one of your
 source files.
 
-.. code-block:: restructuredtext
+.. code-block:: rst
 
    .. py:function:: enumerate(sequence[, start=0])
 
@@ -193,7 +193,7 @@ given, each in its own line.
 The Python domain also happens to be the default domain, so you don't need to
 prefix the markup with the domain name.
 
-.. code-block:: restructuredtext
+.. code-block:: rst
 
    .. function:: enumerate(sequence[, start=0])
 
diff --git a/doc/usage/restructuredtext/basics.rst b/doc/usage/restructuredtext/basics.rst
index 1c601ea2e..d96b1fe38 100644
--- a/doc/usage/restructuredtext/basics.rst
+++ b/doc/usage/restructuredtext/basics.rst
@@ -224,6 +224,8 @@ Internal linking is done via a special reST role provided by Sphinx, see the
 section on specific markup, :ref:`ref-role`.
 
 
+.. _rst-sections:
+
 Sections
 --------
 
diff --git a/doc/usage/restructuredtext/directives.rst b/doc/usage/restructuredtext/directives.rst
index 24f3af9d8..2a9743e94 100644
--- a/doc/usage/restructuredtext/directives.rst
+++ b/doc/usage/restructuredtext/directives.rst
@@ -497,10 +497,10 @@ __ https://pygments.org/docs/lexers
          Some Ruby code.
 
    The directive's alias name :rst:dir:`sourcecode` works as well.  This
-   directive takes a language name as an argument.  It can be any lexer alias
-   supported by Pygments.  If it is not given, the setting of
-   :rst:dir:`highlight` directive will be used.  If not set,
-   :confval:`highlight_language` will be used.
+   directive takes a language name as an argument.  It can be `any lexer alias
+   supported by Pygments <https://pygments.org/docs/lexers/>`_.  If it is not
+   given, the setting of :rst:dir:`highlight` directive will be used.
+   If not set, :confval:`highlight_language` will be used.
 
    .. versionchanged:: 2.0
       The ``language`` argument becomes optional.
diff --git a/doc/usage/restructuredtext/domains.rst b/doc/usage/restructuredtext/domains.rst
index dfd347327..e4e16f7bb 100644
--- a/doc/usage/restructuredtext/domains.rst
+++ b/doc/usage/restructuredtext/domains.rst
@@ -1673,7 +1673,7 @@ There is a set of directives allowing documenting command-line programs:
 
       .. program:: svn
 
-      .. option:: -r revision
+      .. option:: -r <revision>
 
          Specify the revision to work upon.
 
diff --git a/doc/usage/theming.rst b/doc/usage/theming.rst
index 8ea574cfd..60bc20e24 100644
--- a/doc/usage/theming.rst
+++ b/doc/usage/theming.rst
@@ -248,7 +248,8 @@ These themes are:
 
 **scrolls**
   A more lightweight theme, based on `the Jinja documentation
-  <https://jinja.palletsprojects.com/>`_.  The following color options are available:
+  <https://jinja.palletsprojects.com/>`_.  The following color options are
+  available:
 
   - **headerbordercolor**
   - **subheadlinecolor**