Skip to content

LaTeX: add support for fontawesome6 package #13500

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 3 commits into
base: master
Choose a base branch
from
Open

LaTeX: add support for fontawesome6 package #13500

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
dd66f75
LaTeX: add support for fontawesome6 package
jfbu Apr 24, 2025
4bc4ed3
Update CHANGES for PR #13500
jfbu Apr 24, 2025
25c463d
Let user iconpackage original setting not get lost for error message
jfbu Apr 24, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions CHANGES.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,8 @@ Features added
* #13439: linkcheck: Permit warning on every redirect with
``linkcheck_allowed_redirects = {}``.
Patch by Adam Turner.
* #13500: LaTeX: add support for ``fontawesome6`` package.
Patch by Jean-François B.

Bugs fixed
----------
Expand Down
48 changes: 25 additions & 23 deletions doc/latex.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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::

Expand Down
148 changes: 87 additions & 61 deletions sphinx/texinputs/sphinx.sty
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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@[email protected]}
{\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@[email protected] 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@[email protected] 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.
Expand Down
5 changes: 2 additions & 3 deletions sphinx/texinputs/sphinxlatexadmonitions.sty
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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:
%
Expand Down Expand Up @@ -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
Expand Down
Loading