Merge branch '5.x'

.github/workflows/main.yml

@@ -5,73 +5,83 @@ on: [push, pull_request]
 jobs:
   ubuntu:
     runs-on: ubuntu-18.04
+    name: Python ${{ matrix.python }}
     strategy:
       fail-fast: false
       matrix:
-        name: [py36, py37, py38, py39, py310]
         include:
-        - name: py36
-          python: 3.6
+        - python: "3.6"
           docutils: du14
-        - name: py37
-          python: 3.7
+        - python: "3.7"
           docutils: du15
-        - name: py38
-          python: 3.8
+        - python: "3.8"
           docutils: du16
-        - name: py39
-          python: 3.9
+        - python: "3.9"
           docutils: du17
-          coverage: "--cov ./ --cov-append --cov-config setup.cfg"
-        - name: py310
-          python: "3.10"
-          docutils: du17
-        - name: py311-dev
-          python: 3.11-dev
+        - python: "3.10"
+          docutils: du18
+        - python: "3.11-dev"
           docutils: py311
-    env:
-      PYTEST_ADDOPTS: ${{ matrix.coverage }}
 
     steps:
-    - uses: actions/checkout@v2
+    - uses: actions/checkout@v3
     - name: Set up Python ${{ matrix.python }}
-      uses: actions/setup-python@v2
+      uses: actions/setup-python@v3
       if: "!endsWith(matrix.python, '-dev')"
       with:
         python-version: ${{ matrix.python }}
     - name: Set up Python ${{ matrix.python }} (deadsnakes)
       uses: deadsnakes/action@v2.0.1
-      if: endsWith(matrix.python, '-dev')
+      if: "endsWith(matrix.python, '-dev')"
       with:
         python-version: ${{ matrix.python }}
     - name: Check Python version
       run: python --version
     - name: Install graphviz
       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' }}
+      run: python -m pip install -U pip tox
     - name: Run Tox
       run: tox -e ${{ matrix.docutils }} -- -vv
-    - name: codecov
-      uses: codecov/codecov-action@v1
-      if: matrix.coverage
 
   windows:
     runs-on: windows-2019
-    strategy:
-      matrix:
-        architecture: [x86, x64]
-
     steps:
-    - uses: actions/checkout@v2
+    - uses: actions/checkout@v3
     - name: Set up Python
-      uses: actions/setup-python@v1
+      uses: actions/setup-python@v3
       with:
-        architecture: ${{ matrix.architecture }}
+        python-version: 3
     - name: Install dependencies
-      run:  pip install -U tox
+      run:  python -m pip install -U pip tox
     - name: Run Tox
       run:  tox -e py -- -vv
+
+  coverage:
+    # only run on pushes to branches in the sphinx-doc/sphinx repo
+    if: github.repository_owner == 'sphinx-doc' && github.event_name == 'push'
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v3
+    - name: Set up Python 3
+      uses: actions/setup-python@v3
+      with:
+        python-version: 3
+
+    - name: Check Python version
+      run: python --version
+
+    - name: Install graphviz
+      run: sudo apt-get install graphviz
+
+    - name: Install dependencies
+      run: python -m pip install -U pip tox pytest-cov
+
+    - name: Run Tox
+      run: tox --sitepackages -e py -- -vv
+      env:
+        PYTEST_ADDOPTS: "--cov ./ --cov-append --cov-config setup.cfg"
+
+    - name: codecov
+      uses: codecov/codecov-action@v3

CHANGES

@@ -19,7 +19,7 @@ Bugs fixed
 Testing
 --------
 
-Release 5.0.0 (in development)
+Release 5.1.0 (in development)
 ==============================
 
 Dependencies
@@ -28,6 +28,51 @@ Dependencies
 Incompatible changes
 --------------------
 
+Deprecated
+----------
+
+Features added
+--------------
+
+Bugs fixed
+----------
+
+Testing
+--------
+
+Release 5.0.0 beta2 (in development)
+====================================
+
+Dependencies
+------------
+
+Incompatible changes
+--------------------
+
+Deprecated
+----------
+
+Features added
+--------------
+
+Bugs fixed
+----------
+
+Testing
+--------
+
+Release 5.0.0 beta1 (released May 09, 2022)
+===========================================
+
+Dependencies
+------------
+* #10164: Support `Docutils 0.18`_. Patch by Adam Turner.
+
+.. _Docutils 0.18:  https://docutils.sourceforge.io/RELEASE-NOTES.html#release-0-18-2021-10-26
+
+Incompatible changes
+--------------------
+
 * #10031: autosummary: ``sphinx.ext.autosummary.import_by_name()`` now raises
   ``ImportExceptionGroup`` instead of ``ImportError`` when it failed to import
   target object.  Please handle the exception if your extension uses the
@@ -41,6 +86,7 @@ Incompatible changes
   To migrate: either add an explicit inventory name to the references
   intersphinx should resolve, or explicitly set the value of this configuration
   variable to an empty list.
+* #10197: html theme: Reduce ``body_min_width`` setting in basic theme to 360px
 * #9999: LaTeX: separate terms from their definitions by a CR (refs: #9985)
 * #10062: Change the default language to ``'en'`` if any language is not set in
   ``conf.py``
@@ -71,6 +117,10 @@ Deprecated
   required
 * The ``language`` argument of ``sphinx.util.i18n:format_date()`` becomes
   required
+* ``sphinx.builders.html.html5_ready``
+* ``sphinx.io.read_doc()``
+* ``sphinx.util.docutils.__version_info__``
+* ``sphinx.util.docutils.is_html5_writer_available()``
 * ``sphinx.writers.latex.LaTeXWriter.docclasses``
 
 Features added
@@ -85,14 +135,23 @@ Features added
 * #9792: autodoc: Add new option for ``autodoc_typehints_description_target`` to
   include undocumented return values but not undocumented parameters.
 * #10285: autodoc: singledispatch functions having typehints are not documented
+* autodoc: :confval:`autodoc_typehints_format` now also applies to attributes,
+  data, properties, and type variable bounds.
+* #10258: autosummary: Recognize a documented attribute of a module as
+  non-imported
 * #10028: Removed internal usages of JavaScript frameworks (jQuery and
   underscore.js) and modernised ``doctools.js`` and ``searchtools.js`` to
   EMCAScript 2018.
 * #10302: C++, add support for conditional expressions (``?:``).
+* #5157, #10251: Inline code is able to be highlighted via :rst:dir:`role`
+  directive
+* #10337: Make sphinx-build faster by caching Publisher object during build
 
 Bugs fixed
 ----------
 
+* #10200: apidoc: Duplicated submodules are shown for modules having both .pyx
+  and .so files
 * #10279: autodoc: Default values for keyword only arguments in overloaded
   functions are rendered as a string literal
 * #10280: autodoc: :confval:`autodoc_docstring_signature` unexpectedly generates
@@ -101,42 +160,28 @@ Bugs fixed
   mixture of keyword only arguments with/without defaults
 * #10310: autodoc: class methods are not documented when decorated with mocked
   function
+* #10305: autodoc: Failed to extract optional forward-ref'ed typehints correctly
+  via :confval:`autodoc_type_aliases`
+* #10421: autodoc: :confval:`autodoc_preserve_defaults` doesn't work on class
+  methods
 * #10214: html: invalid language tag was generated if :confval:`language`
   contains a country code (ex. zh_CN)
+* #9974: html: Updated jQuery version from 3.5.1 to 3.6.0
 * #10236: html search: objects are duplicated in search result
 * #9962: texinfo: Deprecation message for ``@definfoenclose`` command on
   bulding texinfo document
 * #10000: LaTeX: glossary terms with common definition are rendered with
   too much vertical whitespace
 * #10188: LaTeX: alternating multiply referred footnotes produce a ``?`` in
   pdf output
+* #10363: LaTeX: make ``'howto'`` title page rule use ``\linewidth`` for
+  compatibility with usage of a ``twocolumn`` class option
 * #10318: ``:prepend:`` option of :rst:dir:`literalinclude` directive does not
   work with ``:dedent:`` option
 
-Testing
---------
-
 Release 4.5.1 (in development)
 ==============================
 
-Dependencies
-------------
-
-Incompatible changes
---------------------
-
-Deprecated
-----------
-
-Features added
---------------
-
-Bugs fixed
-----------
-
-Testing
---------
-
 Release 4.5.0 (released Mar 28, 2022)
 =====================================
 

doc/development/theming.rst

@@ -265,7 +265,7 @@ Here is some sample code to accomplish this:
            copy_asset_file('path/to/myextension/_static/myjsfile.js', staticdir)
 
    def setup(app):
-       app.connect('builder-inited', copy_custom_files)
+       app.connect('build-finished', copy_custom_files)
 
 
 Inject JavaScript based on user configuration

doc/development/tutorials/examples/todo.py

@@ -70,7 +70,7 @@ def merge_todos(app, env, docnames, other):
 
 def process_todo_nodes(app, doctree, fromdocname):
     if not app.config.todo_include_todos:
-        for node in doctree.traverse(todo):
+        for node in doctree.findall(todo):
             node.parent.remove(node)
 
     # Replace all todolist nodes with a list of the collected todos.
@@ -80,7 +80,7 @@ def process_todo_nodes(app, doctree, fromdocname):
     if not hasattr(env, 'todo_all_todos'):
         env.todo_all_todos = []
 
-    for node in doctree.traverse(todolist):
+    for node in doctree.findall(todolist):
         if not app.config.todo_include_todos:
             node.replace_self([])
             continue
@@ -93,7 +93,7 @@ def process_todo_nodes(app, doctree, fromdocname):
             description = (
                 _('(The original entry is located in %s, line %d and can be found ') %
                 (filename, todo_info['lineno']))
-            para += nodes.Text(description, description)
+            para += nodes.Text(description)
 
             # Create a reference
             newnode = nodes.reference('', '')
@@ -104,7 +104,7 @@ def process_todo_nodes(app, doctree, fromdocname):
             newnode['refuri'] += '#' + todo_info['target']['refid']
             newnode.append(innernode)
             para += newnode
-            para += nodes.Text('.)', '.)')
+            para += nodes.Text('.)')
 
             # Insert into the todolist
             content.append(todo_info['todo'])

doc/extdev/deprecated.rst

@@ -22,6 +22,11 @@ The following is a list of deprecated interfaces.
      - (will be) Removed
      - Alternatives
 
+   * - ``sphinx.util.jsdump``
+     - 5.0
+     - 7.0
+     - The standard library ``json`` module.
+
    * - :doc:`Setuptools integration </usage/advanced/setuptools>`
      - 5.0
      - 7.0
@@ -37,6 +42,26 @@ The following is a list of deprecated interfaces.
      - 7.0
      - N/A
 
+   * - ``sphinx.builders.html.html5_ready``
+     - 5.0
+     - 7.0
+     - N/A
+
+   * - ``sphinx.io.read_doc()``
+     - 5.0
+     - 7.0
+     - ``sphinx.builders.Builder.read_doc()``
+
+   * - ``sphinx.util.docutils.__version_info__``
+     - 5.0
+     - 7.0
+     - ``docutils.__version_info__``
+
+   * - ``sphinx.util.docutils.is_html5_writer_available()``
+     - 5.0
+     - 7.0
+     - N/A
+
    * - ``sphinx.writers.latex.LaTeXWriter.docclasses``
      - 5.0
      - 7.0

doc/usage/configuration.rst

@@ -552,7 +552,7 @@ General configuration
          make latex O="-D smartquotes_action="
 
       This can follow some ``make html`` with no problem, in contrast to the
-      situation from the prior note.  It requires Docutils 0.14 or later.
+      situation from the prior note.
 
    .. versionadded:: 1.6.6
 

doc/usage/extensions/napoleon.rst

@@ -53,7 +53,7 @@ source code files.
 .. _Google Python Style Guide:
    https://google.github.io/styleguide/pyguide.html
 .. _Google:
-   https://google.github.io/styleguide/pyguide.html#Comments
+   https://google.github.io/styleguide/pyguide.html#38-comments-and-docstrings
 .. _NumPy:
    https://numpydoc.readthedocs.io/en/latest/format.html#docstring-standard
 .. _Khan Academy:
@@ -298,7 +298,7 @@ sure that "sphinx.ext.napoleon" is enabled in `conf.py`::
     napoleon_attr_annotations = True
 
 .. _Google style:
-   https://google.github.io/styleguide/pyguide.html
+   https://google.github.io/styleguide/pyguide.html#38-comments-and-docstrings
 .. _NumPy style:
    https://numpydoc.readthedocs.io/en/latest/format.html#docstring-standard
 

doc/usage/restructuredtext/directives.rst

@@ -499,8 +499,10 @@ __ https://pygments.org/docs/lexers
    The directive's alias name :rst:dir:`sourcecode` works as well.  This
    directive takes a language name as an argument.  It can be `any lexer alias
    supported by Pygments <https://pygments.org/docs/lexers/>`_.  If it is not
-   given, the setting of :rst:dir:`highlight` directive will be used.
-   If not set, :confval:`highlight_language` will be used.
+   given, the setting of :rst:dir:`highlight` directive will be used.  If not
+   set, :confval:`highlight_language` will be used.  To display a code example
+   *inline* within other text, rather than as a separate block, you can use the
+   :rst:role:`code` role instead.
 
    .. versionchanged:: 2.0
       The ``language`` argument becomes optional.