Merge branch '4.x' into HEAD

doc/usage/advanced/setuptools.rst

@@ -64,7 +64,7 @@ Options for setuptools integration
 
    This can also be set by passing the `-E` flag to ``setup.py``:
 
-   .. code-block:: bash
+   .. code-block:: console
 
       $ python setup.py build_sphinx -E
 
@@ -75,7 +75,7 @@ Options for setuptools integration
 
    This can also be set by passing the `-a` flag to ``setup.py``:
 
-   .. code-block:: bash
+   .. code-block:: console
 
       $ python setup.py build_sphinx -a
 
@@ -88,7 +88,7 @@ Options for setuptools integration
 
    This can also be set by passing the `-s` flag to ``setup.py``:
 
-   .. code-block:: bash
+   .. code-block:: console
 
       $ python setup.py build_sphinx -s $SOURCE_DIR
 
@@ -105,7 +105,7 @@ Options for setuptools integration
 
    This can also be set by passing the `-c` flag to ``setup.py``:
 
-   .. code-block:: bash
+   .. code-block:: console
 
       $ python setup.py build_sphinx -c $CONFIG_DIR
 
@@ -117,7 +117,7 @@ Options for setuptools integration
 
    This can also be set by passing the `-b` flag to ``setup.py``:
 
-   .. code-block:: bash
+   .. code-block:: console
 
       $ python setup.py build_sphinx -b $BUILDER
 
@@ -131,7 +131,7 @@ Options for setuptools integration
 
    This can also be set by passing the `-W` flag to ``setup.py``:
 
-   .. code-block:: bash
+   .. code-block:: console
 
       $ python setup.py build_sphinx -W
 
@@ -169,7 +169,7 @@ Options for setuptools integration
 
    This can also be set by passing the `-i` flag to ``setup.py``:
 
-   .. code-block:: bash
+   .. code-block:: console
 
       $ python setup.py build_sphinx -i
 

doc/usage/configuration.rst

@@ -22,9 +22,9 @@ and output behavior.
   .. _`docutils.conf`: https://docutils.sourceforge.io/docs/user/config.html
 
 The configuration file is executed as Python code at build time (using
-:func:`execfile`, and with the current directory set to its containing
-directory), and therefore can execute arbitrarily complex code.  Sphinx then
-reads simple names from the file's namespace as its configuration.
+:func:`importlib.import_module`, and with the current directory set to its
+containing directory), and therefore can execute arbitrarily complex code.
+Sphinx then reads simple names from the file's namespace as its configuration.
 
 Important points to note:
 
@@ -329,6 +329,8 @@ General configuration
    * ``ref.python``
    * ``misc.highlighting_failure``
    * ``toc.circular``
+   * ``toc.excluded``
+   * ``toc.not_readable``
    * ``toc.secnum``
    * ``epub.unknown_project_files``
    * ``epub.duplicated_toc_entry``
@@ -360,6 +362,10 @@ General configuration
 
       Added ``epub.duplicated_toc_entry``
 
+   .. versionchanged:: 4.3
+
+      Added ``toc.excluded`` and ``toc.not_readable``
+
 .. confval:: needs_sphinx
 
    If set to a ``major.minor`` version string like ``'1.1'``, Sphinx will
@@ -802,6 +808,13 @@ documentation on :ref:`intl` for details.
    .. versionchanged:: 1.5
       Use ``locales`` directory as a default value
 
+.. confval:: gettext_allow_fuzzy_translations
+
+   If true, "fuzzy" messages in the message catalogs are used for translation.
+   The default is ``False``.
+
+   .. versionadded:: 4.3
+
 .. confval:: gettext_compact
 
    .. versionadded:: 1.1
@@ -992,7 +1005,7 @@ that use Sphinx's HTMLWriter class.
    to indicate the location of document using `The Canonical Link Relation`_.
    Default: ``''``.
 
-   .. _The Canonical Link Relation: https://tools.ietf.org/html/rfc6596
+   .. _The Canonical Link Relation: https://datatracker.ietf.org/doc/html/rfc6596
 
    .. versionadded:: 1.8
 
@@ -2486,6 +2499,13 @@ These options influence Texinfo output.
 
    .. versionadded:: 1.1
 
+.. confval:: texinfo_cross_references
+
+  If false, do not generate inline references in a document.  That makes
+  an info file more readable with stand-alone reader (``info``).
+  Default is ``True``.
+
+  .. versionadded:: 4.4
 
 .. _qthelp-options:
 
@@ -2637,10 +2657,8 @@ Options for the linkcheck builder
      A regular expression that matches a URI.
    *auth_info*
      Authentication information to use for that URI. The value can be anything
-     that is understood by the ``requests`` library (see `requests
-     Authentication <requests-auth>`_ for details).
-
-     .. _requests-auth: https://requests.readthedocs.io/en/master/user/authentication/
+     that is understood by the ``requests`` library (see :ref:`requests
+     Authentication <requests:authentication>` for details).
 
    The ``linkcheck`` builder will use the first matching ``auth_info`` value
    it can find in the :confval:`linkcheck_auth` list, so values earlier in the
@@ -2668,10 +2686,23 @@ Options for the linkcheck builder
    doubling the wait time between attempts until it succeeds or exceeds the
    ``linkcheck_rate_limit_timeout``. By default, the timeout is 5 minutes.
 
-   .. _Retry-After: https://tools.ietf.org/html/rfc7231#section-7.1.3
+   .. _Retry-After: https://datatracker.ietf.org/doc/html/rfc7231#section-7.1.3
 
    .. versionadded:: 3.4
 
+.. confval:: linkcheck_exclude_documents
+
+   A list of regular expressions that match documents in which Sphinx should
+   not check the validity of links. This can be used for permitting link decay
+   in legacy or historical sections of the documentation.
+
+   Example::
+
+      # ignore all links in documents located in a subfolder named 'legacy'
+      linkcheck_exclude_documents = [r'.*/legacy/.*']
+
+   .. versionadded:: 4.4
+
 
 Options for the XML builder
 ---------------------------

doc/usage/extensions/autodoc.rst

@@ -662,6 +662,18 @@ There are also config values that you can set:
    .. __: https://mypy.readthedocs.io/en/latest/kinds_of_types.html#type-aliases
    .. versionadded:: 3.3
 
+.. confval:: autodoc_typehints_format
+
+   This value controls the format of typehints.  The setting takes the
+   following values:
+
+   * ``'fully-qualified'`` -- Show the module name and its name of typehints
+     (default)
+   * ``'short'`` -- Suppress the leading module names of the typehints
+     (ex. ``io.StringIO`` -> ``StringIO``)
+
+   .. versionadded:: 4.4
+
 .. confval:: autodoc_preserve_defaults
 
    If True, the default argument values of functions will be not evaluated on
@@ -768,8 +780,6 @@ needed docstring processing in event :event:`autodoc-process-docstring`:
 
 .. event:: autodoc-process-bases (app, name, obj, options, bases)
 
-   .. versionadded:: 4.1
-
    Emitted when autodoc has read and processed a class to determine the
    base-classes.  *bases* is a list of classes that the event handler can
    modify **in place** to change what Sphinx puts into the output.  It's
@@ -781,6 +791,12 @@ needed docstring processing in event :event:`autodoc-process-docstring`:
    :param options: the options given to the class directive
    :param bases: the list of base classes signature. see above.
 
+   .. versionadded:: 4.1
+   .. versionchanged:: 4.3
+
+      ``bases`` can contain a string as a base class name.  It will be processed
+      as reST mark-up'ed text.
+
 
 Skipping members
 ----------------

doc/usage/extensions/autosummary.rst

@@ -201,6 +201,25 @@ also use these config values:
 
    .. versionadded:: 2.1
 
+   .. versionchanged:: 4.4
+
+      If ``autosummary_ignore_module_all`` is ``False``, this configuration
+      value is ignored for members listed in ``__all__``.
+
+.. confval:: autosummary_ignore_module_all
+
+   If ``False`` and a module has the ``__all__`` attribute set, autosummary
+   documents every member listed in ``__all__`` and no others. Default is
+   ``True``
+
+   Note that if an imported member is listed in ``__all__``, it will be
+   documented regardless of the value of ``autosummary_imported_members``. To
+   match the behaviour of ``from module import *``, set
+   ``autosummary_ignore_module_all`` to False and
+   ``autosummary_imported_members`` to True.
+
+   .. versionadded:: 4.4
+
 .. confval:: autosummary_filename_map
 
    A dict mapping object names to filenames. This is necessary to avoid
@@ -210,6 +229,7 @@ also use these config values:
 
    .. versionadded:: 3.2
 
+.. _autosummary-customizing-templates:
 
 Customizing templates
 ---------------------

doc/usage/extensions/intersphinx.rst

@@ -148,6 +148,35 @@ linking:
       exception is raised if the server has not issued a response for timeout
       seconds.
 
+.. confval:: intersphinx_disabled_reftypes
+
+   .. versionadded:: 4.3
+
+   A list of strings being either:
+
+   - the name of a specific reference type in a domain,
+     e.g., ``std:doc``, ``py:func``, or ``cpp:class``,
+   - the name of a domain, and a wildcard, e.g.,
+     ``std:*``, ``py:*``, or ``cpp:*``, or
+   - simply a wildcard ``*``.
+
+   The default value is an empty list.
+
+   When a cross-reference without an explicit inventory specification is being
+   resolved by intersphinx, skip resolution if it matches one of the
+   specifications in this list.
+
+   For example, with ``intersphinx_disabled_reftypes = ['std:doc']``
+   a cross-reference ``:doc:`installation``` will not be attempted to be
+   resolved by intersphinx, but ``:doc:`otherbook:installation``` will be
+   attempted to be resolved in the inventory named ``otherbook`` in
+   :confval:`intersphinx_mapping`.
+   At the same time, all cross-references generated in, e.g., Python,
+   declarations will still be attempted to be resolved by intersphinx.
+
+   If ``*`` is in the list of domains, then no references without an explicit
+   inventory will be resolved by intersphinx.
+
 
 Showing all links of an Intersphinx mapping file
 ------------------------------------------------
@@ -158,7 +187,7 @@ searching for the root cause of a broken Intersphinx link in a documentation
 project. The following example prints the Intersphinx mapping of the Python 3
 documentation::
 
-   $ python -msphinx.ext.intersphinx https://docs.python.org/3/objects.inv
+   $ python -m sphinx.ext.intersphinx https://docs.python.org/3/objects.inv
 
 Using Intersphinx with inventory file under Basic Authorization
 ---------------------------------------------------------------

doc/usage/extensions/math.rst

@@ -200,6 +200,11 @@ Sphinx but is set to automatically include it from a third-party site.
 
    .. versionadded:: 1.8
 
+   .. versionchanged:: 4.4.1
+
+      Allow to change the loading method (async or defer) of MathJax if "async"
+      or "defer" key is set.
+
 .. confval:: mathjax3_config
 
    The configuration options for MathJax v3 (which is used by default).

doc/usage/installation.rst

@@ -120,7 +120,7 @@ Chocolatey
    $ choco install sphinx
    
 You would need to `install Chocolatey
-<https://chocolatey.org/install/>`_
+<https://chocolatey.org/install>`_
 before running this.
 
 For more information, refer to the `chocolatey page`__.
@@ -239,13 +239,13 @@ PDF builds using LaTeX.  Please choose one for your purpose.
    commands.  For example, you can use following command to create a Sphinx
    project:
 
-   .. code-block:: bash
+   .. code-block:: console
 
       $ docker run -it --rm -v /path/to/document:/docs sphinxdoc/sphinx sphinx-quickstart
 
    And you can following command this to build HTML document:
 
-   .. code-block:: bash
+   .. code-block:: console
 
       $ docker run --rm -v /path/to/document:/docs sphinxdoc/sphinx make html
 

doc/usage/quickstart.rst

@@ -39,7 +39,7 @@ Sphinx comes with a script called :program:`sphinx-quickstart` that sets up a
 source directory and creates a default :file:`conf.py` with the most useful
 configuration values from a few questions it asks you. To use this, run:
 
-.. code-block:: shell
+.. code-block:: console
 
    $ sphinx-quickstart
 
@@ -128,7 +128,7 @@ Running the build
 Now that you have added some files and content, let's make a first build of the
 docs.  A build is started with the :program:`sphinx-build` program:
 
-.. code-block:: shell
+.. code-block:: console
 
    $ sphinx-build -b html sourcedir builddir
 
@@ -144,7 +144,7 @@ However, :program:`sphinx-quickstart` script creates a :file:`Makefile` and a
 :file:`make.bat` which make life even easier for you. These can be executed by
 running :command:`make` with the name of the builder. For example.
 
-.. code-block:: shell
+.. code-block:: console
 
    $ make html
 

doc/usage/restructuredtext/basics.rst

@@ -410,7 +410,27 @@ following the arguments and indicated by the colons).  Options must be indented
 to the same level as the directive content.
 
 The directive content follows after a blank line and is indented relative to
-the directive start.
+the directive start or if options are present, by the same amount as the
+options.
+
+Be careful as the indent is not a fixed number of whitespace, e.g. three, but
+any number whitespace.  This can be surprising when a fixed indent is used
+throughout the document and can make a difference for directives which are
+sensitive to whitespace. Compare::
+
+   .. code-block::
+      :caption: A cool example
+
+          The output of this line starts with four spaces.
+
+   .. code-block::
+
+          The output of this line has no spaces at the beginning.
+
+In the first code block, the indent for the content was fixated by the option
+line to three spaces, consequently the content starts with four spaces.
+In the latter the indent was fixed by the content itself to seven spaces, thus
+it does not start with a space.
 
 
 Images

doc/usage/restructuredtext/directives.rst

@@ -832,6 +832,9 @@ Glossary
    .. versionchanged:: 1.4
       Index key for glossary term should be considered *experimental*.
 
+   .. versionchanged:: 4.4
+      In internationalized documentation, the ``:sorted:`` flag sorts
+      according to translated terms.
 
 Meta-information markup
 -----------------------

doc/usage/restructuredtext/domains.rst

@@ -125,6 +125,7 @@ In short:
   component of the target.  For example, ``:py:meth:`~Queue.Queue.get``` will
   refer to ``Queue.Queue.get`` but only display ``get`` as the link text.
 
+.. _python-domain:
 
 The Python Domain
 -----------------
@@ -677,12 +678,55 @@ The C domain (name **c**) is suited for documentation of C API.
    Note that you don't have to backslash-escape asterisks in the signature, as
    it is not parsed by the reST inliner.
 
+   In the description of a function you can use the following info fields
+   (see also :ref:`info-field-lists`).
+
+   * ``param``, ``parameter``, ``arg``, ``argument``,
+     Description of a parameter.
+   * ``type``: Type of a parameter,
+     written as if passed to the :rst:role:`c:expr` role.
+   * ``returns``, ``return``: Description of the return value.
+   * ``rtype``: Return type,
+     written as if passed to the :rst:role:`c:expr` role.
+   * ``retval``, ``retvals``: An alternative to ``returns`` for describing
+     the result of the function.
+
+   .. versionadded:: 4.3
+      The ``retval`` field type.
+
+   For example::
+
+      .. c:function:: PyObject *PyType_GenericAlloc(PyTypeObject *type, Py_ssize_t nitems)
+
+         :param type: description of the first parameter.
+         :param nitems: description of the second parameter.
+         :returns: a result.
+         :retval NULL: under some conditions.
+         :retval NULL: under some other conditions as well.
+
+   which renders as
+
+   .. c:function:: PyObject *PyType_GenericAlloc(PyTypeObject *type, Py_ssize_t nitems)
+
+      ..
+         ** for some editors (e.g., vim) to stop bold-highlighting the source
+
+      :param type: description of the first parameter.
+      :param nitems: description of the second parameter.
+      :returns: a result.
+      :retval NULL: under some conditions.
+      :retval NULL: under some other conditions as well.
+
+
 .. rst:directive:: .. c:macro:: name
                    .. c:macro:: name(arg list)
 
    Describes a C macro, i.e., a C-language ``#define``, without the replacement
    text.
 
+   In the description of a macro you can use the same info fields as for the
+   :rst:dir:`c:function` directive.
+
    .. versionadded:: 3.0
       The function style variant.
 
@@ -1453,14 +1497,23 @@ The ``cpp:namespace-pop`` directive undoes the most recent
 Info field lists
 ~~~~~~~~~~~~~~~~~
 
-The C++ directives support the following info fields (see also
-:ref:`info-field-lists`):
+All the C++ directives for declaring entities support the following
+info fields (see also :ref:`info-field-lists`):
 
-* `param`, `parameter`, `arg`, `argument`: Description of a parameter.
-* `tparam`: Description of a template parameter.
-* `returns`, `return`: Description of a return value.
+* ``tparam``: Description of a template parameter.
+
+The :rst:dir:`cpp:function` directive additionally supports the
+following fields:
+
+* ``param``, ``parameter``, ``arg``, ``argument``: Description of a parameter.
+* ``returns``, ``return``: Description of a return value.
+* ``retval``, ``retvals``: An alternative to ``returns`` for describing
+  the result of the function.
 * `throws`, `throw`, `exception`: Description of a possibly thrown exception.
 
+.. versionadded:: 4.3
+   The ``retval`` field type.
+
 .. _cpp-roles:
 
 Cross-referencing

doc/usage/theming.rst

@@ -70,7 +70,7 @@ directory containing :file:`conf.py` and use this configuration::
 The third form is a Python package.  If a theme you want to use is distributed
 as a Python package, you can use it after installing
 
-.. code-block:: bash
+.. code-block:: console
 
     # installing theme package
     $ pip install sphinxjp.themes.dotted
@@ -127,6 +127,10 @@ Builtin themes
 
 Sphinx comes with a selection of themes to choose from.
 
+Note that from these themes only the Alabaster and Scrolls themes are
+mobile-optimated, the other themes resort to horizontal scrolling
+if the screen is too narrow.
+
 .. cssclass:: clear
 
 These themes are: