diff --git a/CHANGES.rst b/CHANGES.rst index fede8b5177b..e41993e2499 100644 --- a/CHANGES.rst +++ b/CHANGES.rst @@ -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 ---------- diff --git a/doc/latex.rst b/doc/latex.rst index fce61480941..634381d5618 100644 --- a/doc/latex.rst +++ b/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._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._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' - ` 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._title-icon`` keys. .. note:: diff --git a/sphinx/texinputs/sphinx.sty b/sphinx/texinputs/sphinx.sty index 8837485c5f7..7e06eff7de8 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}[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. diff --git a/sphinx/texinputs/sphinxlatexadmonitions.sty b/sphinx/texinputs/sphinxlatexadmonitions.sty index 0519903591b..627ee0d49ad 100644 --- a/sphinx/texinputs/sphinxlatexadmonitions.sty +++ b/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