DOCS: admonition customization

[12rambau]

Fix #1124

first draft of an extra documentation page to explain how to create a custom admonition using our theme and 1 extra extention.

That's a draft so feel free to change anything in the text, I'm not the best when it comes to explain stuff.

[drammock]

I reworked the new docs page a bit. I think the prose flow is better now, but I also did a bold move that maybe you won't like: I removed all the repetition between the rendered admonitions and the code examples. Now, the code examples are auto-inserted using .. include:: with :start-after: and :end-before: tags to insert parts of the file back into itself. Same strategy is used to insert the actual CSS rules into the CSS tabs. This mostly works as expected, and is IMO better because there's no risk of the rendered admonition and the example code becoming out-of-sync. The problems:

1. there is an (unavoidable?) newline at the start of the rST example code blocks.
2. the syntax highlighting is wrong because when using .. include it apparently doesn't parse the input, even if you specify :code: css or :code: rst or whatever. As a result, the relevant div gets a highlight-default class instead of highlight-css or highlight-rst.
   • You'll see that I tried to hack it to add this class, but that didn't work either because (1) the highlight-default class comes later in the class list, and (2) because the code wasn't parsed as CSS, the pygments inline span classes are wrong/simplified.

I'm 50/50 on whether the advantages outweigh the disadvantages here. WDYT?

[drammock]

Here's the relevant page: https://pydata-sphinx-theme--1155.org.readthedocs.build/en/1155/user_guide/extending.html

[12rambau]

Thank you very much for revamping everything, the new wording is way better. I love the way you're using incude. For rst that's not a problem at all but css is barely readable. let's give us 1-2 days to find a solution and if it's not possible we can still go back to hard coding them.

[drammock]

OK I think this is not anything we can fix, it needs upstream. Here is the MWE:

https://dan.mccloy.info/data/sphinx-include-highlight-mwe/

and the rST source of that page:

https://dan.mccloy.info/data/sphinx-include-highlight-mwe/_sources/index.rst.txt

[drammock]

crossref to upstream bug report: sphinx-doc/sphinx#11185

[drammock]

@12rambau any reason you picked f26c here instead of f167?

[12rambau]

yes, the youtube icon is a brand icon, if you want to use it you also need to customize the font-family from "Font Awesome 6 Free" to "Font Awesome 6 Brands".

[drammock]

Ah ok, so the brand icons don't work easily in an admonition? I didn't realize that.

[12rambau]

nope it doesn't, I saw it, tried to find an easy fix and realize we need to update fa font management first so I keep it in my mind and if someone complains about it I'll work on it but that's low priority I think

[choldgraf]

This looks great, IMO we should get it merged because it is a helpful improvement even if there are still things to improve!

One quick comment in there about a little sphinx package I wrote that might be useful...but I don't think it needs to block

[choldgraf]

I actually created a tiny little sphinx extension to show off syntax examples, maybe it would be useful here?

https://ebp-sphinx-examples.readthedocs.io/en/latest/

It gives you an example directive like:

```{example}
**foo**
```

And it create a little preview + the raw syntax to show how to make the preview.

[12rambau]

that would be perfect but you can't display 2 files yet right (like in these examples css + rst) ?

I will merge it and we'll see how to use it in the upcoming future