Merge branch 'master' into untyped-call

Author: AA-Turner

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/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

@@ -97,7 +97,7 @@ lint = [
     "mypy==1.16.1",
     "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",
@@ -166,7 +166,7 @@ types = [
 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",
@@ -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",

sphinx/ext/intersphinx/_resolve.py

@@ -46,7 +46,12 @@ def _create_element_from_result(
         # get correct path in case of subdirectories
         uri = (_relative_path(Path(), Path(node['refdoc']).parent) / uri).as_posix()
     if inv_item.project_version:
-        reftitle = _('(in %s v%s)') % (inv_item.project_name, inv_item.project_version)
+        if not inv_item.project_version[0].isdigit():
+            # Do not append 'v' to non-numeric version
+            version = inv_item.project_version
+        else:
+            version = f'v{inv_item.project_version}'
+        reftitle = _('(in %s %s)') % (inv_item.project_name, version)
     else:
         reftitle = _('(in %s)') % (inv_item.project_name,)
 

sphinx/texinputs/sphinxlatextables.sty

@@ -1,7 +1,7 @@
 %% TABLES (WITH SUPPORT FOR MERGED CELLS OF GENERAL CONTENTS)
 %
 % change this info string if making any custom modification
-\ProvidesPackage{sphinxlatextables}[2025/06/09 v8.3.0 tables]%
+\ProvidesPackage{sphinxlatextables}[2025/06/30 v8.3.0 tables]%
 
 % Provides support for this output mark-up from Sphinx latex writer
 % and table templates:
@@ -42,6 +42,22 @@
 % - \sphinxthistablewithnocolorrowsstyle
 % - \sphinxthistablewithvlinesstyle
 % - \sphinxthistablewithnovlinesstyle
+% - \sphinxbeforeendvarwidth
+
+% At 8.3.0, ALL table cell contents are wrapped into a varwidth environment.
+% This helps solve issues such as #3447, #8828, and helps use tabulary
+% in many more cases hence obtain better looking tables.
+\def\sphinxbeforeendvarwidth{\par\vskip-\baselineskip\hbox{\strut}}
+% MEMO: Mark-up uses the above macro right before all \end{varwdith} so that
+% if the cell in a row extends lower than the others, its last line acquires
+% standard "depth". Else it may lack any depth if without descenders such as
+% "p" or "q" letters and the horizontal line or color panel will look strange.
+% It originates in PR #3435 from 2017 which solved *many* table issues for
+% merged cells (and injected the varwidth technique now at 8.3.0 applied to
+% all cells).  The original used \vbox{\hbox{\strut}} but that \vbox appears
+% to do nothing, and it was decided after some testing (July 2025) to remove
+% it, the original rationale for it being now lost.
+
 % These conditionals added at 8.3.0 for nested tables not to break row colors
 % (#13635).  Nested tables are only partially supported by Sphinx LaTeX.
 % The method here is with no changes to neither writer nor templates.
@@ -251,7 +267,32 @@
 %
 % configuration of tabulary
 \setlength{\tymin}{3\fontcharwd\font`0 }% minimal width of "squeezed" columns
-\setlength{\tymax}{10000pt}% allow enough room for paragraphs to "compete"
+\setlength{\tymax}{3000pt}% allow enough room for paragraphs to "compete"
+%
+% MEMO: tabulary initially renders cell contents "horizontally" to measure
+%       them and compare their relative importance.  Its goal is to choose the
+%       column width so that, roughly, all columns will look about evenly
+%       filled.  "Horizontal" rendering is incompatible with many LaTeX
+%       structures such as lists, so prior to Sphinx 8.3.0 cells with such
+%       "problematic" contents caused Sphinx to use tabular not tabulary; the
+%       tabular would then render each column in absence of :widths: option or
+%       tabularcolumns directive the same width equal to available text width
+%       divided by number of columns.  At 8.3.0, "problematic" contents is
+%       wrapped into a "varwidth" environment, as was already done formerly
+%       for merged cells, and this avoids tabulary causing errors such as
+%       "incompatible with LR mode"; \sphinxcolwidth is used which sets
+%       the initial horizontal width for "varwidth". In the first tabulary
+%       pass, \sphinxcolwidth is configured (by us) to use \tymax.
+%
+%       During testing, it was determined that the former 10000pt setting for
+%       \tymax would cause "Dimension too large" TeX error if two columns or
+%       more had cells containing admonitions (such contents does not allow
+%       "varwidth" to reduce the width automatically).  So we use now 3000pt
+%       which allows up to 5 such columns while being large enough for
+%       tabulary algorithm to give good results for cells containing a few
+%       dozen words.  The tabulary default of 2\textwidth proves to be too
+%       small for that.
+%
 % we need access to tabulary's final computed width. \@tempdima is too volatile
 % to hope it has kept tabulary's value when \sphinxcolwidth needs it.
 \newdimen\sphinx@TY@tablewidth
@@ -302,9 +343,7 @@
 % ****            TODO: clarify if next paragraph means we must raise an
 % ****            if LaTeX writer detects a merged cell inside nested table.
 % MEMO about nesting: if sphinxmulticolumn is encountered in a nested tabular
-% inside a tabulary it will think to be at top level in the tabulary. But
-% Sphinx generates no nested tables, and if some LaTeX macro uses internally a
-% tabular this will not have a \sphinxstartmulticolumn within it!
+% inside a tabulary it will think to be at top level in the tabulary.
 %
 % 5.3.0 adds a check for multirow as single-row multi-column will allow a row
 % colour but multi-row multi-column should not.
@@ -407,8 +446,7 @@
 }%
 \newcommand*\sphinxcolwidth[2]{%
   % this dimension will always be used for varwidth, and serves as maximum
-  % width when cells are merged either via multirow or multicolumn or both,
-  % as always their contents is wrapped in varwidth environment.
+  % width for cells whose contents are wrapped in varwidth environment.
   \ifnum#1>\@ne % multi-column (and possibly also multi-row)
   % we wrote our own multicolumn code especially to handle that (and allow
   % verbatim contents)