Merge branch '4.x' into texinfo-add-texinfo_emit_document_references

10 files changed, 381 insertions, 15 deletions

diff --git a/doc/conf.py b/doc/conf.py
index 220774b7f..893761cde 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -109,6 +109,7 @@ texinfo_documents = [
 intersphinx_mapping = {
     'python': ('https://docs.python.org/3/', None),
     'requests': ('https://requests.readthedocs.io/en/master', None),
+    'readthedocs': ('https://docs.readthedocs.io/en/stable', None),
 }
 
 # Sphinx document translation with sphinx gettext feature uses these settings:
diff --git a/doc/development/tutorials/examples/autodoc_intenum.py b/doc/development/tutorials/examples/autodoc_intenum.py
index 7fb85d066..a23f9cebf 100644
--- a/doc/development/tutorials/examples/autodoc_intenum.py
+++ b/doc/development/tutorials/examples/autodoc_intenum.py
@@ -9,7 +9,7 @@ from sphinx.ext.autodoc import ClassDocumenter, bool_option
 
 class IntEnumDocumenter(ClassDocumenter):
     objtype = 'intenum'
-    directivetype = 'class'
+    directivetype = ClassDocumenter.objtype
     priority = 10 + ClassDocumenter.priority
     option_spec = dict(ClassDocumenter.option_spec)
     option_spec['hex'] = bool_option
@@ -18,7 +18,10 @@ class IntEnumDocumenter(ClassDocumenter):
     def can_document_member(cls,
                             member: Any, membername: str,
                             isattr: bool, parent: Any) -> bool:
-        return isinstance(member, IntEnum)
+        try:
+            return issubclass(member, IntEnum)
+        except TypeError:
+            return False
 
     def add_directive_header(self, sig: str) -> None:
         super().add_directive_header(sig)
@@ -36,14 +39,13 @@ class IntEnumDocumenter(ClassDocumenter):
         use_hex = self.options.hex
         self.add_line('', source_name)
 
-        for enum_value in enum_object:
-            the_value_name = enum_value.name
-            the_value_value = enum_value.value
+        for the_member_name, enum_member in enum_object.__members__.items():
+            the_member_value = enum_member.value
             if use_hex:
-                the_value_value = hex(the_value_value)
+                the_member_value = hex(the_member_value)
 
             self.add_line(
-                f"**{the_value_name}**: {the_value_value}", source_name)
+                f"**{the_member_name}**: {the_member_value}", source_name)
             self.add_line('', source_name)
 
 
diff --git a/doc/man/sphinx-autogen.rst b/doc/man/sphinx-autogen.rst
index 18ae8d1e9..4c8f0f207 100644
--- a/doc/man/sphinx-autogen.rst
+++ b/doc/man/sphinx-autogen.rst
@@ -39,6 +39,10 @@ Options
 
    Document imported members.
 
+.. option:: -a, --respect-module-all
+
+   Document exactly the members in a module's ``__all__`` attribute.
+
 Example
 -------
 
diff --git a/doc/tutorial/deploying.rst b/doc/tutorial/deploying.rst
new file mode 100644
index 000000000..85fc6643a
--- /dev/null
+++ b/doc/tutorial/deploying.rst
@@ -0,0 +1,279 @@
+Appendix: Deploying a Sphinx project online
+===========================================
+
+When you are ready to show your documentation project to the world, there are
+many options available to do so. Since the HTML generated by Sphinx is static,
+you can decouple the process of building your HTML documentation from hosting
+such files in the platform of your choice. You will not need a sophisticated
+server running Python: virtually every web hosting service will suffice.
+
+Therefore, the challenge is less how or where to serve the static HTML, but
+rather how to pick a workflow that automatically updates the deployed
+documentation every time there is a change in the source files.
+
+The following sections describe some of the available options to deploy
+your online documentation, and give some background information. If you want
+to go directly to the practical part, you can skip to :ref:`publishing-sources`.
+
+Sphinx-friendly deployment options
+----------------------------------
+
+There are several possible options you have to host your Sphinx documentation.
+Some of them are:
+
+**Read the Docs**
+   `Read the Docs`_ is an online service specialized in hosting technical
+   documentation written in Sphinx, as well as MkDocs. They have a
+   number of extra features, such as versioned documentation, traffic and
+   search analytics, custom domains, user-defined redirects, and more.
+
+**GitHub Pages**
+   `GitHub Pages`_ is a simple static web hosting tightly integrated with
+   `GitHub`_: static HTML is served from one of the branches of a project,
+   and usually sources are stored in another branch so that the output
+   can be updated every time the sources change (for example using `GitHub
+   Actions`_). It is free to use and supports custom domains.
+
+**GitLab Pages**
+   `GitLab Pages`_ is a similar concept to GitHub Pages, integrated with
+   `GitLab`_ and usually automated with `GitLab CI`_ instead.
+
+**Netlify**
+   `Netlify`_ is a sophisticated hosting for static sites enhanced by
+   client-side web technologies like JavaScript (so-called `"Jamstack"`_).
+   They offer support for headless content management systems and
+   serverless computing.
+
+**Your own server**
+   You can always use your own web server to host Sphinx HTML documentation.
+   It is the option that gives more flexibility, but also more complexity.
+
+All these options have zero cost, with the option of paying for extra features.
+
+.. _Read the Docs: https://readthedocs.org/
+.. _GitHub Pages: https://pages.github.com/
+.. _GitHub: https://github.com/
+.. _GitHub Actions: https://github.com/features/actions
+.. _GitLab Pages: https://about.gitlab.com/stages-devops-lifecycle/pages/
+.. _GitLab: https://gitlab.com/
+.. _GitLab CI: https://about.gitlab.com/stages-devops-lifecycle/continuous-integration/
+.. _Netlify: https://www.netlify.com/
+.. _"Jamstack": https://jamstack.org/
+
+Embracing the "Docs as Code" philosophy
+---------------------------------------
+
+The free offerings of most of the options listed above require your
+documentation sources to be publicly available. Moreover, these services
+expect you to use a `Version Control System`_, a technology that tracks the
+evolution of a collection of files as a series of snapshots ("commits").
+The practice of writing documentation in plain text files with the same tools
+as the ones used for software development is commonly known as `"Docs as Code"`_.
+
+The most popular Version Control System nowadays is Git_, a free and open
+source tool that is the backbone of services like GitHub and GitLab.
+Since both Read the Docs and Netlify have integrations with GitHub and GitLab,
+and both GitHub and GitLab have an integrated Pages product, the most effective
+way of automatically build your documentation online is to upload your sources
+to either of these Git hosting services.
+
+.. _Version Control System: https://en.wikipedia.org/wiki/Version_control
+.. _"Docs as Code": https://www.writethedocs.org/guide/docs-as-code/
+.. _Git: https://git-scm.com/
+
+.. _publishing-sources:
+
+Publishing your documentation sources
+-------------------------------------
+
+GitHub
+~~~~~~
+
+The quickest way to upload an existing project to GitHub is to:
+
+1. `Sign up for a GitHub account <https://github.com/signup>`_.
+2. `Create a new repository <https://github.com/new>`_.
+3. Open `the "Upload files" page`_ of your new repository.
+4. Select the files on your operating system file browser (in your case
+   ``README.rst``, ``lumache.py``, the makefiles under the ``docs`` directory,
+   and everything under ``docs/source``) and drag them to the GitHub interface
+   to upload them all.
+5. Click on the :guilabel:`Commit changes` button.
+
+.. _the "Upload files" page: https://docs.github.com/en/repositories/working-with-files/managing-files/adding-a-file-to-a-repository
+
+.. note::
+
+   Make sure you don't upload the ``docs/build`` directory, as it contains the
+   output generated by Sphinx and it will change every time you change the
+   sources, complicating your workflow.
+
+These steps do not require access to the command line or installing any
+additional software. To learn more, you can:
+
+- Follow `this interactive GitHub course`_ to learn more about how the GitHub
+  interface works.
+- Read `this quickstart tutorial`_ to install extra software on your machine
+  and have more flexibility. You can either use the Git command line, or the
+  GitHub Desktop application.
+
+.. _this interactive GitHub course: https://lab.github.com/githubtraining/introduction-to-github
+.. _this quickstart tutorial: https://docs.github.com/en/get-started/quickstart
+
+GitLab
+~~~~~~
+
+Similarly to GitHub, the fastest way to upload your project to GitLab is
+using the web interface:
+
+1. `Sign up for a GitLab account <https://gitlab.com/users/sign_up>`_.
+2. `Create a new blank project <https://gitlab.com/projects/new>`_.
+3. Upload the project files (in your case ``README.rst``, ``lumache.py``, the
+   makefiles under the ``docs`` directory, and everything under
+   ``docs/source``) one by one using the :guilabel:`Upload File` button [#f1]_.
+
+Again, these steps do not require additional software on your computer. To
+learn more, you can:
+
+- Follow `this tutorial`_ to install Git on your machine.
+- Browse the `GitLab User documentation`_ to understand the possibilities of
+  the platform.
+
+.. _this tutorial: https://docs.gitlab.com/ee/gitlab-basics/start-using-git.html
+.. _GitLab User documentation: https://docs.gitlab.com/ee/user/index.html
+
+.. note::
+
+   Make sure you don't upload the ``docs/build`` directory, as it contains the
+   output generated by Sphinx and it will change every time you change the
+   sources, complicating your workflow.
+
+.. [#f1] At the time of writing, `uploading whole directories to GitLab using
+         only the web
+         interface <https://gitlab.com/gitlab-org/gitlab/-/issues/228490>`_ is
+         not yet implemented.
+
+Publishing your HTML documentation
+----------------------------------
+
+Read the Docs
+~~~~~~~~~~~~~
+
+`Read the Docs`_ offers integration with both GitHub and GitLab. The quickest
+way of getting started is to follow :doc:`the RTD
+tutorial <readthedocs:tutorial/index>`, which is loosely based on this one.
+You can publish your sources on GitHub as explained :ref:`in the previous
+section <publishing-sources>`, then skip directly to
+:ref:`readthedocs:tutorial/index:Sign up for Read the Docs`.
+If you choose GitLab instead, the process is similar.
+
+GitHub Pages
+~~~~~~~~~~~~
+
+`GitHub Pages`_ requires you to :ref:`publish your
+sources <publishing-sources>` on `GitHub`_. After that, you will need an
+automated process that performs the ``make html`` step every time the sources
+change. That can be achieved using `GitHub Actions`_.
+
+After you have published your sources on GitHub, create a file named
+``.github/workflows/sphinx.yml`` in your repository with the following
+contents:
+
+.. code-block:: yaml
+   :caption: .github/workflows/
+
+   name: Sphinx build
+
+   on: push
+
+   jobs:
+     build:
+       runs-on: ubuntu-latest
+       steps:
+       - uses: actions/checkout@v2
+       - name: Build HTML
+         uses: ammaraskar/sphinx-action@0.4
+       - name: Upload artifacts
+         uses: actions/upload-artifact@v1
+         with:
+           name: html-docs
+           path: docs/build/html/
+       - name: Deploy
+         uses: peaceiris/actions-gh-pages@v3
+         if: github.ref == 'refs/heads/main'
+         with:
+           github_token: ${{ secrets.GITHUB_TOKEN }}
+           publish_dir: docs/build/html
+
+This contains a GitHub Actions workflow with a single job of four steps:
+
+1. Checkout the code.
+2. Build the HTML documentation using Sphinx.
+3. Attach the HTML output the artifacts to the GitHub Actions job, for easier
+   inspection.
+4. If the change happens on the default branch, take the contents of
+   ``docs/build/html`` and push it to the ``gh-pages`` branch.
+
+Next, you need to specify the dependencies for the ``make html`` step to be
+successful. For that, create a file ``docs/requirements.txt`` and add the
+following contents:
+
+.. code-block::
+   :caption: docs/requirements.txt
+
+   furo==2021.11.16
+
+And finally, you are ready to `enable GitHub Pages on your repository`_. For
+that, go to :guilabel:`Settings`, then :guilabel:`Pages` on the left sidebar,
+select the ``gh-pages`` branch in the "Source" dropdown menu, and click
+:guilabel:`Save`. After a few minutes, you should be able to see your HTML at
+the designated URL.
+
+.. _enable GitHub Pages on your repository: https://docs.github.com/en/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site
+
+GitLab Pages
+~~~~~~~~~~~~
+
+`GitLab Pages`_, on the other hand, requires you to :ref:`publish your
+sources <publishing-sources>` on `GitLab`_. When you are ready, you can
+automate the process of running ``make html`` using `GitLab CI`_.
+
+After you have published your sources on GitLab, create a file named
+``.gitlab-ci.yml`` in your repository with these contents:
+
+.. code-block:: yaml
+   :caption: .gitlab-ci.yml
+
+   stages:
+     - deploy
+
+   pages:
+     stage: deploy
+     image: python:3.9-slim
+     before_script:
+       - apt-get update && apt-get install make --no-install-recommends -y
+       - python -m pip install sphinx furo
+     script:
+       - cd docs && make html
+     after_script:
+       - mv docs/build/html/ ./public/
+     artifacts:
+       paths:
+       - public
+     rules:
+       - if: $CI_COMMIT_REF_NAME == $CI_DEFAULT_BRANCH
+
+This contains a GitLab CI workflow with one job of several steps:
+
+1. Install the necessary dependencies.
+2. Build the HTML documentation using Sphinx.
+3. Move the output to a known artifacts location.
+
+.. note::
+   You will need to `validate your account`_ by entering a payment method
+   (you will be charged a small amount that will then be reimbursed).
+
+.. _validate your account: https://about.gitlab.com/blog/2021/05/17/prevent-crypto-mining-abuse/#validating-an-account
+
+After that, if the pipeline is successful, you should be able to see your HTML
+at the designated URL.
diff --git a/doc/tutorial/describing-code.rst b/doc/tutorial/describing-code.rst
index bfeca0455..0b88f5bd9 100644
--- a/doc/tutorial/describing-code.rst
+++ b/doc/tutorial/describing-code.rst
@@ -14,8 +14,11 @@ section apply for the other domains as well.
 
 .. _tutorial-describing-objects:
 
+Python
+------
+
 Documenting Python objects
---------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Sphinx offers several roles and directives to document Python objects,
 all grouped together in :ref:`the Python domain <python-domain>`. For example,
@@ -68,7 +71,7 @@ Notice several things:
    ``.. function::`` directly.
 
 Cross-referencing Python objects
---------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 By default, most of these directives generate entities that can be
 cross-referenced from any part of the documentation by using
@@ -123,7 +126,7 @@ And finally, this is how the result would look:
 Beautiful, isn't it?
 
 Including doctests in your documentation
-----------------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Since you are now describing code from a Python library, it will become useful
 to keep both the documentation and the code as synchronized as possible.
@@ -229,3 +232,44 @@ And finally, ``make test`` reports success!
 For big projects though, this manual approach can become a bit tedious.
 In the next section, you will see :doc:`how to automate the
 process </tutorial/automatic-doc-generation>`.
+
+Other languages (C, C++, others)
+--------------------------------
+
+Documenting and cross-referencing objects
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Sphinx also supports documenting and cross-referencing objects written in
+other programming languages. There are four additional built-in domains:
+C, C++, JavaScript, and reStructuredText. Third-party extensions may
+define domains for more languages, such as
+
+- `Fortran <https://sphinx-fortran.readthedocs.io>`_,
+- `Julia <http://bastikr.github.io/sphinx-julia>`_, or
+- `PHP <https://github.com/markstory/sphinxcontrib-phpdomain>`_.
+
+For example, to document a C++ type definition, you would use the built-in
+:rst:dir:`cpp:type` directive, as follows:
+
+.. code-block:: rst
+
+   .. cpp:type:: std::vector<int> CustomList
+
+      A typedef-like declaration of a type.
+
+Which would give the following result:
+
+.. cpp:type:: std::vector<int> CustomList
+
+   A typedef-like declaration of a type.
+
+All such directives then generate references that can be
+cross-referenced by using the corresponding role. For example, to reference
+the previous type definition, you can use the :rst:role:`cpp:type` role
+as follows:
+
+.. code-block:: rst
+
+   Cross reference to :cpp:type:`CustomList`.
+
+Which would produce a hyperlink to the previous definition: :cpp:type:`CustomList`.
diff --git a/doc/tutorial/index.rst b/doc/tutorial/index.rst
index 6a5e7de5f..1d12aff83 100644
--- a/doc/tutorial/index.rst
+++ b/doc/tutorial/index.rst
@@ -35,4 +35,5 @@ project.
    narrative-documentation
    describing-code
    automatic-doc-generation
+   deploying
    end
diff --git a/doc/tutorial/narrative-documentation.rst b/doc/tutorial/narrative-documentation.rst
index b1f23b0ff..a81204d4c 100644
--- a/doc/tutorial/narrative-documentation.rst
+++ b/doc/tutorial/narrative-documentation.rst
@@ -91,9 +91,7 @@ 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
+explicit *label* that acts as :duref:`a target <hyperlink-targets>`.
 
 For example, to reference the "Installation" subsection, add a label right
 before the heading, as follows:
diff --git a/doc/usage/configuration.rst b/doc/usage/configuration.rst
index 61878f225..0254d2dbd 100644
--- a/doc/usage/configuration.rst
+++ b/doc/usage/configuration.rst
@@ -1005,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
 
@@ -2686,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
 ---------------------------
diff --git a/doc/usage/extensions/autosummary.rst b/doc/usage/extensions/autosummary.rst
index 9533ed109..ac7bbd68f 100644
--- a/doc/usage/extensions/autosummary.rst
+++ b/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
diff --git a/doc/usage/extensions/math.rst b/doc/usage/extensions/math.rst
index 764bf5dd3..626306089 100644
--- a/doc/usage/extensions/math.rst
+++ b/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).