diff --git a/doc/latex.rst b/doc/latex.rst index bfc4de7393..30aa8c23f9 100644 --- a/doc/latex.rst +++ b/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._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._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._title-icon`` keys to use the LaTeX + commands from that custom icon package. .. note:: diff --git a/sphinx/texinputs/sphinx.sty b/sphinx/texinputs/sphinx.sty index 7e06eff7de..ded8666be0 100644 --- a/sphinx/texinputs/sphinx.sty +++ b/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}}