Merge branch '4.x' into 6525_linkcheck_warn_redirects

doc/_templates/index.html

@@ -33,7 +33,7 @@
     <li>{%trans path=pathto('ext/builtins')%}<b>Extensions:</b> automatic testing of code snippets, inclusion of
       docstrings from Python modules (API docs), and
       <a href="{{ path }}#builtin-sphinx-extensions">more</a>{%endtrans%}</li>
-    <li>{%trans path=pathto("usage/extensions")%}<b>Contributed extensions:</b> dozens of
+    <li>{%trans path=pathto("usage/extensions/index")%}<b>Contributed extensions:</b> dozens of
       extensions <a href="{{ path }}#third-party-extensions">contributed by users</a>;
       most of them installable from PyPI{%endtrans%}</li>
   </ul>
@@ -52,23 +52,25 @@
         <p class="biglink"><a class="biglink" href="{{ pathto("usage/quickstart") }}">{%trans%}First steps with Sphinx{%endtrans%}</a><br/>
            <span class="linkdescr">{%trans%}overview of basic tasks{%endtrans%}</span></p>
       </td><td>
-        {%- if hasdoc('search') %}<p class="biglink"><a class="biglink" href="{{ pathto("search") }}">{%trans%}Search page{%endtrans%}</a><br/>
-           <span class="linkdescr">{%trans%}search the documentation{%endtrans%}</span></p>{%- endif %}
+        <p class="biglink"><a class="biglink" href="{{ pathto("tutorial/index") }}">{%trans%}Tutorial{%endtrans%}</a><br/>
+           <span class="linkdescr">{%trans%}beginners tutorial{%endtrans%}</span></p>
       </td>
     </tr><tr>
       <td>
         <p class="biglink"><a class="biglink" href="{{ pathto("contents") }}">{%trans%}Contents{%endtrans%}</a><br/>
            <span class="linkdescr">{%trans%}for a complete overview{%endtrans%}</span></p>
       </td><td>
-        {%- if hasdoc('genindex') %}<p class="biglink"><a class="biglink" href="{{ pathto("genindex") }}">{%trans%}General Index{%endtrans%}</a><br/>
-           <span class="linkdescr">{%trans%}all functions, classes, terms{%endtrans%}</span></p>{%- endif %}
+        {%- if hasdoc('search') %}<p class="biglink"><a class="biglink" href="{{ pathto("search") }}">{%trans%}Search page{%endtrans%}</a><br/>
+           <span class="linkdescr">{%trans%}search the documentation{%endtrans%}</span></p>{%- endif %}
       </td>
     </tr><tr>
       <td>
         <p class="biglink"><a class="biglink" href="{{ pathto("changes") }}">{%trans%}Changes{%endtrans%}</a><br/>
            <span class="linkdescr">{%trans%}release history{%endtrans%}</span></p>
       </td><td>
-      </td>
+        {%- if hasdoc('genindex') %}<p class="biglink"><a class="biglink" href="{{ pathto("genindex") }}">{%trans%}General Index{%endtrans%}</a><br/>
+           <span class="linkdescr">{%trans%}all functions, classes, terms{%endtrans%}</span></p>{%- endif %}
+      </td><td>
     </tr>
   </table>
 

doc/contents.rst

@@ -7,6 +7,7 @@ Sphinx documentation contents
    :maxdepth: 2
 
    usage/index
+   tutorial/index
    development/index
    man/index
 

doc/development/theming.rst

@@ -207,9 +207,9 @@ inside your module:
 First, define the registration function, which accepts the arguments for
 :event:`html-page-context`.
 
-Within the registration function, define the template function that you'd like to use
-within Jinja. The template function should return a string or Python objects (lists,
-dictionaries) with strings inside that Jinja uses in the templating process
+Within the registration function, define the template function that you'd like to
+use within Jinja. The template function should return a string or Python objects
+(lists, dictionaries) with strings inside that Jinja uses in the templating process
 
 .. note::
 
@@ -256,6 +256,9 @@ Here is some sample code to accomplish this:
 
 .. code-block:: python
 
+   from os import path
+   from sphinx.util.fileutil import copy_asset_file
+
    def copy_custom_files(app, exc):
        if app.builder.format == 'html' and not exc:
            staticdir = path.join(app.builder.outdir, '_static')

doc/extdev/appapi.rst

@@ -159,7 +159,9 @@ connect handlers to the events.  Example:
 
 Below is an overview of each event that happens during a build. In the list
 below, we include the event name, its callback parameters, and the input and output
-type for that event::
+type for that event:
+
+.. code-block:: none
 
    1. event.config-inited(app,config)
    2. event.builder-inited(app)
@@ -168,7 +170,7 @@ type for that event::
 
    for docname in docnames:
       5. event.env-purge-doc(app, env, docname)
-      
+
       if doc changed and not removed:
          6. source-read(app, docname, source)
          7. run source parsers: text -> docutils.document
@@ -176,10 +178,10 @@ type for that event::
          8. apply transforms based on priority: docutils.document -> docutils.document
             - event.doctree-read(app, doctree) is called in the middle of transforms,
               transforms come before/after this event depending on their priority.
-   
+
    9. event.env-merge-info(app, env, docnames, other)
       - if running in parallel mode, this event will be emitted for each process
-   
+
    10. event.env-updated(app, env)
    11. event.env-get-updated(app, env)
    12. event.env-check-consistency(app, env)
@@ -377,13 +379,22 @@ Here is a more detailed list of these events.
    ``'page.html'`` as the HTML template for this page.
 
    .. note:: You can install JS/CSS files for the specific page via
-             :meth:`Sphinx.add_js_file` and :meth:`Sphinx.add_css_file` since v3.5.0.
+             :meth:`Sphinx.add_js_file` and :meth:`Sphinx.add_css_file` since
+             v3.5.0.
 
    .. versionadded:: 0.4
 
    .. versionchanged:: 1.3
       The return value can now specify a template name.
 
+.. event:: linkcheck-process-uri (app, uri)
+
+   Emitted when the linkcheck builder collects hyperlinks from document.  *uri*
+   is a collected URI.  The event handlers can modify the URI by returning a
+   string.
+
+   .. versionadded:: 4.1
+
 .. event:: build-finished (app, exception)
 
    Emitted when a build has finished, before Sphinx exits, usually used for

doc/extdev/deprecated.rst

@@ -750,8 +750,9 @@ The following is a list of deprecated interfaces.
 
    * - ``sphinx.environment.NoUri``
      - 2.1
-     - 4.0
+     - 3.0
      - ``sphinx.errors.NoUri``
+
    * - ``sphinx.ext.apidoc.format_directive()``
      - 2.1
      - 4.0
@@ -1035,7 +1036,7 @@ The following is a list of deprecated interfaces.
 
    * - ``sphinx.util.force_decode()``
      - 2.0
-     - 4.0
+     - 5.0
      - N/A
 
    * - ``sphinx.util.get_matching_docs()``

doc/faq.rst

@@ -259,7 +259,9 @@ The following list gives some hints for the creation of epub files:
 
      ``parent.xhtml`` -> ``child.xhtml`` -> ``parent.xhtml``
 
-  If you get the following error, fix your document structure::
+  If you get the following error, fix your document structure:
+
+  .. code-block:: none
 
      Error(prcgen):E24011: TOC section scope is not included in the parent chapter:(title)
      Error(prcgen):E24001: The table of content could not be built.

doc/glossary.rst

@@ -76,6 +76,9 @@ Glossary
    master document
       The document that contains the root :rst:dir:`toctree` directive.
 
+   root document
+      Same as :term:`master document`.
+
    object
       The basic building block of Sphinx documentation.  Every "object
       directive" (e.g. :rst:dir:`function` or :rst:dir:`object`) creates such a

doc/latex.rst

@@ -282,7 +282,29 @@ Keys that don't need to be overridden unless in special cases are:
    "inputenc" package inclusion.
 
    Default: ``'\\usepackage[utf8]{inputenc}'`` when using pdflatex, else
-   ``''``
+   ``''``.
+
+   .. note::
+
+      If using ``utf8x`` in place of ``utf8`` it is mandatory to extend the
+      LaTeX preamble with suitable ``\PreloadUnicodePage{<number>}`` commands,
+      as per the ``utf8x`` documentation (``texdoc ucs`` on a TeXLive based
+      TeX installation).  Else, unexpected and possibly hard-to-spot problems
+      (i.e. not causing a build crash) may arise in the PDF, in particular
+      regarding hyperlinks.
+
+      Even if these precautions are taken, PDF build via ``pdflatex`` engine
+      may crash due to upstream LaTeX not being fully compatible with
+      ``utf8x``.  For example, in certain circumstances related to
+      code-blocks, or attempting to include images whose filenames contain
+      Unicode characters.  Indeed, starting in 2015, upstream LaTeX with
+      ``pdflatex`` engine has somewhat enhanced native support for Unicode and
+      is becoming more and more incompatible with ``utf8x``.  In particular,
+      since the October 2019 LaTeX release, filenames can use Unicode
+      characters, and even spaces.  At Sphinx level this means e.g. that the
+      :dudir:`image` and :dudir:`figure` directives are now compatible with
+      such filenames for PDF via LaTeX output.  But this is broken if
+      ``utf8x`` is in use.
 
    .. versionchanged:: 1.4.3
       Previously ``'\\usepackage[utf8]{inputenc}'`` was used for all

doc/templating.rst

@@ -115,7 +115,7 @@ The following blocks exist in the ``layout.html`` template:
 ``rootrellink``, ``relbaritems``
     Inside the relbar there are three sections: The ``rootrellink``, the links
     from the documentation and the custom ``relbaritems``.  The ``rootrellink``
-    is a block that by default contains a list item pointing to the master
+    is a block that by default contains a list item pointing to the root
     document by default, the ``relbaritems`` is an empty block.  If you
     override them to add extra links into the bar make sure that they are list
     items and end with the :data:`reldelim1`.

doc/tutorial/index.rst

@@ -0,0 +1,452 @@
+.. _tutorial:
+
+===============
+Sphinx tutorial
+===============
+
+In this tutorial you will build a simple documentation project using Sphinx, and
+view it in your browser as HTML.  The project will include narrative,
+handwritten documentation, as well as autogenerated API documentation.
+
+The tutorial is aimed towards Sphinx newcomers willing to learn the fundamentals
+of how projects are created and structured.  You will create a fictional
+software library to generate random food recipes that will serve as a guide
+throughout the process, with the objective of properly documenting it.
+
+To showcase Sphinx capabilities for code documentation you will use Python,
+which also supports *automatic* documentation generation.
+
+.. note::
+
+   Several other languages are natively supported in Sphinx for *manual* code
+   documentation, however they require extensions for *automatic* code
+   documentation, like `Breathe <https://breathe.readthedocs.io/>`_.
+
+To follow the instructions you will need access to a Linux-like command line and
+a basic understanding of how it works, as well as a working Python installation
+for development, since you will use *Python virtual environments* to create the
+project.
+
+Getting started
+---------------
+
+Setting up your project and development environment
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+In a new directory, create a file called ``README.rst`` with the following
+content.
+
+.. code-block:: rst
+   :caption: README.rst
+
+   Lumache
+   =======
+
+   **Lumache** (/lu'make/) is a Python library for cooks and food lovers that
+   creates recipes mixing random ingredients.
+
+It is a good moment to create a Python virtual environment and install the
+required tools.  For that, open a command line terminal, ``cd`` into the
+directory you just created, and run the following commands:
+
+.. code-block:: console
+
+   $ python -m venv .venv
+   $ source .venv/bin/activate
+   (.venv) $ python -m pip install sphinx
+
+.. note::
+
+   The installation method used above is described in more detail in
+   :ref:`install-pypi`.  For the rest of this tutorial, the instructions will
+   assume a Python virtual environment.
+
+If you executed these instructions correctly, you should have the Sphinx command
+line tools available.  You can do a basic verification running this command:
+
+.. code-block:: console
+
+   (.venv) $ sphinx-build --version
+   sphinx-build 4.0.2
+
+If you see a similar output, you are on the right path!
+
+Creating the documentation layout
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Then from the command line, run the following command:
+
+.. code-block:: console
+
+   (.venv) $ sphinx-quickstart docs
+
+This will present to you a series of questions required to create the basic
+directory and configuration layout for your project inside the ``docs`` folder.
+To proceed, answer each question as follows:
+
+- ``> Separate source and build directories (y/n) [n]``: Write "``y``" (without
+  quotes) and press :kbd:`Enter`.
+- ``> Project name``: Write "``Lumache``" (without quotes) and press
+  :kbd:`Enter`.
+- ``> Author name(s)``: Write "``Graziella``" (without quotes) and press
+  :kbd:`Enter`.
+- ``> Project release []``: Write "``0.1``" (without quotes) and press
+  :kbd:`Enter`.
+- ``> Project language [en]``: Leave it empty (the default, English) and press
+  :kbd:`Enter`.
+
+After the last question, you will see the new ``docs`` directory with the
+following content.
+
+.. code-block:: text
+
+   docs
+   ├── build
+   ├── make.bat
+   ├── Makefile
+   └── source
+      ├── conf.py
+      ├── index.rst
+      ├── _static
+      └── _templates
+
+The purpose of each of these files is:
+
+``build/``
+  An empty directory (for now) that will hold the rendered documentation.
+
+``make.bat`` and ``Makefile``
+  Convenience scripts to simplify some common Sphinx operations, such as
+  rendering the content.
+
+``source/conf.py``
+  A Python script holding the configuration of the Sphinx project.  It contains
+  the project name and release you specified to ``sphinx-quickstart``, as well
+  as some extra configuration keys.
+
+``source/index.rst``
+  The :term:`root document` of the project, which serves as welcome page and
+  contains the root of the "table of contents tree" (or *toctree*).
+
+Thanks to this bootstrapping step, you already have everything needed to render
+the documentation as HTML for the first time.  To do that, run this command:
+
+.. code-block:: console
+
+   (.venv) $ sphinx-build -b html docs/source/ docs/build/html
+
+And finally, open ``docs/build/html/index.html`` in your browser.  You should see
+something like this:
+
+.. figure:: /_static/tutorial/lumache-first-light.png
+   :width: 80%
+   :align: center
+   :alt: Freshly created documentation of Lumache
+
+   Freshly created documentation of Lumache
+
+There we go! You created your first HTML documentation using Sphinx.
+
+First steps to document your project using Sphinx
+-------------------------------------------------
+
+Building your HTML documentation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The ``index.rst`` file that ``sphinx-quickstart`` created has some content
+already, and it gets rendered as the front page of your HTML documentation.  It
+is written in reStructuredText, a powerful markup language.
+
+Modify the file as follows:
+
+.. code-block:: rst
+   :caption: docs/source/index.rst
+
+   Welcome to Lumache's documentation!
+   ===================================
+
+   **Lumache** (/lu'make/) is a Python library for cooks and food lovers that
+   creates recipes mixing random ingredients.  It pulls data from the `Open Food
+   Facts database <https://world.openfoodfacts.org/>`_ and offers a *simple* and
+   *intuitive* API.
+
+   .. note::
+
+      This project is under active development.
+
+This showcases several features of the reStructuredText syntax, including:
+
+- a **section header** using ``===`` for the underline,
+- two examples of :ref:`rst-inline-markup`: ``**strong emphasis**`` (typically
+  bold) and ``*emphasis*`` (typically italics),
+- an **inline external link**,
+- and a ``note`` **admonition** (one of the available :ref:`directives
+  <rst-directives>`)
+
+Now to render it with the new content, you can use the ``sphinx-build`` command
+as before, or leverage the convenience script as follows:
+
+.. code-block:: console
+
+   (.venv) $ cd docs
+   (.venv) $ make html
+
+After running this command, you will see that ``index.html`` reflects the new
+changes!
+
+Building your documentation in other formats
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Sphinx supports a variety of formats apart from HTML, including PDF, EPUB,
+:ref:`and more <builders>`.  For example, to build your documentation
+in EPUB format, run this command from the ``docs`` directory:
+
+.. code-block:: console
+
+   (.venv) $ make epub
+
+After that, you will see the files corresponding to the e-book under
+``docs/build/epub/``.  You can either open ``Lumache.epub`` with an
+EPUB-compatible e-book viewer, like `Calibre <https://calibre-ebook.com/>`_,
+or preview ``index.xhtml`` on a web browser.
+
+.. note::
+
+   To quickly display a complete list of possible output formats, plus some
+   extra useful commands, you can run :code:`make help`.
+
+Each output format has some specific configuration options that you can tune,
+:ref:`including EPUB <epub-options>`.  For instance, the default value of
+:confval:`epub_show_urls` is ``inline``, which means that, by default, URLs are
+shown right after the corresponding link, in parentheses.  You can change that
+behavior by adding the following code at the end of your ``conf.py``:
+
+.. code-block:: python
+
+   # EPUB options
+   epub_show_urls = 'footnote'
+
+With this configuration value, and after running ``make epub`` again, you will
+notice that URLs appear now as footnotes, which avoids cluttering the text.
+Sweet!
+
+.. note::
+
+   Generating a PDF using Sphinx can be done running ``make latexpdf``,
+   provided that the system has a working :math:`\LaTeX` installation,
+   as explained in the documentation of :class:`sphinx.builders.latex.LaTeXBuilder`.
+   Although this is perfectly feasible, such installations are often big,
+   and in general LaTeX requires careful configuration in some cases,
+   so PDF generation is out of scope for this tutorial.
+
+More Sphinx customization
+-------------------------
+
+There are two main ways to customize your documentation beyond what is possible
+with core Sphinx: extensions and themes.
+
+Enabling a built-in extension
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+In addition to these configuration values, you can customize Sphinx even more
+by using :doc:`extensions </usage/extensions/index>`.  Sphinx ships several
+:ref:`builtin ones <builtin-extensions>`, and there are many more
+:ref:`maintained by the community <third-party-extensions>`.
+
+For example, to enable the :mod:`sphinx.ext.duration` extension,
+locate the ``extensions`` list in your ``conf.py`` and add one element as
+follows:
+
+.. code-block:: python
+   :caption: docs/source/conf.py
+
+   # Add any Sphinx extension module names here, as strings. They can be
+   # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+   # ones.
+   extensions = [
+       'sphinx.ext.duration',
+   ]
+
+After that, every time you generate your documentation, you will see a short
+durations report at the end of the console output, like this one:
+
+.. code-block:: console
+
+   (.venv) $ make html
+   ...
+   The HTML pages are in build/html.
+
+   ====================== slowest reading durations =======================
+   0.042 temp/source/index
+
+Using a third-party HTML theme
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Themes, on the other hand, are a way to customize the appearance of your
+documentation.  Sphinx has several :ref:`builtin themes <builtin-themes>`, and
+there are also `third-party ones <https://sphinx-themes.org/>`_.
+
+For example, to use the `Furo <https://pradyunsg.me/furo/>`_ third-party theme
+in your HTML documentation, first you will need to install it with ``pip`` in
+your Python virtual environment, like this:
+
+.. code-block:: console
+
+   (.venv) $ pip install furo
+
+And then, locate the ``html_theme`` variable on your ``conf.py`` and replace
+its value as follows:
+
+.. code-block:: python
+   :caption: docs/source/conf.py
+
+   # The theme to use for HTML and HTML Help pages.  See the documentation for
+   # a list of builtin themes.
+   #
+   html_theme = 'furo'
+
+With this change, you will notice that your HTML documentation has now a new
+appearance:
+
+.. figure:: /_static/tutorial/lumache-furo.png
+   :width: 80%
+   :align: center
+   :alt: HTML documentation of Lumache with the Furo theme
+
+   HTML documentation of Lumache with the Furo theme
+
+Narrative documentation in Sphinx
+---------------------------------
+
+Structuring your documentation across multiple pages
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The file ``index.rst`` created by ``sphinx-quickstart`` is the :term:`root
+document`, whose main function is to serve as a welcome page and to contain the
+root of the "table of contents tree" (or *toctree*).  Sphinx allows you to
+assemble a project from different files, which is helpful when the project
+grows.
+
+As an example, create a new file ``docs/source/usage.rst`` (next to
+``index.rst``) with these contents:
+
+.. code-block:: rst
+   :caption: docs/source/usage.rst
+
+   Usage
+   =====
+
+   Installation
+   ------------
+
+   To use Lumache, first install it using pip:
+
+   .. code-block:: console
+
+      (.venv) $ pip install lumache
+
+This new file contains two :ref:`section <rst-sections>` headers, normal
+paragraph text, and a :rst:dir:`code-block` directive that renders
+a block of content as source code, with appropriate syntax highlighting
+(in this case, generic ``console`` text).
+
+The structure of the document is determined by the succession of heading
+styles, which means that, by using ``---`` for the "Installation" section
+after ``===`` for the "Usage" section, you have declared "Installation" to
+be a *subsection* of "Usage".
+
+To complete the process, add a ``toctree`` :ref:`directive <rst-directives>` at
+the end of ``index.rst`` including the document you just created, as follows:
+
+.. code-block:: rst
+   :caption: docs/source/index.rst
+
+   Contents
+   --------
+
+   .. toctree::
+
+      usage
+
+This step inserts that document in the root of the *toctree*, so now it belongs
+to the structure of your project, which so far looks like this:
+
+.. code-block:: text
+
+   index
+   └── usage
+
+If you build the HTML documentation running ``make html``, you will see
+that the ``toctree`` gets rendered as a list of hyperlinks, and this allows you
+to navigate to the new page you just created.  Neat!
+
+.. warning::
+
+   Documents outside a *toctree* will result in ``WARNING: document isn't
+   included in any toctree`` messages during the build process, and will be
+   unreachable for users.
+
+Adding cross-references
+~~~~~~~~~~~~~~~~~~~~~~~
+
+One powerful feature of Sphinx is the ability to seamlessly add
+:ref:`cross-references <xref-syntax>` to specific parts of the documentation:
+a document, a section, a figure, a code object, etc.  This tutorial is full of
+them!
+
+To add a cross-reference, write this sentence right after the
+introduction paragraph in ``index.rst``:
+
+.. code-block:: rst
+   :caption: docs/source/index.rst
+
+   Check out the :doc:`usage` section for further information.
+
+The :rst:role:`doc` role you used automatically references a specific document
+in the project, in this case the ``usage.rst`` you created earlier.
+
+Alternatively, you can also add a cross-reference to an arbitrary part of the
+project. For that, you need to use the :rst:role:`ref` role, and add an
+explicit *label* that acts as `a target`__.
+
+__ https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#hyperlink-targets
+
+For example, to reference the "Installation" subsection, add a label right
+before the heading, as follows:
+
+.. code-block:: rst
+   :caption: docs/source/usage.rst
+   :emphasize-lines: 4
+
+   Usage
+   =====
+
+   .. _installation:
+
+   Installation
+   ------------
+
+   ...
+
+And make the sentence you added in ``index.rst`` look like this:
+
+.. code-block:: rst
+   :caption: docs/source/index.rst
+
+   Check out the :doc:`usage` section for further information, including how to
+   :ref:`install <installation>` the project.
+
+Notice a trick here: the ``install`` part specifies how the link will look like
+(we want it to be a specific word, so the sentence makes sense), whereas the
+``<installation>`` part refers to the actual label we want to add a
+cross-reference to. If you do not include an explicit title, hence using
+``:ref:`installation```, the section title will be used (in this case,
+``Installation``). Both the ``:doc:`` and the ``:ref:`` roles will be rendered
+as hyperlinks in the HTML documentation.
+
+Where to go from here
+---------------------
+
+This tutorial covered the very first steps to create a documentation project
+with Sphinx.  To continue learning more about Sphinx, check out the :ref:`rest
+of the documentation <contents>`.

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``:

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():

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
 

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

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
 ----------------------
 

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

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
 

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])
 

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
 --------
 

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.

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.
 

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**