fix: use consistent markup in examples

[12rambau]

WIP

Fix #1366

Try to replace all the occurence of markup example and replace them with a tab:

• https://pydata-sphinx-theme.readthedocs.io/en/stable/user_guide/theme-elements.html
• https://pydata-sphinx-theme.readthedocs.io/en/latest/user_guide/extending.html
• https://pydata-sphinx-theme.readthedocs.io/en/latest/user_guide/light-dark.html
• https://pydata-sphinx-theme.readthedocs.io/en/latest/user_guide/static_assets.html
• https://pydata-sphinx-theme.readthedocs.io/en/latest/community/topics/page-metadata.html

[12rambau]

@choldgraf I think I identified all the pages with markup example. To check how it looks, I tested on 1 page and the prettier pre-commit is refactoring the tab directive with "````". As you have more experience with md. could you advise what's happening ?

I'm writing the following and there seems to be conflicts between "```". What should I do ?

```{tab-set}
```{tab-item} rst
```rst
.. code-block:: python
    :caption: python.py

    print("A code block with a caption.")
```
```
```{tab-item} markdown
```md
```{code-block} python
:caption: python.py

print("A code block with a caption.")
```
```
```
```

[12rambau]

I finally followed instructions from here: https://myst-parser.readthedocs.io/en/latest/syntax/roles-and-directives.html#nesting-directives. That's very dificult to read but that works.

[choldgraf]

Yep this is the right way to do it. If you want to I believe that you can indent everything within the directive just to make it easier to read.

[drammock]

FYI indentation does not work (which is a shame because it does help readability of the source). It yields

  File "/opt/mambaforge/envs/pst/lib/python3.11/site-packages/sphinx_design/tabs.py", line 243, in run
    tab_label, tab_content = tab_item.children
    ^^^^^^^^^^^^^^^^^^^^^^
ValueError: not enough values to unpack (expected 2, got 1)

[12rambau]

Now that I get I think we can leave it as it is

[choldgraf]

I don't have time to go through this in a lot of detail, but in general it looks good to me and I'm +1 on merging this and then making gradual improvements from there because I think it's a clear improvement!

[drammock]

argh, was in the middle of reviewing this. I'll open a new PR with the fixes I guess.

[drammock]

I'll submit the changes I had queued up in a separate PR

[drammock]

FYI indentation does not work (which is a shame because it does help readability of the source). It yields

  File "/opt/mambaforge/envs/pst/lib/python3.11/site-packages/sphinx_design/tabs.py", line 243, in run
    tab_label, tab_content = tab_item.children
    ^^^^^^^^^^^^^^^^^^^^^^
ValueError: not enough values to unpack (expected 2, got 1)

[12rambau]

argh, was in the middle of reviewing this. I'll open a new PR with the fixes I guess.

oupsss sorry