Merge remote-tracking branch 'upstream/master' into untyped-call

Author: adamtheturtle

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

@@ -62,10 +62,22 @@ Features added
 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.
@@ -83,6 +95,8 @@ Bugs fixed
   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/internals/contributing.rst

@@ -138,6 +138,10 @@ These are the basic steps needed to start developing on Sphinx.
 
 #. Wait for a core developer or contributor to review your changes.
 
+   You may be asked to address comments on the review. If so, please avoid
+   force pushing to the branch. Sphinx uses the *squash merge* strategy when
+   merging PRs, so follow-up commits will all be combined.
+
 
 Coding style
 ~~~~~~~~~~~~

doc/usage/restructuredtext/directives.rst

@@ -1483,60 +1483,95 @@ Check the :confval:`latex_table_style`.
 
 .. rst:directive:: .. tabularcolumns:: column spec
 
-   This directive influences only the LaTeX output for the next table in
-   source.  The mandatory argument is a column specification (known as an
-   "alignment preamble" in LaTeX idiom).  Please refer to a LaTeX
+   This directive influences only the LaTeX output, and only for the next
+   table in source.  The mandatory argument is a column specification (known
+   as an "alignment preamble" in LaTeX idiom).  Please refer to a LaTeX
    documentation, such as the `wiki page`_, for basics of such a column
    specification.
 
    .. _wiki page: https://en.wikibooks.org/wiki/LaTeX/Tables
 
    .. versionadded:: 0.3
 
+   Sphinx renders tables with at most 30 rows using ``tabulary`` (or
+   ``tabular`` if at least one cell contains either a code-block or a nested
+   table), and those with more rows with ``longtable``.  The advantage of
+   using ``tabulary`` is that it tries to compute automatically (internally to
+   LaTeX) suitable column widths.
+
+   The ``tabulary`` algorithm often works well, but in some cases when a cell
+   contains long paragraphs, the column will be given a large width and other
+   columns whose cells contain only single words may end up too narrow.  The
+   :rst:dir:`tabularcolumns` can help solve this via providing to LaTeX a
+   custom "alignment preamble" (aka "colspec").  For example ``lJJ`` will be
+   suitable for a three-columns table whose first column contains only single
+   words and the other two have cells with long paragraphs.
+
    .. note::
 
-      :rst:dir:`tabularcolumns` conflicts with ``:widths:`` option of table
-      directives.  If both are specified, ``:widths:`` option will be ignored.
+      Of course, a fully automated solution would be better, and it is still
+      hoped for, but it is an intrinsic aspect of ``tabulary``, and the latter
+      is in use by Sphinx ever since ``0.3``...  It looks as if solving the
+      problem of squeezed columns could require substantial changes to that
+      LaTeX package.  And no good alternative appears to exist, as of 2025.
+
+   .. hint::
+
+      A way to solve the issue for all tables at once, is to inject in the
+      LaTeX preamble (see :confval:`latex_elements`) a command such as
+      ``\setlength{\tymin}{1cm}`` which causes all columns to be at least
+      ``1cm`` wide (not counting inter-column whitespace).  Currently, Sphinx
+      configures ``\tymin`` to allow room for three characters at least.
 
-   Sphinx renders tables with at most 30 rows using ``tabulary``, and those
-   with more rows with ``longtable``.
+   Here is a more sophisticated "colspec", for a 4-columns table:
 
-   ``tabulary`` tries to compute automatically (internally to LaTeX) suitable
-   column widths.  However, cells are then not allowed to contain
-   "problematic" elements such as lists, object descriptions,
-   blockquotes... Sphinx will fall back to using ``tabular`` if such a cell is
-   encountered (or a nested ``tabulary``).  In such a case the table will have
-   a tendency to try to fill the whole available line width.
+   .. code-block:: latex
 
-   :rst:dir:`tabularcolumns` can help in coercing the usage of ``tabulary`` if
-   one is careful to not employ the ``tabulary`` column types (``L``, ``R``,
-   ``C`` or ``J``) for those columns with at least one "problematic" cell, but
-   only LaTeX's ``p{<width>}`` or Sphinx ``\X`` and ``\Y`` (described next).
+      .. tabularcolumns:: >{\raggedright}\Y{.4}>{\centering}\Y{.1}>{\sphinxcolorblend{!95!red}\centering\noindent\bfseries\color{red}}\Y{.12}>{\raggedright\arraybackslash}\Y{.38}
 
-   Literal blocks do not work at all with ``tabulary``.  Sphinx will fall back
-   to ``tabular`` or ``longtable`` environments depending on the number of
-   rows.  It will employ the :rst:dir:`tabularcolumns` specification only if it
-   contains no usage of the ``tabulary`` specific types.
+   This is used in Sphinx own PDF docs at :ref:`dev-deprecated-apis`.
+   Regarding column widths, this "colspec" achieves the same as would
+   ``:widths:`` option set to ``40 10 12 38`` but it injects extra effects.
+
+   .. note::
+
+      In case both :rst:dir:`tabularcolumns` and ``:widths:`` option of table
+      directives are used, ``:widths:`` option will be ignored by the LaTeX
+      builder.  Of course it is obeyed by other builders.
+
+   Literal blocks do not work at all with ``tabulary`` and Sphinx will then
+   fall back to ``tabular`` LaTeX environment.  It will employ the
+   :rst:dir:`tabularcolumns` specification in that case only if it contains no
+   usage of the ``tabulary`` specific column types (which are ``L``, ``R``,
+   ``C`` and ``J``).
 
    Besides the LaTeX ``l``, ``r``, ``c`` and ``p{width}`` column specifiers,
-   one can also use ``\X{a}{b}`` which configures the column width to be a
-   fraction ``a/b`` of the total line width and ``\Y{f}`` where ``f`` is a
-   decimal: for example ``\Y{0.2}`` means that the column will occupy ``0.2``
-   times the line width.
+   and the ``tabulary`` specific ``L``, ``R``, ``C`` and ``J``, one can also
+   use (with all table types) ``\X{a}{b}`` which configures the column width
+   to be a fraction ``a/b`` of the total line width and ``\Y{f}`` where ``f``
+   is a decimal: for example ``\Y{0.2}`` means that the column will occupy
+   ``0.2`` times the line width.
 
 .. versionchanged:: 1.6
 
-   Use ``J`` (justified) by default with ``tabulary``, not ``L``
+   Sphinx uses ``J`` (justified) by default with ``tabulary``, not ``L``
    (flushed-left).  To revert, include ``\newcolumntype{T}{L}`` in the LaTeX
    preamble, as in fact Sphinx uses ``T`` and sets it by default to be an
    alias of ``J``.
 
-.. hint::
+.. versionchanged:: 8.3.0
 
-   A frequent issue with ``tabulary`` is that columns with little contents
-   appear to be "squeezed".  One can add to the LaTeX preamble for example
-   ``\setlength{\tymin}{40pt}`` to ensure a minimal column width of ``40pt``,
-   the ``tabulary`` default of ``10pt`` being too small.
+   Formerly, Sphinx did not use ``tabulary`` if the table had at least one
+   cell containing "problematic" elements such as lists, object descriptions,
+   blockquotes (etc...) because such contents are not out-of-the-box
+   compatible with ``tabulary``.  At ``8.3.0`` a technique, which was already
+   in use for merged cells, was extended to such cases, and the sole
+   "problematic" contents are code-blocks and nested tables.  So tables
+   containing (only) cells with mutliple paragraphs, bullet or enumerated
+   lists, or line blocks, will now better fit to their contents (if not
+   rendered by ``longtable``).  Cells with object descriptions or admonitions
+   will still have a tendency to induce the table to fill the full text area
+   width, but columns in that table with no such contents will be tighter.
 
 .. hint::
 

pyproject.toml

@@ -93,19 +93,19 @@ docs = [
     "sphinxcontrib-websupport",
 ]
 lint = [
-    "ruff==0.12.0",
-    "mypy==1.16.1",
+    "ruff==0.12.5",
+    "mypy==1.17.0",
     "sphinx-lint>=0.9",
     "types-colorama==0.4.15.20240311",
-    "types-defusedxml==0.7.0.20250516",
+    "types-defusedxml==0.7.0.20250708",
     "types-docutils==0.21.0.20250525",
     "types-Pillow==10.2.0.20240822",
-    "types-Pygments==2.19.0.20250516",
+    "types-Pygments==2.19.0.20250715",
     "types-requests==2.32.4.20250611",  # align with requests
     "types-urllib3==1.26.25.14",
     "pyright==1.1.400",
     "pytest>=8.0",
-    "pypi-attestations==0.0.26",
+    "pypi-attestations==0.0.27",
     "betterproto==2.0.0b6",
 ]
 test = [
@@ -136,13 +136,13 @@ docs = [
     "sphinxcontrib-websupport",
 ]
 lint = [
-    "ruff==0.12.0",
+    "ruff==0.12.5",
     "sphinx-lint>=0.9",
 ]
 package = [
     "betterproto==2.0.0b6",  # resolution fails without betterproto
     "build",
-    "pypi-attestations==0.0.26",
+    "pypi-attestations==0.0.27",
     "twine>=6.1",
 ]
 test = [
@@ -158,18 +158,18 @@ translations = [
     "Jinja2>=3.1",
 ]
 types = [
-    "mypy==1.16.1",
+    "mypy==1.17.0",
     "pyrefly",
     "pyright==1.1.400",
     { include-group = "type-stubs" },
 ]
 type-stubs = [
     # align with versions used elsewhere
     "types-colorama==0.4.15.20240311",
-    "types-defusedxml==0.7.0.20250516",
+    "types-defusedxml==0.7.0.20250708",
     "types-docutils==0.21.0.20250525",
     "types-Pillow==10.2.0.20240822",
-    "types-Pygments==2.19.0.20250516",
+    "types-Pygments==2.19.0.20250715",
     "types-requests==2.32.4.20250611",
     "types-urllib3==1.26.25.14",
 ]
@@ -257,7 +257,6 @@ module = [
     "tests.test_builders.test_build_html_assets",
     "tests.test_builders.test_build_html_maths",
     "tests.test_builders.test_build_html_numfig",
-    "tests.test_builders.test_build_html_tocdepth",
     "tests.test_builders.test_build_html_toctree",
     "tests.test_builders.test_build_linkcheck",
     "tests.test_builders.test_build_warnings",
@@ -295,7 +294,6 @@ disallow_untyped_defs = false
 [[tool.mypy.overrides]]
 module = [
     # tests/
-    "tests.test_quickstart",
     "tests.test_search",
     # tests/test_builders
     "tests.test_builders.test_build_latex",

sphinx/application.py

@@ -52,7 +52,8 @@
     from sphinx.config import ENUM, _ConfigRebuild
     from sphinx.domains import Domain, Index
     from sphinx.environment.collectors import EnvironmentCollector
-    from sphinx.ext.autodoc import Documenter, _AutodocProcessDocstringListener
+    from sphinx.ext.autodoc._documenters import Documenter
+    from sphinx.ext.autodoc._event_listeners import _AutodocProcessDocstringListener
     from sphinx.ext.todo import todo_node
     from sphinx.extension import Extension
     from sphinx.registry import (

sphinx/cmd/quickstart.py

@@ -89,7 +89,8 @@
 
 
 # function to get input from terminal -- overridden by the test suite
-def term_input(prompt: str) -> str:
+# Arguments are positional-only to match ``input``.
+def term_input(prompt: str, /) -> str:
     if sys.platform == 'win32':
         # Important: On windows, readline is not enabled by default.  In these
         #            environment, escape sequences have been broken.  To avoid the

sphinx/events.py

@@ -28,7 +28,7 @@
     from sphinx.config import Config
     from sphinx.domains import Domain
     from sphinx.environment import BuildEnvironment
-    from sphinx.ext.autodoc import _AutodocProcessDocstringListener
+    from sphinx.ext.autodoc._event_listeners import _AutodocProcessDocstringListener
     from sphinx.ext.todo import todo_node