LaTeX: add support for fontawesome6 package

Author: jfbu

doc/latex.rst

@@ -1006,18 +1006,19 @@ 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 +1411,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
@@ -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,105 @@
 }
 
 % 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}{%
+          \sphinxbuildwarning{badiconpackage}%
+          \PackageWarningNoLine{sphinx}{%
             You have set iconpackage=\spx@opt@iconpackage\MessageBreak
             But \spx@opt@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