LaTeX: support for using the fontawesome7 LaTeX package (#13805)

doc/latex.rst

@@ -1007,13 +1007,14 @@ The color used in the above example is available from having passed the
 ``iconpackage``
 
     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
+    titles.  Its default is set dynamically to either ``fontawesome7``,
+    ``fontawesome6``,
+    ``fontawesome5``, ``fontawesome``, or ``none``, in decreasing order of
+    priority and 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
+    code will use ``\faIcon`` command if with ``fontawesome5-7`` 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``.
+    "radiation", which is only found in ``fontawesome5-7``.
     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
@@ -1413,16 +1414,16 @@ The next keys, for admonitions, :dudir:`topic`, contents_, and
 
 - ``div.<type>_title-icon``: the LaTeX code responsible for producing the
   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
+  the ``\faIcon`` LaTeX command if one of ``fontawesome5``, ``6`` or ``7`` is
+  on your LaTeX installation.  For example the default for :dudir:`note` is
+  ``div.note_title-icon=\faIcon{info-circle}`` with ``fontawesome5`` but
+  ``div.note_title-icon=\faIcon{circle-info}`` with ``fontawesome7`` (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.
+  (not ``\faIcon``) in order to modify the choice of icons.  The
+  ``iconpackage`` key can give the name of some other package providing icons.
+  You must then configure the ``div.<type>_title-icon`` keys to use the LaTeX
+  commands from that custom icon package.
 
 .. note::
 

sphinx/texinputs/sphinx.sty

@@ -9,7 +9,7 @@
 % by the Sphinx LaTeX writer.
 
 \NeedsTeXFormat{LaTeX2e}[1995/12/01]
-\ProvidesPackage{sphinx}[2025/04/24 v8.3.0 Sphinx LaTeX package (sphinx-doc)]
+\ProvidesPackage{sphinx}[2025/08/03 v8.3.0 Sphinx LaTeX package (sphinx-doc)]
 
 % provides \ltx@ifundefined
 % (many packages load ltxcmds: graphicx does for pdftex and lualatex but
@@ -870,32 +870,43 @@
 
 % 7.4.0 Support for icons in admonition titles
 %
-% 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
+% We let Sphinx use, listed in order of priority:
+% - a user-specified package via iconpackage key,
+% - fontawesome7 (supported since 8.3.0),
+% - fontawesome6 (supported since 8.3.0),
+% - fontawesome5,
+% - fontawesome, 
+% - or nothing at all, and then icons are not drawn.
+% 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
+% We can't load fontawesome7 (or 6 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}%
+% only set the default value of iconpackage key.
+\IfFileExists{fontawesome7.sty}{%
+  \DeclareStringOption[fontawesome7]{iconpackage}%
 }%
 {%
- \IfFileExists{fontawesome5.sty}{%
-   \DeclareStringOption[fontawesome5]{iconpackage}%
- }%
- {%
-  \IfFileExists{fontawesome.sty}
-  {\DeclareStringOption[fontawesome]{iconpackage}}
-  {\DeclareStringOption[none]{iconpackage}}%
- }%
+  \IfFileExists{fontawesome6.sty}{%
+    \DeclareStringOption[fontawesome6]{iconpackage}%
+  }%
+  {%
+   \IfFileExists{fontawesome5.sty}{%
+     \DeclareStringOption[fontawesome5]{iconpackage}%
+   }%
+   {%
+    \IfFileExists{fontawesome.sty}
+    {\DeclareStringOption[fontawesome]{iconpackage}}
+    {\DeclareStringOption[none]{iconpackage}}%
+   }%
+  }%
 }%
-% 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...
+% Unfortunately icon macro names are not the same across fontawesome,
+% fontawesome5, fontawesome6  and fontawesome7 LaTeX packages.
+% At 8.3.0 we refactor the
+% icon support code into something easier to maintain in future in case of a
+% fontawesome8, 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
@@ -918,7 +929,12 @@
 }
 
 % Icon defaults depending on package used.
-% Attention! no extra spaces for alignment when using \@namedef!
+% Attention! no extra spaces (to align here) when using \@namedef!
+
+% MEMO: the [regular] style mark-up for {lightbulb} was inherited
+% from fontawesome5 and found experimentally to work also with
+% fontawesome6 (and fontawesome7) despite their respective PDF docs
+% not mentioning it...
 \@namedef{spx@fontawesome6@note}{\faIcon{circle-info}}
 \@namedef{spx@fontawesome6@hint}{\faIcon[regular]{lightbulb}}
 \@namedef{spx@fontawesome6@tip}{\faIcon[regular]{lightbulb}}
@@ -931,6 +947,13 @@
 \@namedef{spx@fontawesome6@danger}{\faIcon{radiation}}
 \@namedef{spx@fontawesome6@error}{\faIcon{circle-xmark}}
 
+% Turns out that fontawesome7 commands for our target icons are
+% same as with fontawesome6.  So make a loop to spare a few lines here.
+\@for\x:=note,hint,tip,seealso,todo,important,caution,warning,attention,%
+         danger,error%
+\do{\expandafter\let\csname spx@fontawesome7@\x\expandafter\endcsname
+                    \csname spx@fontawesome6@\x\endcsname}
+
 \@namedef{spx@fontawesome5@note}{\faIcon{info-circle}}
 \@namedef{spx@fontawesome5@hint}{\faIcon[regular]{lightbulb}}
 \@namedef{spx@fontawesome5@tip}{\faIcon[regular]{lightbulb}}