Adding warning icon to warning admonitions?

Adding warning icon to warning admonitions?

[Bagas Sanjaya]

[-- Attachment #1: Type: text/plain, Size: 2775 bytes --]

Hi,

On my head, I'm often thinking about adding warning icon (more specifically,
circle exclamation) to warning admonition blocks. The idea is inspired by
content safety disclaimers as seen on TikTok (TT) (for example and FYI,
racing-themed contents there like [1] are more likely to get what I called
"pro-only" admonition that literally says `The actions in this video are
performed by professionals or supervised by professionals. Do not attempt.`)

From above inspiration, I'd like to make the warning admonition block from
currently:

```
+----------------------------------------------------------------------------+
|   Warning:                                                                 |
|                                                                            |
|   Function foo() can produce undefined behavior. Either sanitize           |
|   arguments being passed, or use the safer abstraction foo_wrapper().      |
+----------------------------------------------------------------------------+
```

into:

```
+----------------------------------------------------------------------------+
|   (!) Warning:                                                             |
|                                                                            |
|       Function foo() can produce undefined behaivor. Either sanitize       |
|       arguments being passed, or use the safer abstraction foo_wrapper().  |
+----------------------------------------------------------------------------+
```

or even to match TT:

```
+----------------------------------------------------------------------------+
|   (!) Function foo() can produce undefined behavior. Either sanitize       |
|       arguments being passed, or use the safer abstraction foo_wrapper().  |
+----------------------------------------------------------------------------+
```

In other words, the admonition text should be indented after the warning icon.

For the icon itself, the approach is to use Font Awesome [2] (many other doc
sites that uses Sphinx also do that due to site theme they use but Alabaster
theme don't use the icon, hence this question). I personally prefer regular
icon variant (like in TT), but alas it is in non-free PRO plan (and only
solid variant is free and that is what Sphinx themes using).

Does adding warning icon like above idea make sense for the kernel docs? And
does it require non-trivial (complex) changes to Alabaster theme?

Thanks.

[1]: https://www.tiktok.com/@supercars/video/7301916055063088392?is_from_webapp=1&sender_device=pc&web_id=7320595371066557959
[2]: https://fontawesome.com/icons/circle-exclamation?f=classic&s=solid

-- 
An old man doll... just what I always wanted! - Clara

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 228 bytes --]

Re: Adding warning icon to warning admonitions?

[Jonathan Corbet]

Bagas Sanjaya <bagasdotme@gmail.com> writes:

> For the icon itself, the approach is to use Font Awesome [2] (many other doc
> sites that uses Sphinx also do that due to site theme they use but Alabaster
> theme don't use the icon, hence this question). I personally prefer regular
> icon variant (like in TT), but alas it is in non-free PRO plan (and only
> solid variant is free and that is what Sphinx themes using).
>
> Does adding warning icon like above idea make sense for the kernel docs? And
> does it require non-trivial (complex) changes to Alabaster theme?

It can probably be done with a bit of CSS tweaking.  I don't really like
the idea of requiring the installation of another font to build the
docs, though, and Font Awesome looks like it could bring in licensing
issues of its own - that's not clear from the site at all.

jon

Re: Adding warning icon to warning admonitions?

[Vegard Nossum]

On 05/01/2024 15:59, Jonathan Corbet wrote:
> Bagas Sanjaya <bagasdotme@gmail.com> writes:
> 
>> For the icon itself, the approach is to use Font Awesome [2] (many other doc
>> sites that uses Sphinx also do that due to site theme they use but Alabaster
>> theme don't use the icon, hence this question). I personally prefer regular
>> icon variant (like in TT), but alas it is in non-free PRO plan (and only
>> solid variant is free and that is what Sphinx themes using).
>>
>> Does adding warning icon like above idea make sense for the kernel docs? And
>> does it require non-trivial (complex) changes to Alabaster theme?
> 
> It can probably be done with a bit of CSS tweaking.  I don't really like
> the idea of requiring the installation of another font to build the
> docs, though, and Font Awesome looks like it could bring in licensing
> issues of its own - that's not clear from the site at all.

You could use the unicode symbol as a replacement for the graphic by
adding something like this to custom.css:

div.admonition.warning p.admonition-title::before {
         content: "\26A0";
         font-weight: bold;
         font-size: 120%;
         padding-right: 8px;
         float: left;
}

It doesn't look great to me, but maybe with some additional tweaking it
could (e.g. text-stroke property, sizing, positioning, etc.).


Vegard

Re: Adding warning icon to warning admonitions?

[Bagas Sanjaya]

[-- Attachment #1: Type: text/plain, Size: 1028 bytes --]

On Fri, Jan 05, 2024 at 07:59:09AM -0700, Jonathan Corbet wrote:
> Bagas Sanjaya <bagasdotme@gmail.com> writes:
> 
> > For the icon itself, the approach is to use Font Awesome [2] (many other doc
> > sites that uses Sphinx also do that due to site theme they use but Alabaster
> > theme don't use the icon, hence this question). I personally prefer regular
> > icon variant (like in TT), but alas it is in non-free PRO plan (and only
> > solid variant is free and that is what Sphinx themes using).
> >
> > Does adding warning icon like above idea make sense for the kernel docs? And
> > does it require non-trivial (complex) changes to Alabaster theme?
> 
> It can probably be done with a bit of CSS tweaking.  I don't really like
> the idea of requiring the installation of another font to build the
> docs, though, and Font Awesome looks like it could bring in licensing
> issues of its own - that's not clear from the site at all.

OK, thanks!

-- 
An old man doll... just what I always wanted! - Clara

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 228 bytes --]

Re: Adding warning icon to warning admonitions?

[Bagas Sanjaya]

[-- Attachment #1: Type: text/plain, Size: 1587 bytes --]

On Fri, Jan 05, 2024 at 07:12:10PM +0100, Vegard Nossum wrote:
> 
> On 05/01/2024 15:59, Jonathan Corbet wrote:
> > Bagas Sanjaya <bagasdotme@gmail.com> writes:
> > 
> > > For the icon itself, the approach is to use Font Awesome [2] (many other doc
> > > sites that uses Sphinx also do that due to site theme they use but Alabaster
> > > theme don't use the icon, hence this question). I personally prefer regular
> > > icon variant (like in TT), but alas it is in non-free PRO plan (and only
> > > solid variant is free and that is what Sphinx themes using).
> > > 
> > > Does adding warning icon like above idea make sense for the kernel docs? And
> > > does it require non-trivial (complex) changes to Alabaster theme?
> > 
> > It can probably be done with a bit of CSS tweaking.  I don't really like
> > the idea of requiring the installation of another font to build the
> > docs, though, and Font Awesome looks like it could bring in licensing
> > issues of its own - that's not clear from the site at all.
> 
> You could use the unicode symbol as a replacement for the graphic by
> adding something like this to custom.css:
> 
> div.admonition.warning p.admonition-title::before {
>         content: "\26A0";
>         font-weight: bold;
>         font-size: 120%;
>         padding-right: 8px;
>         float: left;
> }
> 
> It doesn't look great to me, but maybe with some additional tweaking it
> could (e.g. text-stroke property, sizing, positioning, etc.).

Thanks for the tip!

-- 
An old man doll... just what I always wanted! - Clara

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 228 bytes --]