Merging upstream version 7.4.7.

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

10 files changed, 144 insertions, 36 deletions

diff --git a/doc/usage/extensions/autodoc.rst b/doc/usage/extensions/autodoc.rst
index c920de8..a2a093f 100644
--- a/doc/usage/extensions/autodoc.rst
+++ b/doc/usage/extensions/autodoc.rst
@@ -1,4 +1,6 @@
-.. highlight:: rest
+.. highlight:: rst
+
+.. _ext-autodoc:
 
 :mod:`sphinx.ext.autodoc` -- Include documentation from docstrings
 ==================================================================
@@ -12,13 +14,6 @@
 This extension can import the modules you are documenting, and pull in
 documentation from docstrings in a semi-automatic way.
 
-.. note::
-
-   For Sphinx (actually, the Python interpreter that executes Sphinx) to find
-   your module, it must be importable.  That means that the module or the
-   package must be in one of the directories on :data:`sys.path` -- adapt your
-   :data:`sys.path` in the configuration file accordingly.
-
 .. warning::
 
    :mod:`~sphinx.ext.autodoc` **imports** the modules to be documented.  If any
@@ -43,6 +38,68 @@ docstrings to correct reStructuredText before :mod:`autodoc` processes them.
 .. _Google: https://google.github.io/styleguide/pyguide.html#38-comments-and-docstrings
 .. _NumPy: https://numpydoc.readthedocs.io/en/latest/format.html#docstring-standard
 
+Getting started
+---------------
+
+Setup
+.....
+Activate the plugin by adding ``'sphinx.ext.autodoc'`` to the :confval:`extensions`
+in your :file:`conf.py`::
+
+   extensions = [
+       ...
+       'sphinx.ext.autodoc',
+   ]
+
+Ensuring the code can be imported
+.................................
+
+:mod:`~sphinx.ext.autodoc` analyses the code and docstrings by introspection after
+importing the modules. For importing to work, you have to make sure that your
+modules can be found by Sphinx and that dependencies can be resolved (if your
+module does ``import foo``, but ``foo`` is not available in the python environment
+that Sphinx runs in, your module import will fail).
+
+There are two ways to ensure this:
+
+1. Use an environment that contains your package and Sphinx. This can e.g. be your
+   local dev environment (with an editable install), or an environment in CI in
+   which you install Sphinx and your package. The regular installation process
+   ensures that your package can be found by Sphinx and that all dependencies are
+   available.
+
+2. It is alternatively possible to patch the Sphinx run so that it can operate
+   directly on the sources; e.g. if you want to be able to do a Sphinx build from a
+   source checkout.
+
+   - Patch :data:`sys.path` in your Sphinx :file:`conf.py` to include the folder of
+     your sources. E.g. if you have a repository structure with :file:`doc/conf.py`
+     and your package is at :file:`src/mypackage`, then you should add::
+
+        sys.path.insert(0, os.path.abspath('../src'))
+
+     to your :file:`conf.py`.
+
+   - To cope with missing dependencies, specify the missing modules in
+     :confval:`autodoc_mock_imports`.
+
+Usage
+.....
+
+You can now use the :ref:`autodoc-directives` to add formatted documentation for
+Python code elements like functions, classes, modules, etc. For example, to document
+the function ``io.open()``, reading its signature and docstring from the source file,
+you'd write ::
+
+   .. autofunction:: io.open
+
+You can also document whole classes or even modules automatically, using member
+options for the auto directives, like ::
+
+   .. automodule:: io
+      :members:
+
+.. _autodoc-directives:
 
 Directives
 ----------
@@ -271,7 +328,7 @@ inserting them into the page source under a suitable :rst:dir:`py:module`,
      once by specifying the option to :rst:dir:`automodule` directive.
 
      Note: this will lead to markup errors if the inherited members come from a
-     module whose docstrings are not reST formatted.
+     module whose docstrings are not reStructuredText formatted.
 
      .. versionadded:: 0.3
 
@@ -688,7 +745,7 @@ There are also config values that you can set:
 
    * ``'fully-qualified'`` -- Show the module name and its name of typehints
    * ``'short'`` -- Suppress the leading module names of the typehints
-     (ex. ``io.StringIO`` -> ``StringIO``)  (default)
+     (e.g. ``io.StringIO`` -> ``StringIO``)  (default)
 
    .. versionadded:: 4.4
 
@@ -816,8 +873,8 @@ needed docstring processing in event :event:`autodoc-process-docstring`:
    .. 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.
+      ``bases`` can contain a string as a base class name.
+      It will be processed as reStructuredText.
 
 
 Skipping members
diff --git a/doc/usage/extensions/autosectionlabel.rst b/doc/usage/extensions/autosectionlabel.rst
index b5b9b51..29b1c2a 100644
--- a/doc/usage/extensions/autosectionlabel.rst
+++ b/doc/usage/extensions/autosectionlabel.rst
@@ -1,4 +1,4 @@
-.. highlight:: rest
+.. highlight:: rst
 
 :mod:`sphinx.ext.autosectionlabel` -- Allow reference sections using its title
 ==============================================================================
@@ -51,6 +51,6 @@ Debugging
 ---------
 
 The ``WARNING: undefined label`` indicates that your reference in
-:rst:role:`ref` is mis-spelled. Invoking :program:`sphinx-build` with ``-vv``
+:rst:role:`ref` is mis-spelled. Invoking :program:`sphinx-build` with ``-vvv``
 (see :option:`-v`) will print all section names and the labels that have been
 generated for them. This output can help finding the right reference label.
diff --git a/doc/usage/extensions/autosummary.rst b/doc/usage/extensions/autosummary.rst
index a18460b..0a25d8d 100644
--- a/doc/usage/extensions/autosummary.rst
+++ b/doc/usage/extensions/autosummary.rst
@@ -1,4 +1,4 @@
-.. highlight:: rest
+.. highlight:: rst
 
 :mod:`sphinx.ext.autosummary` -- Generate autodoc summaries
 ===========================================================
diff --git a/doc/usage/extensions/coverage.rst b/doc/usage/extensions/coverage.rst
index b9c493b..75ffc0f 100644
--- a/doc/usage/extensions/coverage.rst
+++ b/doc/usage/extensions/coverage.rst
@@ -6,15 +6,64 @@
 
 This extension features one additional builder, the :class:`CoverageBuilder`.
 
-.. class:: CoverageBuilder
+.. todo:: Write this section.
 
-   To use this builder, activate the coverage extension in your configuration
-   file and give ``-M coverage`` on the command line.
+.. note::
 
-.. todo:: Write this section.
+   The :doc:`sphinx-apidoc </man/sphinx-apidoc>` command can be used to
+   automatically generate API documentation for all code in a project,
+   avoiding the need to manually author these documents and keep them up-to-date.
+
+.. warning::
+
+   :mod:`~sphinx.ext.coverage` **imports** the modules to be documented.
+   If any modules have side effects on import,
+   these will be executed by the coverage builder when ``sphinx-build`` is run.
+
+   If you document scripts (as opposed to library modules),
+   make sure their main routine is protected by a
+   ``if __name__ == '__main__'`` condition.
+
+.. note::
+
+   For Sphinx (actually, the Python interpreter that executes Sphinx)
+   to find your module, it must be importable.
+   That means that the module or the package must be in
+   one of the directories on :data:`sys.path` -- adapt your :data:`sys.path`
+   in the configuration file accordingly.
+
+To use this builder, activate the coverage extension in your configuration file
+and run ``sphinx-build -M coverage`` on the command line.
+
+
+Builder
+-------
+
+.. py:class:: CoverageBuilder
+
+
+Configuration
+-------------
+
+Several configuration values can be used to specify
+what the builder should check:
+
+.. confval:: coverage_modules
+   :type: ``list[str]``
+   :default: ``[]``
+
+   List of Python packages or modules to test coverage for.
+   When this is provided, Sphinx will introspect each package
+   or module provided in this list as well
+   as all sub-packages and sub-modules found in each.
+   When this is not provided, Sphinx will only provide coverage
+   for Python packages and modules that it is aware of:
+   that is, any modules documented using the :rst:dir:`py:module` directive
+   provided in the :doc:`Python domain </usage/domains/python>`
+   or the :rst:dir:`automodule` directive provided by the
+   :mod:`~sphinx.ext.autodoc` extension.
 
-Several configuration values can be used to specify what the builder
-should check:
+   .. versionadded:: 7.4
 
 .. confval:: coverage_ignore_modules
 
diff --git a/doc/usage/extensions/doctest.rst b/doc/usage/extensions/doctest.rst
index 1848e1f..a5fc2c7 100644
--- a/doc/usage/extensions/doctest.rst
+++ b/doc/usage/extensions/doctest.rst
@@ -1,4 +1,4 @@
-.. highlight:: rest
+.. highlight:: rst
 
 :mod:`sphinx.ext.doctest` -- Test snippets in the documentation
 ===============================================================
@@ -344,12 +344,12 @@ The doctest extension uses the following configuration values:
 
 .. confval:: doctest_test_doctest_blocks
 
-   If this is a nonempty string (the default is ``'default'``), standard reST
-   doctest blocks will be tested too.  They will be assigned to the group name
-   given.
+   If this is a nonempty string (the default is ``'default'``),
+   standard reStructuredText doctest blocks will be tested too.
+   They will be assigned to the group name given.
 
-   reST doctest blocks are simply doctests put into a paragraph of their own,
-   like so::
+   reStructuredText doctest blocks are simply doctests
+   put into a paragraph of their own, like so::
 
       Some documentation text.
 
@@ -378,8 +378,8 @@ The doctest extension uses the following configuration values:
    with the :mod:`~sphinx.ext.autodoc` extension without marking them up with a
    special directive.
 
-   Note though that you can't have blank lines in reST doctest blocks.  They
-   will be interpreted as one block ending and another one starting.  Also,
-   removal of ``<BLANKLINE>`` and ``# doctest:`` options only works in
+   Note though that you can't have blank lines in reStructuredText doctest blocks.
+   They will be interpreted as one block ending and another one starting.
+   Also, removal of ``<BLANKLINE>`` and ``# doctest:`` options only works in
    :rst:dir:`doctest` blocks, though you may set :confval:`trim_doctest_flags`
    to achieve that in all code blocks with Python console content.
diff --git a/doc/usage/extensions/graphviz.rst b/doc/usage/extensions/graphviz.rst
index 231bd36..0cd7cac 100644
--- a/doc/usage/extensions/graphviz.rst
+++ b/doc/usage/extensions/graphviz.rst
@@ -1,4 +1,4 @@
-.. highlight:: rest
+.. highlight:: rst
 
 :mod:`sphinx.ext.graphviz` -- Add Graphviz graphs
 =================================================
@@ -66,7 +66,7 @@ It adds these directives:
    .. rst:directive:option:: layout: layout type of the graph
       :type: text
 
-      The layout of the graph (ex. ``dot``, ``neato`` and so on).  A path to the
+      The layout of the graph (e.g. ``dot``, ``neato`` and so on).  A path to the
       graphviz commands are also allowed.  By default, :confval:`graphviz_dot`
       is used.
 
diff --git a/doc/usage/extensions/ifconfig.rst b/doc/usage/extensions/ifconfig.rst
index 837c0b3..17cdbc0 100644
--- a/doc/usage/extensions/ifconfig.rst
+++ b/doc/usage/extensions/ifconfig.rst
@@ -1,4 +1,4 @@
-.. highlight:: rest
+.. highlight:: rst
 
 :mod:`sphinx.ext.ifconfig` -- Include content based on configuration
 ====================================================================
diff --git a/doc/usage/extensions/inheritance.rst b/doc/usage/extensions/inheritance.rst
index 33284b5..90bbcc3 100644
--- a/doc/usage/extensions/inheritance.rst
+++ b/doc/usage/extensions/inheritance.rst
@@ -1,4 +1,4 @@
-.. highlight:: rest
+.. highlight:: rst
 
 :mod:`sphinx.ext.inheritance_diagram` -- Include inheritance diagrams
 =====================================================================
diff --git a/doc/usage/extensions/intersphinx.rst b/doc/usage/extensions/intersphinx.rst
index e81719f..f64b596 100644
--- a/doc/usage/extensions/intersphinx.rst
+++ b/doc/usage/extensions/intersphinx.rst
@@ -1,3 +1,5 @@
+.. _ext-intersphinx:
+
 :mod:`sphinx.ext.intersphinx` -- Link to other projects' documentation
 ======================================================================
 
@@ -143,7 +145,7 @@ linking:
 
    Example:
 
-   .. code:: python
+   .. code-block:: python
 
       intersphinx_mapping = {'https://docs.python.org/': None}
 
diff --git a/doc/usage/extensions/math.rst b/doc/usage/extensions/math.rst
index 251d721..7d48d3a 100644
--- a/doc/usage/extensions/math.rst
+++ b/doc/usage/extensions/math.rst
@@ -1,4 +1,4 @@
-.. highlight:: rest
+.. highlight:: rst
 
 .. _math-support: