Merge branch '4.x'

Author: tk0miya

CHANGES

@@ -28,15 +28,57 @@ Dependencies
 Incompatible changes
 --------------------
 
+* #9649: ``searchindex.js``: the embedded data has changed format to allow
+  objects with the same name in different domains.
+* #9672: The rendering of Python domain declarations is implemented
+  with more docutils nodes to allow better CSS styling.
+  It may break existing styling.
+* #9672: the signature of
+  :py:meth:`domains.py.PyObject.get_signature_prefix` has changed to
+  return a list of nodes instead of a plain string.
+* #9695: ``domains.js.JSObject.display_prefix`` has been changed into a method
+  ``get_display_prefix`` which now returns a list of nodes
+  instead of a plain string.
+* #9695: The rendering of Javascript domain declarations is implemented
+  with more docutils nodes to allow better CSS styling.
+  It may break existing styling.
+
+
 Deprecated
 ----------
 
 Features added
 --------------
 
+* #9639: autodoc: Support asynchronous generator functions
+* #9664: autodoc: ``autodoc-process-bases`` supports to inject reST snippet as a
+  base class
+* #9691: C, added new info-field ``retval``
+  for :rst:dir:`c:function` and :rst:dir:`c:macro`.
+* C++, added new info-field ``retval`` for :rst:dir:`cpp:function`.
+* #9672: More CSS classes on Python domain descriptions
+* #9695: More CSS classes on Javascript domain descriptions
+
 Bugs fixed
 ----------
 
+* #9630: autodoc: Failed to build cross references if :confval:`primary_domain`
+  is not 'py'
+* #9644: autodoc: Crashed on getting source info from problematic object
+* #9655: autodoc: mocked object having doc comment is warned unexpectedly
+* #9651: autodoc: return type field is not generated even if
+  :confval:`autodoc_typehints_description_target` is set to "documented" when
+  its info-field-list contains ``:returns:`` field
+* #9657: autodoc: The base class for a subclass of mocked object is incorrect
+* #9607: autodoc: Incorrect base class detection for the subclasses of the
+  generic class
+* #9630: autosummary: Failed to build summary table if :confval:`primary_domain`
+  is not 'py'
+* #9670: html: Fix download file with special characters
+* #9649: HTML search: when objects have the same name but in different domains,
+  return all of them as result instead of just one.
+* #9678: linkcheck: file extension was shown twice in warnings
+
 Testing
 --------
 
@@ -131,6 +173,7 @@ Bugs fixed
   with the HEAD of 3.10
 * #9436, #9471: autodoc: crashed if ``autodoc_class_signature = "separated"``
 * #9456: html search: html_copy_source can't control the search summaries
+* #9500: LaTeX: Failed to build Japanese document on Windows
 * #9435: linkcheck: Failed to check anchors in github.com
 
 Release 4.1.1 (released Jul 15, 2021)

doc/_static/conf.py.txt

@@ -1,8 +1,8 @@
 # test documentation build configuration file, created by
 # sphinx-quickstart on Sun Jun 26 00:00:43 2016.
 #
-# This file is execfile()d with the current directory set to its
-# containing dir.
+# This file is executed through importlib.import_module with 
+# the current directory set to its containing dir.
 #
 # Note that not all possible configuration values are present in this
 # autogenerated file.

doc/_static/tutorial/lumache-autosummary.png

@@ -118,7 +118,7 @@ <h2>{%trans%}Contributor Guide{%endtrans%}</h2>
     this part of the documentation is for you.{%endtrans%}</p>
 
     <ul>
-      <li>{%trans path=pathto("internals/contributing")%}<a href="{{ path }}">Sphinx Contributors’s Guide</a></li>{%endtrans%}
+      <li>{%trans path=pathto("internals/contributing")%}<a href="{{ path }}">Sphinx Contributors’ Guide</a></li>{%endtrans%}
       <li>{%trans path=pathto("internals/authors")%}<a href="{{ path }}">Sphinx Authors</a></li>{%endtrans%}
     </ul>
 

doc/_static/tutorial/lumache-py-function-full.png

@@ -16,6 +16,7 @@ Builder API
    .. autoattribute:: name
    .. autoattribute:: format
    .. autoattribute:: epilog
+   .. autoattribute:: allow_parallel
    .. autoattribute:: supported_image_types
    .. autoattribute:: supported_remote_images
    .. autoattribute:: supported_data_uri_images

doc/_static/tutorial/lumache-py-function.png

@@ -748,6 +748,11 @@ The following is a list of deprecated interfaces.
      - 4.0
      - ``sphinx.domains.std.StandardDomain.process_doc()``
 
+   * - ``sphinx.domains.js.JSObject.display_prefix``
+     - 
+     - 4.3
+     - ``sphinx.domains.js.JSObject.get_display_prefix()``
+
    * - ``sphinx.environment.NoUri``
      - 2.1
      - 3.0

doc/_templates/index.html

@@ -13,6 +13,10 @@ Domain API
 .. autoclass:: Index
    :members:
 
+.. module:: sphinx.directives
+
+.. autoclass:: ObjectDescription
+   :members:
 
 Python Domain
 -------------

doc/extdev/builderapi.rst

@@ -0,0 +1,166 @@
+Automatic documentation generation from code
+============================================
+
+In the :ref:`previous section <tutorial-describing-objects>` of the tutorial
+you manually documented a Python function in Sphinx. However, the description
+was out of sync with the code itself, since the function signature was not
+the same. Besides, it would be nice to reuse `Python
+docstrings <https://www.python.org/dev/peps/pep-0257/#what-is-a-docstring>`_
+in the documentation, rather than having to write the information in two
+places.
+
+Fortunately, :doc:`the autodoc extension </usage/extensions/autodoc>` provides this
+functionality.
+
+Reusing signatures and docstrings with autodoc
+----------------------------------------------
+
+To use autodoc, first add it to the list of enabled extensions:
+
+.. code-block:: python
+   :caption: docs/source/conf.py
+   :emphasize-lines: 4
+
+   extensions = [
+       'sphinx.ext.duration',
+       'sphinx.ext.doctest',
+       'sphinx.ext.autodoc',
+   ]
+
+Next, move the content of the ``.. py:function`` directive to the function
+docstring in the original Python file, as follows:
+
+.. code-block:: python
+   :caption: lumache.py
+   :emphasize-lines: 2-11
+
+   def get_random_ingredients(kind=None):
+       """
+       Return a list of random ingredients as strings.
+
+       :param kind: Optional "kind" of ingredients.
+       :type kind: list[str] or None
+       :raise lumache.InvalidKindError: If the kind is invalid.
+       :return: The ingredients list.
+       :rtype: list[str]
+
+       """
+       return ["shells", "gorgonzola", "parsley"]
+
+Finally, replace the ``.. py:function`` directive from the Sphinx documentation
+with :rst:dir:`autofunction`:
+
+.. code-block:: rst
+   :caption: docs/source/usage.rst
+   :emphasize-lines: 3
+
+   you can use the ``lumache.get_random_ingredients()`` function:
+
+   .. autofunction:: lumache.get_random_ingredients
+
+If you now build the HTML documentation, the output will be the same!
+With the advantage that it is generated from the code itself.
+Sphinx took the reStructuredText from the docstring and included it,
+also generating proper cross-references.
+
+You can also autogenerate documentation from other objects. For example, add
+the code for the ``InvalidKindError`` exception:
+
+.. code-block:: python
+   :caption: lumache.py
+
+   class InvalidKindError(Exception):
+       """Raised if the kind is invalid."""
+       pass
+
+And replace the ``.. py:exception`` directive with :rst:dir:`autoexception`
+as follows:
+
+.. code-block:: rst
+   :caption: docs/source/usage.rst
+   :emphasize-lines: 4
+
+   or ``"veggies"``. Otherwise, :py:func:`lumache.get_random_ingredients`
+   will raise an exception.
+
+   .. autoexception:: lumache.InvalidKindError
+
+And again, after running ``make html``, the output will be the same as before.
+
+Generating comprehensive API references
+---------------------------------------
+
+While using ``sphinx.ext.autodoc`` makes keeping the code and the documentation
+in sync much easier, it still requires you to write an ``auto*`` directive
+for every object you want to document. Sphinx provides yet another level of
+automation: the :doc:`autosummary </usage/extensions/autosummary>` extension.
+
+The :rst:dir:`autosummary` directive generates documents that contain all the
+necessary ``autodoc`` directives. To use it, first enable the autosummary
+extension:
+
+.. code-block:: python
+   :caption: docs/source/conf.py
+   :emphasize-lines: 5
+
+   extensions = [
+      'sphinx.ext.duration',
+      'sphinx.ext.doctest',
+      'sphinx.ext.autodoc',
+      'sphinx.ext.autosummary',
+   ]
+
+Next, create a new ``api.rst`` file with these contents:
+
+.. code-block:: rst
+   :caption: docs/source/api.rst
+
+   API
+   ===
+
+   .. autosummary::
+      :toctree: generated
+
+      lumache
+
+Remember to include the new document in the root toctree:
+
+.. code-block:: rst
+   :caption: docs/source/index.rst
+   :emphasize-lines: 7
+
+   Contents
+   --------
+
+   .. toctree::
+
+      usage
+      api
+
+Finally, after you build the HTML documentation running ``make html``, it will
+contain two new pages:
+
+- ``api.html``, corresponding to ``docs/source/api.rst`` and containing a table
+  with the objects you included in the ``autosummary`` directive (in this case,
+  only one).
+- ``generated/lumache.html``, corresponding to a newly created reST file
+  ``generated/lumache.rst`` and containing a summary of members of the module,
+  in this case one function and one exception.
+
+.. figure:: /_static/tutorial/lumache-autosummary.png
+   :width: 80%
+   :align: center
+   :alt: Summary page created by autosummary
+
+   Summary page created by autosummary
+
+Each of the links in the summary page will take you to the places where you
+originally used the corresponding ``autodoc`` directive, in this case in the
+``usage.rst`` document.
+
+.. note::
+
+   The generated files are based on `Jinja2
+   templates <https://jinja2docs.readthedocs.io/>`_ that
+   :ref:`can be customized <autosummary-customizing-templates>`,
+   but that is out of scope for this tutorial.