Merge branch 'master' into issue-11324-prep/linkcheck-tests-http-1.1

.github/workflows/main.yml

@@ -31,6 +31,7 @@ jobs:
         docutils:
         - "0.18"
         - "0.19"
+        - "0.20"
 
     steps:
     - uses: actions/checkout@v3
@@ -57,13 +58,7 @@ jobs:
       env:
         PYTHONWARNINGS: ""
     - name: Install Docutils ${{ matrix.docutils }}
-      run: python -m pip install --upgrade "docutils==${{ matrix.docutils }}.*"
-      if: "!endsWith(matrix.python, '-dev')"
-      env:
-        PYTHONWARNINGS: "error,default:pkg_resources is deprecated:DeprecationWarning::,default:Deprecated call to `pkg_resources.declare_namespace:DeprecationWarning::"
-    - name: Install Docutils ${{ matrix.docutils }} (ignore warnings)
-      run: python -m pip install --upgrade "docutils==${{ matrix.docutils }}.*"
-      if: "endsWith(matrix.python, '-dev')"
+      run: python -m pip install --upgrade "docutils~=${{ matrix.docutils }}.0"
       env:
         PYTHONWARNINGS: ""
     - name: Test with pytest

CHANGES

@@ -1,4 +1,4 @@
-Release 7.0.1 (in development)
+Release 7.1.0 (in development)
 ==============================
 
 Dependencies
@@ -10,15 +10,51 @@ Incompatible changes
 Deprecated
 ----------
 
+* #11412: Emit warnings on using a deprecated Python-specific index entry type
+  (namely, ``module``, ``keyword``, ``operator``, ``object``, ``exception``,
+  ``statement``, and ``builtin``) in the :rst:dir:`index` directive, and
+  set the removal version to Sphinx 9. Patch by Adam Turner.
+
 Features added
 --------------
 
+* #11415: Add a checksum to JavaScript and CSS asset URIs included within
+  generated HTML, using the CRC32 algorithm.
+* :meth:`~sphinx.application.Sphinx.require_sphinx` now allows the version
+  requirement to be specified as ``(major, minor)``.
+* #11011: Allow configuring a line-length limit for object signatures, via
+  :confval:`maximum_signature_line_length` and the domain-specific variants.
+  If the length of the signature (in characters) is greater than the configured
+  limit, each parameter in the signature will be split to its own logical line.
+  This behaviour may also be controlled by options on object description
+  directives, for example :rst:dir:`py:function:single-line-parameter-list`.
+  Patch by Thomas Louf, Adam Turner, and Jean-François B.
+* #10983: Support for multiline copyright statements in the footer block.
+  Patch by Stefanie Molin
+
 Bugs fixed
 ----------
 
 Testing
 --------
 
+Release 7.0.1 (released May 12, 2023)
+=====================================
+
+Dependencies
+------------
+
+* #11411: Support `Docutils 0.20`_. Patch by Adam Turner.
+
+.. _Docutils 0.20: https://docutils.sourceforge.io/RELEASE-NOTES.html#release-0-20-2023-05-04
+
+Bugs fixed
+----------
+
+* #11418: Clean up remaining references to ``sphinx.setup_command``
+  following the removal of support for setuptools.
+  Patch by Willem Mulder.
+
 Release 7.0.0 (released Apr 29, 2023)
 =====================================
 

Makefile

@@ -1,56 +1,43 @@
 PYTHON ?= python3
 
 .PHONY: all
-all: clean-pyc clean-backupfiles style-check type-check test
+all: style-check type-check test
 
 .PHONY: clean
-clean: clean-pyc clean-pycache clean-patchfiles clean-backupfiles clean-generated clean-testfiles clean-buildfiles clean-mypyfiles
-
-.PHONY: clean-pyc
-clean-pyc:
+clean: clean
+	# clean Python cache files:
 	find . -name '*.pyc' -exec rm -f {} +
 	find . -name '*.pyo' -exec rm -f {} +
-
-.PHONY: clean-pycache
-clean-pycache:
 	find . -name __pycache__ -exec rm -rf {} +
 
-.PHONY: clean-patchfiles
-clean-patchfiles:
-	find . -name '*.orig' -exec rm -f {} +
-	find . -name '*.rej' -exec rm -f {} +
-
-.PHONY: clean-backupfiles
-clean-backupfiles:
+	# clean backup files:
 	find . -name '*~' -exec rm -f {} +
 	find . -name '*.bak' -exec rm -f {} +
 	find . -name '*.swp' -exec rm -f {} +
 	find . -name '*.swo' -exec rm -f {} +
 
-.PHONY: clean-generated
-clean-generated:
+	# clean generated:
 	find . -name '.DS_Store' -exec rm -f {} +
-	rm -rf Sphinx.egg-info/
-	rm -rf dist/
+
+	# clean rendered documentation :
+	rm -rf doc/build/
 	rm -rf doc/_build/
-	rm -f sphinx/pycode/*.pickle
-	rm -f utils/*3.py*
-	rm -f utils/regression_test.js
+	rm -rf build/sphinx/
 
-.PHONY: clean-testfiles
-clean-testfiles:
+	# clean caches:
+	find . -name '.mypy_cache' -exec rm -rf {} +
+	find . -name '.ruff_cache' -exec rm -rf {} +
+
+	# clean test files:
 	rm -rf tests/.coverage
 	rm -rf tests/build
 	rm -rf .tox/
 	rm -rf .cache/
+	find . -name '.pytest_cache' -exec rm -rf {} +
 
-.PHONY: clean-buildfiles
-clean-buildfiles:
-	rm -rf build
-
-.PHONY: clean-mypyfiles
-clean-mypyfiles:
-	find . -name '.mypy_cache' -exec rm -rf {} +
+	# clean build files:
+	rm -rf dist/
+	rm -rf build/
 
 .PHONY: style-check
 style-check:

doc/_themes/sphinx13/layout.html

@@ -54,7 +54,7 @@ <h3>{{ _('Site navigation') }}</h3>
 
 {%- block footer %}
 <div class="footer" role="contentinfo">
-  {% trans path=pathto('copyright'), copyright=copyright|e %}&#169; <a href="{{ path }}">Copyright</a> {{ copyright }}.{% endtrans %}
+  {{ copyright_block() }}
   {% trans sphinx_version=sphinx_version|e %}Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> {{ sphinx_version }}.{% endtrans %}
 </div>
 {%- endblock %}

doc/latex.rst

@@ -1479,6 +1479,12 @@ Macros
   .. versionadded:: 6.2.0
      ``\sphinxparam``, ``\sphinxsamedocref``
 
+  .. versionadded:: 7.1.0
+     ``\sphinxparamcomma`` which defaults to a comma followed by a space and
+     ``\sphinxparamcommaoneperline`` which is used for one-parameter-per-line
+     signatures (see :confval:`maximum_signature_line_length`).  It defaults
+     to ``\texttt{,}`` to make these end-of-line separators more distinctive.
+
 - More text styling:
 
   .. csv-table::

doc/usage/configuration.rst

@@ -73,6 +73,10 @@ Project information
 
    A copyright statement in the style ``'2008, Author Name'``.
 
+   .. versionchanged:: 7.1
+      The value may now be a sequence of copyright statements in the above form,
+      which will be displayed each to their own line.
+
 .. confval:: project_copyright
 
    An alias of :confval:`copyright`.
@@ -337,6 +341,7 @@ General configuration
    * ``epub.unknown_project_files``
    * ``epub.duplicated_toc_entry``
    * ``i18n.inconsistent_references``
+   * ``index``
    * ``image.not_readable``
    * ``ref.term``
    * ``ref.ref``
@@ -388,6 +393,10 @@ General configuration
 
       Added ``i18n.inconsistent_references``
 
+    .. versionadded:: 7.1
+
+        Added ``index`` warning type.
+
 .. confval:: needs_sphinx
 
    If set to a ``major.minor`` version string like ``'1.1'``, Sphinx will
@@ -670,6 +679,25 @@ General configuration
       If the value is a fully-qualified name of a custom Pygments style class,
       this is then used as custom style.
 
+.. confval:: maximum_signature_line_length
+
+   If a signature's length in characters exceeds the number set, each
+   parameter within the signature will be displayed on an individual logical
+   line.
+
+   When ``None`` (the default), there is no maximum length and the entire
+   signature will be displayed on a single logical line.
+
+   A 'logical line' is similar to a hard line break---builders or themes may
+   choose to 'soft wrap' a single logical line, and this setting does not affect
+   that behaviour.
+
+   Domains may provide options to suppress any hard wrapping on an individual
+   object directive, such as seen in the C, C++, and Python domains (e.g.
+   :rst:dir:`py:function:single-line-parameter-list`).
+
+   .. versionadded:: 7.1
+
 .. confval:: add_function_parentheses
 
    A boolean that decides whether parentheses are appended to function and
@@ -2907,6 +2935,14 @@ Options for the C domain
 
   .. versionadded:: 4.0.3
 
+.. confval:: c_maximum_signature_line_length
+
+   If a signature's length in characters exceeds the number set, each
+   parameter will be displayed on an individual logical line. This is a
+   domain-specific setting, overriding :confval:`maximum_signature_line_length`.
+
+   .. versionadded:: 7.1
+
 .. _cpp-config:
 
 Options for the C++ domain
@@ -2937,6 +2973,14 @@ Options for the C++ domain
 
    .. versionadded:: 1.5
 
+.. confval:: cpp_maximum_signature_line_length
+
+   If a signature's length in characters exceeds the number set, each
+   parameter will be displayed on an individual logical line. This is a
+   domain-specific setting, overriding :confval:`maximum_signature_line_length`.
+
+   .. versionadded:: 7.1
+
 Options for the Python domain
 -----------------------------
 
@@ -2979,6 +3023,25 @@ Options for the Python domain
 
    .. note:: This configuration is still in experimental
 
+.. confval:: python_maximum_signature_line_length
+
+   If a signature's length in characters exceeds the number set, each
+   argument will be displayed on an individual logical line. This is a
+   domain-specific setting, overriding :confval:`maximum_signature_line_length`.
+
+   .. versionadded:: 7.1
+
+Options for the Javascript domain
+---------------------------------
+
+.. confval:: javascript_maximum_signature_line_length
+
+   If a signature's length in characters exceeds the number set, each
+   parameter will be displayed on an individual logical line. This is a
+   domain-specific setting, overriding :confval:`maximum_signature_line_length`.
+
+   .. versionadded:: 7.1
+
 Example of configuration file
 -----------------------------
 

doc/usage/restructuredtext/directives.rst

@@ -896,9 +896,10 @@ mainly contained in information units, such as the language reference.
 
       .. index::
          single: execution; context
-         module: __main__
-         module: sys
+         pair: module; __main__
+         pair: module; sys
          triple: module; search; path
+         seealso: scope
 
       The execution context
       ---------------------
@@ -916,25 +917,63 @@ mainly contained in information units, such as the language reference.
    The possible entry types are:
 
    single
-      Creates a single index entry.  Can be made a subentry by separating the
-      subentry text with a semicolon (this notation is also used below to
-      describe what entries are created).
+      Creates a single index entry.
+      Can be made a sub-entry by separating the sub-entry text with a semicolon
+      (this notation is also used below to describe what entries are created).
+      Examples:
+
+      .. code:: reStructuredText
+
+         .. index:: single: execution
+                    single: execution; context
+
+      - ``single: execution`` creates an index entry labelled ``execution``.
+      - ``single: execution; context`` creates an sub-entry of ``execution``
+        labelled ``context``.
    pair
-      ``pair: loop; statement`` is a shortcut that creates two index entries,
-      namely ``loop; statement`` and ``statement; loop``.
+      A shortcut to create two index entries.
+      The pair of values must be separated by a semicolon.
+      Example:
+
+      .. code:: reStructuredText
+
+         .. index:: pair: loop; statement
+
+      This would create two index entries; ``loop; statement`` and ``statement; loop``.
    triple
-      Likewise, ``triple: module; search; path`` is a shortcut that creates
-      three index entries, which are ``module; search path``, ``search; path,
-      module`` and ``path; module search``.
+      A shortcut to create three index entries.
+      All three values must be separated by a semicolon.
+      Example:
+
+      .. code:: reStructuredText
+
+         .. index:: triple: module; search; path
+
+      This would create three index entries; ``module; search path``,
+      ``search; path, module``, and ``path; module search``.
    see
-      ``see: entry; other`` creates an index entry that refers from ``entry`` to
-      ``other``.
+      A shortcut to create an index entry that refers to another entry.
+      Example:
+
+      .. code:: reStructuredText
+
+         .. index:: see: entry; other
+
+      This would create an index entry referring from ``entry`` to ``other``
+      (i.e. 'entry': See 'other').
    seealso
-      Like ``see``, but inserts "see also" instead of "see".
+      Like ``see``, but inserts 'see also' instead of 'see'.
    module, keyword, operator, object, exception, statement, builtin
-      These all create two index entries.  For example, ``module: hashlib``
-      creates the entries ``module; hashlib`` and ``hashlib; module``.  (These
-      are Python-specific and therefore deprecated.)
+      These **deprecated** shortcuts all create two index entries.
+      For example, ``module: hashlib`` creates the entries ``module; hashlib``
+      and ``hashlib; module``.
+
+      .. deprecated:: 1.0
+         These Python-specific entry types are deprecated.
+
+      .. versionchanged:: 7.1
+         Removal version set to Sphinx 9.0.
+         Using these entry types will now emit warnings with the ``index`` category.
 
    You can mark up "main" index entries by prefixing them with an exclamation
    mark.  The references to "main" entries are emphasized in the generated