Merge branch 'master' into dependabot/pip/pypi-attestations-0.0.27

Author: AA-Turner

.gitattributes

@@ -51,6 +51,8 @@ tests/roots/test-pycode/cp_1251_coded.py dos
 
 # Non UTF-8 encodings
 tests/roots/test-pycode/cp_1251_coded.py working-tree-encoding=windows-1251
+tests/roots/test-root/wrongenc.inc working-tree-encoding=latin-1
+tests/roots/test-warnings/wrongenc.inc working-tree-encoding=latin-1
 
 # Generated files
 # https://github.com/github/linguist/blob/master/docs/overrides.md

.github/workflows/main.yml

@@ -89,6 +89,7 @@ jobs:
       matrix:
         python:
         - "3.14"
+        - "3.15"
         docutils:
         - "0.20"
         - "0.21"
@@ -125,6 +126,7 @@ jobs:
       matrix:
         python:
         - "3.14"
+        - "3.15"
 
     steps:
     - uses: actions/checkout@v4

AUTHORS.rst

@@ -103,6 +103,7 @@ Contributors
 * Stefan Seefeld -- toctree improvements
 * Stefan van der Walt -- autosummary extension
 * Steve Piercy -- documentation improvements
+* Szymon Karpinski -- intersphinx improvements
 * \T. Powers -- HTML output improvements
 * Taku Shimizu -- epub3 builder
 * Thomas Lamb -- linkcheck builder

CHANGES.rst

@@ -7,9 +7,34 @@ Dependencies
 Incompatible changes
 --------------------
 
+* #13639: :py:meth:`!SphinxComponentRegistry.create_source_parser` no longer
+  has an *app* parameter, instead taking *config* and *env*.
+  Patch by Adam Turner.
+
 Deprecated
 ----------
 
+* 13627: Deprecate remaining public :py:attr:`!.app` attributes,
+  including ``builder.app``, ``env.app``, ``events.app``,
+  and ``SphinxTransform.`app``.
+  Patch by Adam Turner.
+* #13637: Deprecate the :py:meth:`!set_application` method
+  of :py:class:`~sphinx.parsers.Parser` objects.
+  Patch by Adam Turner.
+* #13644: Deprecate the :py:attr:`!Parser.config` and :py:attr:`!env` attributes.
+  Patch by Adam Turner.
+* #13665: Deprecate support for non-UTF 8 source encodings,
+  scheduled for removal in Sphinx 10.
+  Patch by Adam Turner.
+* #13679: Non-decodable characters in source files will raise an error in Sphinx 9.
+  Currently, such bytes are replaced with '?' along with logging a warning.
+  Patch by Adam Turner.
+* #13682: Deprecate :py:mod:`!sphinx.io`.
+  Sphinx no longer uses the :py:mod:`!sphinx.io` classes,
+  having replaced them with standard Python I/O.
+  The entire :py:mod:`!sphinx.io` module will be removed in Sphinx 10.
+  Patch by Adam Turner.
+
 Features added
 --------------
 
@@ -22,21 +47,56 @@ Features added
 * #13497: Support C domain objects in the table of contents.
 * #13500: LaTeX: add support for ``fontawesome6`` package.
   Patch by Jean-François B.
-* #13535: html search: Update to the latest version of Snowball (v3.0.1).
-  Patch by Adam Turner.
-* #13704: autodoc: Detect :py:func:`typing_extensions.overload <typing.overload>`
+* #13509: autodoc: Detect :py:func:`typing_extensions.overload <typing.overload>`
   and :py:func:`~typing.final` decorators.
   Patch by Spencer Brown.
+* #13535: html search: Update to the latest version of Snowball (v3.0.1).
+  Patch by Adam Turner.
+* #13647: LaTeX: allow more cases of table nesting.
+  Patch by Jean-François B.
+* #13684: intersphinx: Add a file-based cache for remote inventories.
+  The location of the cache directory must not be relied upon externally,
+  as it may change without notice or warning in future releases.
+  Patch by Adam Turner.
 
 Bugs fixed
 ----------
 
+* #1327: LaTeX: tables using longtable raise error if
+  :rst:dir:`tabularcolumns` specifies automatic widths
+  (``L``, ``R``, ``C``, or ``J``).
+  Patch by Jean-François B.
+* #3447: LaTeX: when assigning longtable class to table for PDF, it may render
+  "horizontally" and overflow in right margin.
+  Patch by Jean-François B.
+* #8828: LaTeX: adding a footnote to a longtable cell causes table to occupy
+  full width.
+  Patch by Jean-François B.
+* #11498: LaTeX: Table in cell fails to build if it has many rows.
+  Patch by Jean-François B.
+* #11515: LaTeX: longtable does not allow nested table.
+  Patch by Jean-François B.
+* #11973: LaTeX: links in table captions do not work in PDF.
+  Patch by Jean-François B.
 * #12821: LaTeX: URLs/links in section titles should render in PDF.
   Patch by Jean-François B.
 * #13369: Correctly parse and cross-reference unpacked type annotations.
   Patch by Alicia Garcia-Raboso.
 * #13528: Add tilde ``~`` prefix support for :rst:role:`py:deco`.
   Patch by Shengyu Zhang and Adam Turner.
+* #13597: LaTeX: table nested in a merged cell leads to invalid LaTeX mark-up
+  and PDF cannot be built.
+  Patch by Jean-François B.
+* #13619: LaTeX: possible duplicated footnotes in PDF from object signatures
+  (typically if :confval:`latex_show_urls` ``= 'footnote'``).
+  Patch by Jean-François B.
+* #13635: LaTeX: if a cell contains a table, row coloring is turned off for
+  the next table cells.
+  Patch by Jean-François B.
+* #13685: gettext: Correctly ignore trailing backslashes.
+  Patch by Bénédikt Tran.
+* #13712: intersphinx: Don't add "v" prefix to non-numeric versions.
+  Patch by Szymon Karpinski.
 
 Testing
 -------

doc/changes/5.3.rst

@@ -8,7 +8,10 @@ Release 5.3.0 (released Oct 16, 2022)
 
 * #10759: LaTeX: add :confval:`latex_table_style` and support the
   ``'booktabs'``, ``'borderless'``, and ``'colorrows'`` styles.
-  (thanks to Stefan Wiehler for initial pull requests #6666, #6671)
+  (thanks to Stefan Wiehler for initial pull requests #6666, #6671).
+  Using the ``'booktabs'`` style solves #6740 (Removing LaTeX
+  column borders for automatic colspec).
+  Patch by Jean-François B.
 * #10840: One can cross-reference including an option value like
   ``:option:`--module=foobar```, ``:option:`--module[=foobar]```,
   or ``:option:`--module foobar```.

doc/conf.py

@@ -297,14 +297,12 @@ def linkify_issues_in_changelog(
 ) -> None:
     """Linkify issue references like #123 in changelog to GitHub."""
     if docname == 'changes':
+        linkified_changelog = re.sub(r'(?:PR)?#([0-9]+)\b', _linkify, source[0])
+        source[0] = linkified_changelog
 
-        def linkify(match: re.Match[str]) -> str:
-            url = 'https://github.com/sphinx-doc/sphinx/issues/' + match[1]
-            return f'`{match[0]} <{url}>`_'
-
-        linkified_changelog = re.sub(r'(?:PR)?#([0-9]+)\b', linkify, source[0])
 
-        source[0] = linkified_changelog
+def _linkify(match: re.Match[str], /) -> str:
+    return f'`{match[0]} <https://github.com/sphinx-doc/sphinx/issues/{match[1]}>`__'
 
 
 REDIRECT_TEMPLATE = """

doc/development/tutorials/examples/recipe.py

@@ -165,7 +165,7 @@ def add_recipe(self, signature, ingredients):
             name,
             signature,
             'Recipe',
-            self.env.docname,
+            self.env.current_document.docname,
             anchor,
             0,
         ))

doc/development/tutorials/examples/todo.py

@@ -44,7 +44,7 @@ def run(self):
             self.env.todo_all_todos = []
 
         self.env.todo_all_todos.append({
-            'docname': self.env.docname,
+            'docname': self.env.current_document.docname,
             'lineno': self.lineno,
             'todo': todo_node.deepcopy(),
             'target': targetnode,

doc/development/tutorials/extending_build.rst

@@ -143,7 +143,7 @@ Looking first at the ``TodolistDirective`` directive:
 .. literalinclude:: examples/todo.py
    :language: python
    :linenos:
-   :lines: 24-27
+   :pyobject: TodolistDirective
 
 It's very simple, creating and returning an instance of our ``todolist`` node
 class.  The ``TodolistDirective`` directive itself has neither content nor
@@ -153,7 +153,7 @@ directive:
 .. literalinclude:: examples/todo.py
    :language: python
    :linenos:
-   :lines: 30-53
+   :pyobject: TodoDirective
 
 Several important things are covered here. First, as you can see, we're now
 subclassing the :class:`~sphinx.util.docutils.SphinxDirective` helper class
@@ -168,16 +168,16 @@ new unique integer on each call and therefore leads to unique target names. The
 target node is instantiated without any text (the first two arguments).
 
 On creating admonition node, the content body of the directive are parsed using
-``self.state.nested_parse``.  The first argument gives the content body, and
-the second one gives content offset.  The third argument gives the parent node
-of parsed result, in our case the ``todo`` node. Following this, the ``todo``
-node is added to the environment.  This is needed to be able to create a list of
-all todo entries throughout the documentation, in the place where the author
-puts a ``todolist`` directive.  For this case, the environment attribute
-``todo_all_todos`` is used (again, the name should be unique, so it is prefixed
-by the extension name).  It does not exist when a new environment is created, so
-the directive must check and create it if necessary.  Various information about
-the todo entry's location are stored along with a copy of the node.
+``self.parse_content_to_nodes()``.
+Following this, the ``todo`` node is added to the environment.
+This is needed to be able to create a list of all todo entries throughout
+the documentation, in the place where the author puts a ``todolist`` directive.
+For this case, the environment attribute ``todo_all_todos`` is used
+(again, the name should be unique, so it is prefixed by the extension name).
+It does not exist when a new environment is created, so the directive must
+check and create it if necessary.
+Various information about the todo entry's location are stored along with
+a copy of the node.
 
 In the last line, the nodes that should be put into the doctree are returned:
 the target node and the admonition node.
@@ -211,7 +211,7 @@ the :event:`env-purge-doc` event:
 .. literalinclude:: examples/todo.py
    :language: python
    :linenos:
-   :lines: 56-61
+   :pyobject: purge_todos
 
 Since we store information from source files in the environment, which is
 persistent, it may become out of date when the source file changes.  Therefore,
@@ -229,20 +229,21 @@ to be merged:
 .. literalinclude:: examples/todo.py
    :language: python
    :linenos:
-   :lines: 64-68
+   :pyobject: merge_todos
 
 
 The other handler belongs to the :event:`doctree-resolved` event:
 
 .. literalinclude:: examples/todo.py
    :language: python
    :linenos:
-   :lines: 71-113
+   :pyobject: process_todo_nodes
 
-The :event:`doctree-resolved` event is emitted at the end of :ref:`phase 3
-(resolving) <build-phases>` and allows custom resolving to be done. The handler
-we have written for this event is a bit more involved. If the
-``todo_include_todos`` config value (which we'll describe shortly) is false,
+The :event:`doctree-resolved` event is emitted for each document that is
+about to be written at the end of :ref:`phase 3 (resolving) <build-phases>`
+and allows custom resolving to be done on that document.
+The handler we have written for this event is a bit more involved.
+If the ``todo_include_todos`` config value (which we'll describe shortly) is false,
 all ``todo`` and ``todolist`` nodes are removed from the documents. If not,
 ``todo`` nodes just stay where and how they are.  ``todolist`` nodes are
 replaced by a list of todo entries, complete with backlinks to the location
@@ -266,17 +267,17 @@ the other parts of our extension. Let's look at our ``setup`` function:
 .. literalinclude:: examples/todo.py
    :language: python
    :linenos:
-   :lines: 116-
+   :pyobject: setup
 
 The calls in this function refer to the classes and functions we added earlier.
 What the individual calls do is the following:
 
 * :meth:`~Sphinx.add_config_value` lets Sphinx know that it should recognize the
-  new *config value* ``todo_include_todos``, whose default value should be
-  ``False`` (this also tells Sphinx that it is a boolean value).
+  new *config value* ``todo_include_todos``, whose default value is ``False``
+  (which also tells Sphinx that it is a boolean value).
 
-  If the third argument was ``'html'``, HTML documents would be full rebuild if the
-  config value changed its value.  This is needed for config values that
+  If the third argument was ``'html'``, HTML documents would be fully rebuilt
+  if the config value changed its value.  This is needed for config values that
   influence reading (build :ref:`phase 1 (reading) <build-phases>`).
 
 * :meth:`~Sphinx.add_node` adds a new *node class* to the build system.  It also

doc/extdev/deprecated.rst

@@ -22,6 +22,36 @@ The following is a list of deprecated interfaces.
      - Removed
      - Alternatives
 
+   * - ``sphinx.io`` (entire module)
+     - 8.3
+     - 10.0
+     - ``docutils.io`` or standard Python I/O
+
+   * - ``sphinx.builders.Builder.app``
+     - 8.3
+     - 10.0
+     - N/A
+
+   * - ``sphinx.environment.BuildEnvironment.app``
+     - 8.3
+     - 10.0
+     - N/A
+
+   * - ``sphinx.transforms.Transform.app``
+     - 8.3
+     - 10.0
+     - N/A
+
+   * - ``sphinx.transforms.post_transforms.SphinxPostTransform.app``
+     - 8.3
+     - 10.0
+     - N/A
+
+   * - ``sphinx.events.EventManager.app``
+     - 8.3
+     - 10.0
+     - N/A
+
    * - ``sphinx.builders.singlehtml.SingleFileHTMLBuilder.fix_refuris``
      - 8.2
      - 10.0