[LaTeX] Revamped styling of all admonitions, with addition of a title row with icon

[jfbu]

Subject: The aim is to let Sphinx PDF output via LaTeX use as default for all admonitions (inclusive of seealso) similar styling as used at https://www.sphinx-doc.org/ for HTML output of our own docs.

Feature or Bugfix

• Feature

Relates

• [docs] add icons to admonition titles #12486, DOC: Improve internal sphinx13 style #12439

A few on-the-side things need to be mentioned:

• the xcolor LaTeX package is now required ; I have trimmed old annoying branches which tried to allow using only color package. Anyhow we required texlive-latex-recommended and this includes xcolor.
• for the icons the fontawesome5 LaTeX package is needed. If not available no build error, but a LaTeX warning. On Ubuntu texlive-fonts-extra must be installed.
• some under-the-hood refactoring which however should not break any project.

Examples of output in PDF:

edit beware that the screenshots here are not fully up-to-date anymore as later commits (now squashed) modified some icons, and set the style at page breaks to "slice", whereas here it was still "clone". Also, padding settings changed. But colours have not been modified and are still the ones displayed here. Scroll further down to latest comments to see updated screenshots.

The colours for the titles (background colour and icon colour) should be exactly the same as the ones from sphinx13.css but the colour and widths of the borders were chosen independently.

Note: current implementation of sphinx.ext.todo means we can not yet style the TODO notes especially (they are rendered as "note" admonitions with a modified title that's all). It will be easier to address this in sphinx.ext.todo in a second stage, once this is merged.

First example

Second Example

Third Example with a pagebreak

Fourth Example

Last Example (beware that choices for icons have evolved, scroll down for up-to-date screenshots)

[jfbu]

@AA-Turner I tied this to 7.4.0 because it does strengthen a bit the requirements on LaTeX installations, because a package is needed to access the icons. Of course it can be merged earlier. But then all 7.4.0 strings should be updated. (in sphinxpackageboxes.sty there is one location where I wrote 6.4.0 by mistake).

[jfbu]

The mypy linting failures which have surfaced at third commit have nothing to do with this PR. The linting was successful at second commit (on prior day) and the third commit is only a refactoring of LaTeX code.

Linting failures from type-docutils 0.21.0.20240704 having been released.

See #12510

[jfbu]

Here and below lines I really imitated #12486 sphinx13.css which results in grouped choices for foreground and background according to categories "note", "success", "warning", "error". I could not take care of "todo" because the todo extension produces LaTeX markup which amalgamates with "note".

[jfbu]

I have modified choices for default associated icons. Also, no warning is emitted if fontawesome5 is not found (because doing so requires adding logic to not emit a warning if the user has made usage of the -title-icon keys to employ some LaTeX code of their own). And in absence of fontawesome5, the default admonition titles thus lacking icons inhibit the space supposed to separate the icon from the title text.

Here is the new rendering (please make suggestions if you feel so!):

Also, at page breaks, the default now adopts a "slice" style for box-decoration-break:

and

[jfbu]

Variant "regular" of the light bulb for tip/hint.

NOTE: all these boxes can display a "shadow"

[chrisjsewell]

Haven't had time to review yet, but like it in principle btw cheers 👍

[picnixz]

I haven't looked at the actual changes, but I remember that I had some issues with fontawesome5. If the package is not available for the texlive distribution, is fontawesome sufficient?

[jfbu]

I haven't looked at the actual changes, but I remember that I had some issues with fontawesome5. If the package is not available for the texlive distribution, is fontawesome sufficient?

@picnixz It is only partly sufficient in the current state of this PR:

  div.note_title-icon      = \spx@faIcon{info-circle},
  div.hint_title-icon      = \spx@faIcon[regular]{lightbulb}, NOT OK
  div.tip_title-icon       = \spx@faIcon[regular]{lightbulb}, NOT OK
  div.seealso_title-icon   = \spx@faIcon{share},
  div.important_title-icon = \spx@faIcon{pause-circle},
  div.caution_title-icon   = \spx@faIcon{radiation}, NOT OK
  div.warning_title-icon   = \spx@faIcon{exclamation-triangle},
  div.attention_title-icon = \spx@faIcon{exclamation-triangle},
  div.danger_title-icon    = \spx@faIcon{radiation}, NOT OK
  div.error_title-icon     = \spx@faIcon{skull-crossbones}, NOT OK

I have marked with NOT OK those names which fontawesome does not recognize and thus in this case there empty output. I guess I should go the extra effort to add a specific "fontawesome but not fontawesome5" handling ;-)

I wasn't sure about context because I only work with latest TeXLive and I checked fontawesome5 already was there in TL2019. I will add the extra effort mentioned in previous paragraph...

[picnixz]

I wasn't sure about context because I only work with latest TeXLive and I checked fontawesome5 already was there in TL2019

Actually, the issues I had were because I was using texlive-2017 and because I was still using an old distribution (so it was an EOL distribution). I could still make it work in general with most packages but if maybe ask for a minimal texlive version distribution (I think 2019 should be sufficient for most users, and if you say that fa5 was present in 2019 then it should be fine).

[jfbu]

@picnixz Thanks a lot for such feedback. I do have Tl2012 to 2019 but not on my current computer (and will be only one for some time) so did not check that far back in time. I will add a complete configuration with fontawesome, but can only test it with the TL2019 version of that package...

[picnixz]

If you think it's too much, maybe we can just ask users to use TL2019+. It would simplify the code base (and your life I think).

[jfbu]

If you think it's too much, maybe we can just ask users to use TL2019+. It would simplify the code base (and your life I think).

We currently say:

PDF builds need a sufficiently complete LaTeX installation. The testing is currently (since 5.3.0) done on Ubuntu 22.04LTS, whose LaTeX distribution matches upstream TeXLive 2021 as of 2022/02/04, but PDF builds can be successfully done on much older LaTeX installations.

It is not too much here for me to try to support fontawesome as fall-back, although I still have to check if I find some other name for skull-crossbones or if it is really absent and I have to pick another icon, or perhaps in the end use always times-circle as is done in sphinx13.css svg icon.

[picnixz]

Ah yes, we say "can be successfully done on much older LaTeX installations". So maybe add "except for some icons that require TeXLive 2019". I prefer the ❌ if possible because I know people that have some issues with skulls and I think it's better to have neutral icons for them.

For the light bulb, it's under \faLightbulbO. To replace 'radiation', \faBolt or \faExclamationCircle could be an alternative though the second could be confusing with the warning (furo uses the bolt for danger/caution IIRC).

[jfbu]

Ah yes, we say "can be successfully done on much older LaTeX installations". So maybe add "except for some icons that require TeXLive 2019".

Would it be acceptable to say that some icons may render differently in earlier TL? Only the radiation is causing me problem at this time.

I prefer the ❌ if possible because I know people that have some issues with skulls and I think it's better to have neutral icons for them.

Ok, I don't have strong opinion so I propose times-circle which is available in both fontawesome and fontawesome5.

For the light bulb, it's under \faLightbulbO.

Yes, seen.

To replace 'radiation', \faBolt or \faExclamationCircle could be an alternative though the second could be confusing with the warning (furo uses the bolt for danger/caution IIRC).

I was considering \faWarning which seems to be the same as exclamantion-triangle my PR currently uses for warning and attention. I went through most fontawesome and did not see many candidates. Perhaps \faBolt indeed...

[picnixz]

Would it be acceptable to say that some icons may render differently in earlier TL?

I think it's definitely fine. I don't think we need to reinvent the wheel for that and if people are really not happy with the default rendering, they can always redefine the corresponding symbol I think.

Ok, I don't have strong opinion so I propose times-circle which is available in both fontawesome and fontawesome5.

It's a better one indeed!

[jfbu]

@picnixz I have added fontawesome support. Here is how it renders with fontawesome:

With fontawesome5 it renders as:

so the sole significant difference is use of "bolt" with fontawesome, as it does not have the fontawesome5 "radiation".

If neither is found, the titles will have no icons (and be shifted to start of line).

Full customization is possible, see the docs in latex.rst. (ratio of doc time to coding time being circa 10 to 1).

In checking this with TeXLive2019 I have hit against an unrelated matter which strangely shifts the title rows downwards in the admonition boxes. I will investigate later.

[jfbu]

I have understood why on testing my code on old LaTeX there was suddenly a gap above the colored title rows, a gap that does not show in above screenshots.

With LaTeX of June 2023 (I think) a longstanding issue was fixed about "parskip" vertical glue in minipages. And the gap above is such an instance ¹. I did not see it in my testing because I was using recent LaTeX.

I will push a commit which will remove the gap seen above when compiling with LaTeX earlier than June 2023.

Footnotes

1. well, the full truth is a bit complex. The vertical space issue applies potentially to all "vertical boxes" not only to LaTeX minipages. No real minipage environment is used in our context, but some booleans are set which tell LaTeX we are in a minipage... this activates the LaTeX 2023-06-01 hack at start of paragraphs to undo the vertical space. ↩

[jfbu]

squashed and rebased on current master to get mypy linting pass

[jfbu]

Let me describe the logic for icon support:

• If LaTeX package fontawesome5 is available, use it,
• else if LaTeX package fontawesome is available, use it (with slightly different icon choices),
• else drop silently attempts to include icons in admonition titles and suppress the space separating them from the title.

In all cases, user can employ 'sphinxsetup' keys of the type div.note_title-icon to specify arbitrary code to be used (a priori, to draw an icon, at any rate it will be executed at start of title row).

(I know 'sphinxsetup' may feel a bit inconvenient, because we use it for LaTeX syntax key=value, whereas it is itself a Python key in the latex_elements dict, but its existence has allowed avoiding accumulating in latex_elements dozens of additional keys)

Use 'sphinxsetup': 'iconpackage=none', in latex_elements to prevent usage of fontawesome5 and fontawesome even if present. Or use it with iconpackage=fontawesome if you don't want fontawesome5 even if available but only fontawesome LaTeX package. Use it with iconpackage=somepackage if you want to use some other LaTeX package but then you must define the div.<type>_title-icon key values. Those left undefined will simply cancel the icon (they will not use the fontawesome5 icon, as fontawesome5 will not be loaded).

Can one create a build error depending on available packages with the above? Only on purpose. If you do

latex_elements = {
    'sphinxsetup': 'iconpackage=fontawesome',
    'preamble': r'\usepackage{fontawesome5}',
}

forcing the loading of both packages, then fontawesome5 crashes the build:

! Package fontawesome5 Error: Incompatible version of Font Awesome already
(fontawesome5)                loaded

But for normal use, the most probable and unique cause of a crash with this PR user interface will be to set up faulty LaTeX code as the values of the div.<type>_title-icon LaTeX keys for 'sphinxsetup'.

What does this PR do?

• since 5.1.0 for warning type (aka "heavy") admonitions and 6.2.0 for note type (aka "light") admonitions it has been possible to use background colours, rounded corners, and shadows.
• but so far the default have been left to the rather boring legacy rendering: light admonitions with a horizontal line above and below, heavy admonitions with a frame, no background color, no border color, no rounded corners, no shadows
• this PR uses a background colour in all cases, rounded corners for light admonitions, and coloured borders. It does not use shadows,
• also this PR adds a special internal LaTeX macro to produce a "title-row" with a background colour, an icon at start, and a foreground colour (which applies only to the icon).

Let me conclude by mentioning that since a very long time, since Sphinx 1.5 actually:

• latex, public names for environments and parameters used by note, warning,
  and other admonition types, allowing full customizability from the
  'preamble' key or an input file (ref: feature request Feature request: Adjustable colour/thickness of border/rule in latex admonitions #2674, latex: fully customizable notices/admonitions #2685)

all admonitions (except seealso which was added later) have in LaTeX associated environments: sphinxnote, sphinxhint, sphinxdanger, etc... and the user can redefine these environments to do whatever is desired, for example use the package tcolorbox syntax. This is very simple and requires moderate LaTeX skills: knowing how to define an environment with one argument (the title).

We don't use tcolorbox at Sphinx core, because it would slow down considerably the build time, and Sphinx core LaTeX is able for some years to produce itself colourful boxes via a much more lightweight approach based on pict2e and ellipse package (for elliptical corners if desired).

So far these capacities remained under-exploited, the aim of this PR is to use them as default.

[picnixz]

We don't use tcolorbox at Sphinx core, because it would slow down considerably the build time

I like this one and don't want to ever use tcolorbox (just using tikz-based rendering would slow a process that may already be slow enough in general).

I have some comments now on the colors being used for the borders. It feels that some of the reds are too extreme (especially for ERROR) or that the borders are a bit too large by default (I think the border could be 50% or 75% of what it is now for the error/warn boxes). Maybe we can ask theme maintainers about what they would suggest (I don't want to ping them yet)?

[jfbu]

I have some comments now on the colors being used for the borders. It feels that some of the reds are too extreme (especially for ERROR) or that the borders are a bit too large by default (I think the border could be 50% or 75% of what it is now for the error/warn boxes).

This was a quick on-the-moment decision a bit influenced by some experiments I had done on a third-party large project using Sphinx. I am completely open to any other choices.

Here is what is done now for warning type borders (warning-type = warning, caution, attention, danger and error):

• border-widths are set (except for error) to1.5pt. They used to be at 1pt. The light admonitions (note, hint, etc...) use 0.5pt. (by the way we can specify 4 distinct border-widths, top, left, bottom, right)
• error has thicker borders at 2pt.
• border colour is the same for all: #940000
  except error which got a full #ff0000
  . What is actually the use-case of error directive? I have never used it myself.

Perhaps I should revert the s/1pt/1.5pt/ and not handle error type especially?
If reverting, padding should be increased to keep a constant 12.5pt value of border-width plus horizontal padding. There is no necessity to do that but I like having all admonition texts look exactly vertically aligned across various types, for example if you issue in succession important, caution and tip notices.

Other questions

• keep straight corners for warning-type admonitions? I did that to let them look more martial.
• we support ellipitical corners, use them by default to show-off?
• use some (a priori external, but inset is possible) shadows for light or heavy admonitions?

I must point out also my somewhat cavalier choice of icons. Our sphinx13.css seems to derive from furo theme some choices but I changed that in part, for example using "pause" symbol for important.

Maybe we can ask theme maintainers about what they would suggest (I don't want to ping them yet)?

Any advice is welcome! My not-really-informed impression is that people are not so much worried about how PDF look, and the vast majority of Sphinx users care mostly for HTML/ePub output. And PDF pages all have a priori a white color background which is not the case of most HTML themes.

[jfbu]

@picnixz Reagrding todos, Furo theme, and Alabaster, use a kind of gray and Pydata theme some violet very similar to the choices from sphinx13.css. RTD uses some orange. Not all themes I tried style especially todos, as really distinct from other admonitions.

Furo:

Pydata:

RTD:

The RTD theme uses white for text, for which there is no config in the present PR for PDF output. Anyhow to my eye (which has problems) this is bit blurry contrast.

Book:

Press:

---

Not finding yet apart from RTD a yellowish rendering among themes I checked, I do not change the setting but any suggestion is welcome.

I changed the border-widths, reverting to previously used 1pt for strong admonitions, and slightly thicker 1.25pt for error. The error border colour was changed.

Here is how it looks:

[jfbu]

@picnixz I misread your comment thinking a priori you were referring to #12543 but you did mention colors so it is indeed #12508. I added to the discussion some snapshots of various theme renderings for TODOs but did not do similar search for admonitions.

[picnixz]

I like those new colors. A final remark I could say is that Caution/Danger should be redder than Warning/Attention but less red than error (ranked in terms of importance IMO). Is it possible to reduce a bit the red of the error symbol actually? While the contrast is strong (and it should be), I feel it should be a little less.

Also, in the other themes, the internal padding seems a bit smaller (symbols are much closer to the margin) so maybe we can also reduce the left padding? I don't know its current value but maybe by we can make it 50% of its current value (or 30% to keep a bit of space still).

[jfbu]

I like those new colors. A final remark I could say is that Caution/Danger should be redder than Warning/Attention but less red than error (ranked in terms of importance IMO).

I don't disagree, but the pairs Caution/Warning on one side and Danger/Attention on the other sides were simply copied over from our own sphinx13.css (in doc/_themes/sphinx13/static). Except if I made a mistake.

Is it possible to reduce a bit the red of the error symbol actually? While the contrast is strong (and it should be), I feel it should be a little less.

Absolutely. I completely forgot to update it.

Also, in the other themes, the internal padding seems a bit smaller (symbols are much closer to the margin) so maybe we can also reduce the left padding? I don't know its current value but maybe by we can make it 50% of its current value (or 30% to keep a bit of space still).

I have no issue with that. In HTML themes some align the text with the symbol as I do in PDF, others align it with the title. I think it is better as it is now. I liked the increased padding but no strong opinion, and it is only a default, theoretically easily overriden as per our docs.

[jfbu]

The rationale for the padding is to avoid a too large discrepancy between on one hand the distance from the symbol to the left margin (aka padding) and the distance from the symbol to the title on its right. I will push a change which reduces both.

[jfbu]

Here is with reduced horizontal padding and the error symbol color.

[picnixz]

Personally, I like the colors! @AA-Turner do you have some personal comments on this change as well?

[chrisjsewell]

Yeh looks all good to me

On a related note, would love to see a more "simple" css-like way to modify stylings of pdfs (as mentioned in the documentation below)

Would also be interested if https://typst.app/ (https://github.com/typst/typst) integration with sphinx could make pdf creation not such a horrible experience 😅

[AA-Turner]

Thanks all!

A

[jfbu]

@chrisjsewell

On a related note, would love to see a more "simple" css-like way to modify stylings of pdfs (as mentioned in the documentation below)

I would too! I think it would be a nice job for an extension to pick up the HTML theme selected by conf.py, analyze all CSS files and extract from it the data which latex_elements['sphinxsetup'] can understand. It does not look to me like a minor task, as CSS is so versatile... ¹ What Sphinx LaTeX currently can understand is explained in the section of the docs you mention. Some of the CSS-alike named options also have legacy names, which are described earlier. But I think it is easier especially for an automated approach to use the CSS-alike named options which now with this PR also apply to seealso and todo directives.

Would also be interested if https://typst.app/ (https://github.com/typst/typst) integration with sphinx could make pdf creation not such a horrible experience 😅

LaTeX is notoriously complex due to the fact that core functionalities only arise from packages, some of them unmaintained, sometimes conflict exist etc...

I know nothing about it but ConTeXt, and now LuaMetaTeX are powerful. Also there is now a lean OpTeX which uses LuaLateX. All of these things suffer certainly from the same situation with LaTeX: very few people actually master (really) the underlying TeX concepts and language.

I hope though that producing PDF from Sphinx via LaTeX is not so much horrible since basically the sole setting really needed is perhaps to set latex_engine to 'luatex' or 'xelatex' for Unicode: but then we enter the somewhat horrible world indeed of font loading, as conventions between the two Unicode engines differ about that, and we hit the main core problem being that LaTeX does not have a "fall-back" for fonts. A very good thing about LuaLaTeX is that it does offers fall-back mechanism, but still one has to configure it.

Footnotes

1. Perhaps the simpler solution is a kind of collections of human made translations of the major themes... ↩

[jfbu]

This closed #10620.

[jfbu]

This closed #8807.