Merge branch '4.x' into 9623_suppress_warnings_for_excluded_document_…

…in_toctree

.github/workflows/docutils-latest.yml

@@ -0,0 +1,25 @@
+name: Test with the HEAD of docutils
+
+on:
+  schedule:
+  - cron: "0 0 * * SUN"
+  workflow_dispatch:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v2
+    - name: Set up Python
+      uses: actions/setup-python@v2
+    - name: Check Python version
+      run: python --version
+    - name: Unpin docutils
+      run: sed -i -e "s/'docutils>=.*'/'docutils'/" setup.py
+    - name: Install graphviz
+      run: sudo apt-get install graphviz
+    - name: Install dependencies
+      run: pip install -U tox codecov
+    - name: Run Tox
+      run: tox -e du-latest -- -vv

.github/workflows/main.yml

@@ -8,7 +8,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        name: [py36, py37, py38, py39]
+        name: [py36, py37, py38, py39, py310]
         include:
         - name: py36
           python: 3.6
@@ -23,9 +23,12 @@ jobs:
           python: 3.9
           docutils: du17
           coverage: "--cov ./ --cov-append --cov-config setup.cfg"
-        - name: py310-dev
-          python: 3.10-dev
+        - name: py310
+          python: "3.10"
           docutils: du17
+        - name: py311-dev
+          python: 3.11-dev
+          docutils: py311
     env:
       PYTEST_ADDOPTS: ${{ matrix.coverage }}
 
@@ -47,6 +50,9 @@ jobs:
       run: sudo apt-get install graphviz
     - name: Install dependencies
       run: pip install -U tox codecov
+    - name: Install the latest py package (for py3.11-dev)
+      run: pip install -U git+https://github.com/pytest-dev/py
+      if: ${{ matrix.python == '3.11-dev' }}
     - name: Run Tox
       run: tox -e ${{ matrix.docutils }} -- -vv
     - name: codecov

.github/workflows/transifex.yml

@@ -15,6 +15,8 @@ jobs:
         ref: 4.x
     - name: Set up Python
       uses: actions/setup-python@v2
+      with:
+        python-version: 3.9  # https://github.com/transifex/transifex-client/pull/330
     - name: Install dependencies
       run:  pip install -U babel jinja2 transifex-client
     - name: Extract translations from source code
@@ -33,6 +35,8 @@ jobs:
         ref: 4.x
     - name: Set up Python
       uses: actions/setup-python@v2
+      with:
+        python-version: 3.9  # https://github.com/transifex/transifex-client/pull/330
     - name: Install dependencies
       run:  pip install -U babel jinja2 transifex-client
     - name: Extract translations from source code

CHANGES

@@ -4,21 +4,100 @@ Release 4.3.0 (in development)
 Dependencies
 ------------
 
+* Support Python 3.10
+
 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.
+* #9450: mathjax: Load MathJax via "defer" strategy
+
+
 Deprecated
 ----------
 
+* ``sphinx.ext.autodoc.AttributeDocumenter._datadescriptor``
+* ``sphinx.writers.html.HTMLTranslator._fieldlist_row_index``
+* ``sphinx.writers.html.HTMLTranslator._table_row_index``
+* ``sphinx.writers.html5.HTML5Translator._fieldlist_row_index``
+* ``sphinx.writers.html5.HTML5Translator._table_row_index``
+
 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
+* #9683: Revert the removal of ``add_stylesheet()`` API.  It will be kept until
+  the Sphinx-6.0 release
+* #2068, add :confval:`intersphinx_disabled_reftypes` for disabling
+  interphinx resolution of cross-references that do not have an explicit
+  inventory specification. Specific types of cross-references can be disabled,
+  e.g., ``std:doc`` or all cross-references in a specific domain,
+  e.g., ``std:*``.
 * #9623: Allow to suppress "toctree contains reference to excluded document"
   warnings using :confval:`suppress_warnings`
 
 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
+* #9755: autodoc: memory addresses are shown for aliases
+* #9752: autodoc: Failed to detect type annotation for slots attribute
+* #9756: autodoc: Crashed if classmethod does not have __func__ attribute
+* #9757: autodoc: :confval:`autodoc_inherit_docstrings` does not effect to
+  overriden classmethods
+* #9781: autodoc: :confval:`autodoc_preserve_defaults` does not support
+  hexadecimal numeric
+* #9630: autosummary: Failed to build summary table if :confval:`primary_domain`
+  is not 'py'
+* #9670: html: Fix download file with special characters
+* #9710: html: Wrong styles for even/odd rows in nested tables
+* #9763: html: parameter name and its type annotation are not separated in HTML
+* #9649: HTML search: when objects have the same name but in different domains,
+  return all of them as result instead of just one.
+* #7634: intersphinx: references on the file in sub directory are broken
+* #9737: LaTeX: hlist is rendered as a list containing "aggedright" text
+* #9678: linkcheck: file extension was shown twice in warnings
+* #9697: py domain: An index entry with parens was registered for ``py:method``
+  directive with ``:property:`` option
+* #9775: py domain: Literal typehint was converted to a cross reference when
+  :confval:`autodoc_typehints='description'`
+* #9708: needs_extension failed to check double-digit version correctly
+* #9688: Fix :rst:dir:`code`` does not recognize ``:class:`` option
+* #9733: Fix for logging handler flushing warnings in the middle of the docs
+  build
+* #9656: Fix warnings without subtype being incorrectly suppressed
+* Intersphinx, for unresolved references with an explicit inventory,
+  e.g., ``proj:myFunc``, leave the inventory prefix in the unresolved text.
+
 Testing
 --------
 
@@ -113,6 +192,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/_templates/index.html

@@ -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/extdev/builderapi.rst

@@ -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/extdev/deprecated.rst

@@ -22,6 +22,31 @@ The following is a list of deprecated interfaces.
      - (will be) Removed
      - Alternatives
 
+   * - ``sphinx.ext.autodoc.AttributeDocumenter._datadescriptor``
+     - 4.3
+     - 6.0
+     - N/A
+
+   * - ``sphinx.writers.html.HTMLTranslator._fieldlist_row_index``
+     - 4.3
+     - 6.0
+     - ``sphinx.writers.html.HTMLTranslator._fieldlist_row_indices``
+
+   * - ``sphinx.writers.html.HTMLTranslator._table_row_index``
+     - 4.3
+     - 6.0
+     - ``sphinx.writers.html.HTMLTranslator._table_row_indices``
+
+   * - ``sphinx.writers.html5.HTML5Translator._fieldlist_row_index``
+     - 4.3
+     - 6.0
+     - ``sphinx.writers.html5.HTML5Translator._fieldlist_row_indices``
+
+   * - ``sphinx.writers.html5.HTML5Translator._table_row_index``
+     - 4.3
+     - 6.0
+     - ``sphinx.writers.html5.HTML5Translator._table_row_indices``
+
    * - The optional argument ``app`` for ``sphinx.environment.BuildEnvironment``
      - 4.1
      - 6.0
@@ -748,6 +773,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
@@ -1207,7 +1237,7 @@ The following is a list of deprecated interfaces.
 
    * - :meth:`~sphinx.application.Sphinx.add_stylesheet()`
      - 1.8
-     - 4.0
+     - 6.0
      - :meth:`~sphinx.application.Sphinx.add_css_file()`
 
    * - :meth:`~sphinx.application.Sphinx.add_javascript()`

doc/extdev/domainapi.rst

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