Merge branch 'master' into dependabot/pip/types-docutils-0.21.0.20250516

Author: adamtheturtle

.gitignore

@@ -3,6 +3,7 @@
 *.so
 *.swp
 
+.auto/
 .dir-locals.el
 .cache/
 .idea

CHANGES.rst

@@ -20,6 +20,8 @@ Features added
   ``linkcheck_allowed_redirects = {}``.
   Patch by Adam Turner.
 * #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>`
@@ -29,6 +31,8 @@ Features added
 Bugs fixed
 ----------
 
+* #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`.

doc/latex.rst

@@ -1006,18 +1006,20 @@ The color used in the above example is available from having passed the
 
 ``iconpackage``
 
-    The name of the LaTeX package used for icons in the admonition titles.  It
-    defaults to ``fontawesome5`` or to fall-back ``fontawesome``.  In case
-    neither one is available the option value will automatically default to
-    ``none``, which means that no attempt at loading a package is done.
-    Independently of this setting, arbitrary LaTeX code can be associated to
-    each admonition type via ``div.<type>_icon-title`` keys which are
-    described in the :ref:`additionalcss` section.  If these keys are not
-    used, Sphinx will either apply its default choices of icons (if
-    ``fontawesome{5,}`` is available) or not draw the icon at all.  Notice that
-    if fall-back ``fontawesome`` is used the common icon for :dudir:`caution`
-    and :dudir:`danger` will default to "bolt" not "radiation", which is only
-    found in ``fontawesome5``.
+    The name of the LaTeX package used for rendering icons in the admonition
+    titles.  Its default is set dynamically to either ``fontawesome6``,
+    ``fontawesome5``, or ``fontawesome``, or ``none``, depending on whether
+    packages with those names exist in the used LaTeX installation.  The LaTeX
+    code will use ``\faIcon`` command if with ``fontawesome6/fontawesome5``,
+    and ``\faicon`` if with ``fontawesome``.  In the latter case the icon used
+    both for :dudir:`caution` and :dudir:`danger` will default to "bolt" not
+    "radiation", which is only found in ``fontawesome6`` and ``fontawesome5``.
+    If no "Font Awesome" related package is found (or if the option is set
+    forcefully to ``none``) the icons are silently dropped.  User can set this
+    option to some specific package and must configure the
+    ``div.note_title-icon`` and similar keys to use then that LaTeX package
+    interface (see the :ref:`additionalcss` section for these extra
+    ``'sphinxsetup'`` keys).
 
     .. versionadded:: 7.4.0
 
@@ -1410,17 +1412,17 @@ The next keys, for admonitions, :dudir:`topic`, contents_, and
   (it applies only to the icon, not to the title of the admonition).
 
 - ``div.<type>_title-icon``: the LaTeX code responsible for producing the
-  icon.  For example, the default for :dudir:`note` is
-  ``div.note_title-icon=\faIcon{info-circle}``.  This uses a command from the
-  LaTeX ``fontawesome5`` package, which is loaded automatically if available.
-
-  If neither ``fontawesome5`` nor fall-back ``fontawesome`` (for which the
-  associated command is :code-tex:`\\faicon`, not :code-tex:`\\faIcon`) are
-  found, or if the ``iconpackage`` key of :ref:`'sphinxsetup'
-  <latexsphinxsetup>` is set to load some other user-chosen package, or no
-  package at all, all the ``title-icons`` default to empty LaTeX code.  It is
-  up to user to employ this interface to inject the icon (or anything else)
-  into the PDF output.
+  icon.  If you want to modify the icons used by Sphinx, employ in these keys
+  the ``\faIcon`` LaTeX command (assuming either ``fontawesome6`` or
+  ``fontawesome5`` LaTeX package is available on your system).  For example
+  the default for :dudir:`note` is
+  ``div.note_title-icon=\faIcon{info-circle}`` with ``fontawesome5`` and
+  ``div.note_title-icon=\faIcon{circle-info}`` with ``fontawesome6`` (which is
+  used automatically if available).  If your system only provides the
+  ``fontawesome`` package (automatically detected) use its command ``\faicon``
+  rather in order to modify the choice of icons.  The ``iconpackage`` key can
+  be used to use some other package providing icons, use then the commands
+  suitable to that package as values of the ``div.<type>_title-icon`` keys.
 
 .. note::
 

sphinx/texinputs/sphinx.sty

@@ -9,7 +9,7 @@
 % by the Sphinx LaTeX writer.
 
 \NeedsTeXFormat{LaTeX2e}[1995/12/01]
-\ProvidesPackage{sphinx}[2024/11/23 v8.2.0 Sphinx LaTeX package (sphinx-doc)]
+\ProvidesPackage{sphinx}[2025/04/24 v8.3.0 Sphinx LaTeX package (sphinx-doc)]
 
 % provides \ltx@ifundefined
 % (many packages load ltxcmds: graphicx does for pdftex and lualatex but
@@ -67,7 +67,7 @@
    Footnote rendering may have had problems, due to extra package or
    document class; check latex log for instructions}%
 \@namedef{sphinx_buildwarning_badiconpackage}{%
-   You have set iconpackage=\spx@opt@iconpackage, but this LaTeX package
+   You have set iconpackage=\spx@usr@iconpackage, but this LaTeX package
    is not found}%
 
 %% OPTION HANDLING
@@ -672,7 +672,7 @@
 % defaults for them remain not to have specific colour.
 %
 % 7.4.0 adds keys for admonition titles: for background and foreground colors,
-% and for icons (whose defaults are picked from Free Fontawesome 5).
+% and for icons.
 \def\spx@tempa#1{%
   \expandafter\spx@tempb
   \csname if#1withshadowcolor\expandafter\endcsname
@@ -869,80 +869,106 @@
 }
 
 % 7.4.0 Support for icons in admonition titles
-% We try to
-% - get Sphinx PDF builds to process fine in absence of fontawesome5
-% - use fontawesome5 if present, but not if user prefers another package
-% - provide an interface for using other LaTeX code for icons
-% - provide an interface for using some other package than fontawesome5
-% Indeed we can't load fontawesome5 unconditionally even if available,
-% as it proves incompatible with fontawesome package.
-% We thus must delay its loading.
-\IfFileExists{fontawesome5.sty}{%
-  \DeclareStringOption[fontawesome5]{iconpackage}%
+%
+% We let Sphinx use in order of priority: some user-specifid package,
+% fontawesome6 (since 8.3.0), fontawesome5, fontawesome, or nothing (and then
+% not draw any icon).  To allow a user-specified package, an extra interface
+% is provided for specifying the icon-drawing LaTeX code.
+%
+% We can't load fontawesome6 (or 5) unconditionally even if available, as it
+% is incompatible with fontawesome package which may be preferred by user.  We
+% thus must delay loading the package to at begin document, and for now can
+% only set the default value of iconpackage key..
+\IfFileExists{fontawesome6.sty}{%
+  \DeclareStringOption[fontawesome6]{iconpackage}%
 }%
 {%
+ \IfFileExists{fontawesome5.sty}{%
+   \DeclareStringOption[fontawesome5]{iconpackage}%
+ }%
+ {%
   \IfFileExists{fontawesome.sty}
   {\DeclareStringOption[fontawesome]{iconpackage}}
   {\DeclareStringOption[none]{iconpackage}}%
+ }%
 }%
-\newcommand\spx@faIcon[2][]{}%
-% The above \spx@faIcon which gobbles one mandatory and one optional
-% argument is put into use only if both fontawesome5 and fontawesome
-% LaTeX packages are not available, as part of the defaults for the
-% div.*_title-icon keys (these keys can be redefined via the sphinxsetup
-% interface).
-%
-\def\spxstring@fontawesome{fontawesome}
-\def\spxstring@fontawesomev{fontawesome5}
+% Unfortunately icon names differ between fontawesome, fontawesome5, and
+% fontawesome6 LaTeX packages.  At 8.3.0 we refactor the icon support code
+% into something easier to maintain in future in case of a fontawesome7,
+% etc...
+%
+% TODO: Handle spaces possibly caused by bad user usage of iconpackage key?
+%       This would need to check how LaTeX handle spaces in package name
+%       in \RequirePackage command.  Things in this area may have changed
+%       recently (2025/04).
 \AtBeginDocument{%
   \ifx\spx@opt@iconpackage\spxstring@none
   \else
       \IfFileExists{\spx@opt@iconpackage.sty}
-         {\RequirePackage{\spx@opt@iconpackage}%
-          \ifx\spx@opt@iconpackage\spxstring@fontawesomev
-              \renewcommand\spx@faIcon{\faIcon}%
-          \else
-          \ifx\spx@opt@iconpackage\spxstring@fontawesome
-              \renewcommand\spx@faIcon[2][]{\faicon{##2}}%
-              % The \ifdefined's are a bit silly because we know that
-              % fontawesome.sty does not provide it, but perhaps
-              % there can be some new release of that package?
-              \ifdefined\faicon@lightbulb\else
-                   \let\faicon@lightbulb\faLightbulbO
-              \fi
-              \ifdefined\faicon@radiation\else
-                   \let\faicon@radiation\faBolt
-              \fi
-              \ifdefined\faicon@pen\else
-                   \let\faicon@pen\faPencil
-              \fi
-          % if neither has been required, \spx@faIcon will simply swallow
-          % its argument and it is up to user
-          % to set the various div.*_title-icon keys appropriately.
-          \fi\fi %
-         }%
+         {\RequirePackage{\spx@opt@iconpackage}}%
          {%
-         \sphinxbuildwarning{badiconpackage}%
-         \PackageWarningNoLine{sphinx}{%
-            You have set iconpackage=\spx@opt@iconpackage\MessageBreak
-            But \spx@opt@iconpackage.sty is not found by LaTeX}
+          \let\spx@usr@iconpackage\spx@opt@iconpackage
+          \sphinxbuildwarning{badiconpackage}%
+          \PackageWarningNoLine{sphinx}{%
+            You have set iconpackage=\spx@usr@iconpackage\MessageBreak
+            But \spx@usr@iconpackage.sty is not found by LaTeX}
+          \let\spx@opt@iconpackage\spxstring@none
          }%
   \fi
 }
 
+% Icon defaults depending on package used.
+% Attention! no extra spaces for alignment when using \@namedef!
+\@namedef{spx@fontawesome6@note}{\faIcon{circle-info}}
+\@namedef{spx@fontawesome6@hint}{\faIcon[regular]{lightbulb}}
+\@namedef{spx@fontawesome6@tip}{\faIcon[regular]{lightbulb}}
+\@namedef{spx@fontawesome6@seealso}{\faIcon{share}}
+\@namedef{spx@fontawesome6@todo}{\faIcon{pen}}
+\@namedef{spx@fontawesome6@important}{\faIcon{circle-pause}}
+\@namedef{spx@fontawesome6@caution}{\faIcon{radiation}}
+\@namedef{spx@fontawesome6@warning}{\faIcon{triangle-exclamation}}
+\@namedef{spx@fontawesome6@attention}{\faIcon{triangle-exclamation}}
+\@namedef{spx@fontawesome6@danger}{\faIcon{radiation}}
+\@namedef{spx@fontawesome6@error}{\faIcon{circle-xmark}}
+
+\@namedef{spx@fontawesome5@note}{\faIcon{info-circle}}
+\@namedef{spx@fontawesome5@hint}{\faIcon[regular]{lightbulb}}
+\@namedef{spx@fontawesome5@tip}{\faIcon[regular]{lightbulb}}
+\@namedef{spx@fontawesome5@seealso}{\faIcon{share}}
+\@namedef{spx@fontawesome5@todo}{\faIcon{pen}}
+\@namedef{spx@fontawesome5@important}{\faIcon{pause-circle}}
+\@namedef{spx@fontawesome5@caution}{\faIcon{radiation}}
+\@namedef{spx@fontawesome5@warning}{\faIcon{exclamation-triangle}}
+\@namedef{spx@fontawesome5@attention}{\faIcon{exclamation-triangle}}
+\@namedef{spx@fontawesome5@danger}{\faIcon{radiation}}
+\@namedef{spx@fontawesome5@error}{\faIcon{times-circle}}
+
+\def\spx@fontawesome@note     {\faicon{info-circle}}
+\def\spx@fontawesome@hint     {\faicon{lightbulb-o}}
+\def\spx@fontawesome@tip      {\faicon{lightbulb-o}}
+\def\spx@fontawesome@seealso  {\faicon{share}}
+\def\spx@fontawesome@todo     {\faicon{pencil}}
+\def\spx@fontawesome@important{\faicon{pause-circle}}
+\def\spx@fontawesome@caution  {\faicon{bolt}}
+\def\spx@fontawesome@warning  {\faicon{exclamation-triangle}}
+\def\spx@fontawesome@attention{\faicon{exclamation-triangle}}
+\def\spx@fontawesome@danger   {\faicon{bolt}}
+\def\spx@fontawesome@error    {\faicon{times-circle}}
+
+% \spx@none@{note,hint,...} left undefined, the \@nameuse will be \relax
+\def\spx@titleicon@default#1{\@nameuse{spx@\spx@opt@iconpackage @#1}}
 \setkeys{sphinx}{
-% Icon defaults.
-  div.note_title-icon      = \spx@faIcon{info-circle},
-  div.hint_title-icon      = \spx@faIcon[regular]{lightbulb},
-  div.tip_title-icon       = \spx@faIcon[regular]{lightbulb},
-  div.seealso_title-icon   = \spx@faIcon{share},
-  div.todo_title-icon      = \spx@faIcon{pen},
-  div.important_title-icon = \spx@faIcon{pause-circle},
-  div.caution_title-icon   = \spx@faIcon{radiation},
-  div.warning_title-icon   = \spx@faIcon{exclamation-triangle},
-  div.attention_title-icon = \spx@faIcon{exclamation-triangle},
-  div.danger_title-icon    = \spx@faIcon{radiation},
-  div.error_title-icon     = \spx@faIcon{times-circle},
+  div.note_title-icon      = \spx@titleicon@default{note},
+  div.hint_title-icon      = \spx@titleicon@default{hint},
+  div.tip_title-icon       = \spx@titleicon@default{tip},
+  div.seealso_title-icon   = \spx@titleicon@default{seealso},
+  div.todo_title-icon      = \spx@titleicon@default{todo},
+  div.important_title-icon = \spx@titleicon@default{important},
+  div.caution_title-icon   = \spx@titleicon@default{caution},
+  div.warning_title-icon   = \spx@titleicon@default{warning},
+  div.attention_title-icon = \spx@titleicon@default{attention},
+  div.danger_title-icon    = \spx@titleicon@default{danger},
+  div.error_title-icon     = \spx@titleicon@default{error},
 % MEMO: the new at 8.1.0 defaults for contents/topic/sidebar directives
 % use no icons, they use \sphinxdotitlerow which detects automatically
 % whether title-icon key has been set or not.

sphinx/texinputs/sphinxlatexadmonitions.sty

@@ -1,7 +1,7 @@
 %% NOTICES AND ADMONITIONS
 %
 % change this info string if making any custom modification
-\ProvidesPackage{sphinxlatexadmonitions}[2024/10/11 v8.1.1 admonitions]
+\ProvidesPackage{sphinxlatexadmonitions}[2025/04/24 v8.3.0 admonitions]
 
 % Provides support for this output mark-up from Sphinx latex writer:
 %
@@ -342,8 +342,7 @@
           \textcolor{sphinx#1TtlFgColor}{%
             \@nameuse{sphinx#1TtlIcon}%
             % The next macro is located here for legacy reasons of earlier
-            % functioning of \spx@faIcon.  When fontawesome{5,}.sty both
-            % are unavailable, it (formerly) gobbled this next macro.
+            % functioning of sphinx.sty now removed \spx@faIcon macro.
             % We leave it here now although it could be moved to after
             % the closing brace.
             \sphinxtitlerowaftericonspacecmd

sphinx/texinputs/sphinxlatexstyletext.sty

@@ -1,7 +1,7 @@
 %% TEXT STYLING
 %
 % change this info string if making any custom modification
-\ProvidesPackage{sphinxlatexstyletext}[2024/07/28 v8.1.0 text styling]
+\ProvidesPackage{sphinxlatexstyletext}[2025/05/24 v8.3.0 text styling]
 
 % 7.4.0 has moved all that is related to admonitions to sphinxlatexadmonitions.sty
 % 8.1.0 has moved topic/contents/sidebar to sphinxlatexshadowbox.sty
@@ -57,7 +57,11 @@
 % reduce hyperref "Token not allowed in a PDF string" warnings on PDF builds
 \AtBeginDocument{\pdfstringdefDisableCommands{%
 % all "protected" macros possibly ending up in section titles should be here
-% TODO: examine if \sphinxhref, \sphinxurl, \sphinnolinkurl should be handled
+% next four were added so that URLs and internal links in titles can be allowed
+    \let\sphinxurl      \@firstofone
+    \let\sphinxnolinkurl\@firstofone
+    \let\sphinxhref     \@secondoftwo
+    \def\hyperref[#1]#2{#2}% for PDF bookmark to ignore #1
     \let\sphinxstyleemphasis        \@firstofone
     \let\sphinxstyleliteralemphasis \@firstofone
     \let\sphinxstylestrong          \@firstofone

sphinx/writers/latex.py

@@ -1962,7 +1962,7 @@ def visit_reference(self, node: Element) -> None:
         uri = node.get('refuri', '')
         if not uri and node.get('refid'):
             uri = '%' + self.curfilestack[-1] + '#' + node['refid']
-        if self.in_title or not uri:
+        if not uri:
             self.context.append('')
         elif uri.startswith('#'):
             # references to labels in the same document

tests/roots/test-root/markup.txt

@@ -469,3 +469,9 @@ Smart quotes
 
 .. [#] Like footnotes.
 
+
+Link in a title: `Field lists <https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#field-lists>`_
+---------------------------------------------------------------------------------------------------------------------
+
+Again: https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#field-lists
+------------------------------------------------------------------------------------------

tests/test_builders/test_build_latex.py

@@ -72,6 +72,17 @@ def compile_latex_document(app, filename='projectnamenotset.tex', docclass='manu
                 filename,
             ]
             subprocess.run(args, capture_output=True, check=True)
+            # Run a second time (if engine is pdflatex), to have a chance to
+            # detect problems caused on second LaTeX pass (for example, this
+            # is required for the TOC in PDF to show up, for internal
+            # hyperlinks to actually work).  Of course, this increases
+            # duration of test, but also its usefulness.
+            # TODO: in theory the correct way is to run Latexmk with options
+            # as configured in the Makefile and in presence of latexmkrc
+            # or latexmkjarc and also sphinx.xdy and other xindy support.
+            # And two passes are not enough except for simplest documents.
+            if app.config.latex_engine == 'pdflatex':
+                subprocess.run(args, capture_output=True, check=True)
     except OSError as exc:  # most likely the latex executable was not found
         raise pytest.skip.Exception from exc
     except CalledProcessError as exc: