[Migration tooling] Blocks

[bmorelli25]

Summary

A block admonition is converted to MyST admonition block directive. If the admonition has a title, then the {admonition} directive is used. The type of the admonition is passed as the class attribute.

admonition_type: NOTE | TIP | IMPORTANT | CAUTION | WARNING
Other classes can also be added to the class attribute. For example, if [%collapsible] option is specified for the admonition block, then “dropdown” will also be added to the class attribute

````{admonition} <title>
:class: <admonition_type> <other_classes>
<admonition_content>
````

If the admonition doesn’t have a title, then the following syntax will be used

````{<admonition_type>}
:class: <classes>
<admonition_content>
````

In both cases above, note that we are using 4 backquotes instead of 3. That’s because an admonition can have other directives nested in it. So it needs to have more than 3 backquotes. The minimum required number depends on the levels of nesting. Dynamically assigning the backquotes depending on their nested directives, is currently out of the scope of this project.

To do

Determine if we will support [%collapsible].

Related

#106

[Mpdreamz]

Reiterating from #106 but it bares repeating IMO 😸

We explicitly don't/won't support MYST syntax which directly influences HTML.
So we never use :class: to set the admonition type or influence any other directive for that matter.

So we'll never want to expose new features by adding a 'class' as per:

Other classes can also be added to the class attribute. For example, if [%collapsible] option is specified for the admonition block, then “dropdown” will also be added to the class attribute

In the case of [%collapsible] docs-builder supports two options today:

Adding the :open: <bool> option to an admonition.

```{note}
:open:

Longer content can be collapsed to take less space.

```

Or we support a more general dropdown region with the {dropdown} directive

```{dropdown} Dropdown Title
:open:
Dropdown content
```

```{dropdown} Dropdown Title
Dropdown content
```

In both cases above, note that we are using 4 backquotes instead of 3. That’s because an admonition can have other directives nested in it. So it needs to have more than 3 backquotes. The minimum required number depends on the levels of nesting. Dynamically assigning the backquotes depending on their nested directives, is currently out of the scope of this project.

I would caution against this. Make 3 backticks the default only use 4 or more when you start needing to include nested directives which should be rare from a UX perspective in my opinion.

If this comes up a lot I suspect it might be hiding a new directives use case.