📚 DOCS: Full update

[chrisjsewell]

Just about ready for a release!

[codecov]

Codecov Report

Patch coverage: 92.80% and project coverage change: +0.01 🎉

Comparison is base (7692f87) 89.93% compared to head (b4fa8a8) 89.95%.

Additional details and impacted files

@@            Coverage Diff             @@
##           master     #717      +/-   ##
==========================================
+ Coverage   89.93%   89.95%   +0.01%     
==========================================
  Files          23       23              
  Lines        2892     2967      +75     
==========================================
+ Hits         2601     2669      +68     
- Misses        291      298       +7     

Flag	Coverage Δ
pytests	89.95% <92.80%> (+0.01%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

Impacted Files	Coverage Δ
myst_parser/config/main.py	86.03% <ø> (ø)
myst_parser/sphinx_ext/myst_refs.py	88.76% <ø> (ø)
myst_parser/mdit_to_docutils/base.py	92.67% <86.95%> (-0.27%)	⬇️
myst_parser/mdit_to_docutils/sphinx_.py	95.90% <94.54%> (-1.83%)	⬇️
myst_parser/__init__.py	100.00% <100.00%> (ø)
myst_parser/mocking.py	84.82% <100.00%> (ø)
myst_parser/parsers/docutils_.py	82.72% <100.00%> (+1.90%)	⬆️
myst_parser/sphinx_ext/main.py	89.74% <100.00%> (ø)
myst_parser/warnings_.py	96.15% <100.00%> (+0.07%)	⬆️

Help us with your feedback. Take ten seconds to tell us how you rate us. Have a feature suggestion? Share it here.

☔ View full report at Codecov.
📢 Do you have feedback about the report comment? Let us know in this issue.

[rowanc1]

Took a look through all the docs, block attrs and inline attributes look great. The hover-tool tips are great, as you know I am a big fan of showing contextual information. Also was funny to see some of the Shakespeare quote and poems I chose making their way back here.

Only concern in this PR is around the mixing of directive names and class names. I think that is fine if we adopt a widely used existing syntax (e.g. support quarto-style callouts). However, I don't think that we should suggest another way to do admonitions without addressing some of the existing confusions. e.g. in jupyter-book/myst-spec#49. @mmcky @choldgraf and I have been chatting about this recently, and some of our thoughts are going to be clarified in the next few weeks!

Can we please either (1) put a warning around this saying we might deprecate it; or (2) remove the functionality.

I would love to discuss how directives and class-names interact in a specific MEP, but I think that needs to come after we decide as a team on the block and inline syntax!

[chrisjsewell]

Just to link, as we discussed on slack; I have tried to kick start some conversation here, as to a shorthand to essentially specify a role/directive in attribute syntax: jgm/djot#146

[mgielda]

I think the docs should probably use sth like:

![fishy](img/fun-fish.png)

For an example. Hopefully most people use the md image syntax, not the HTML one :)

[chrisjsewell]

Done thanks!

Admonitions removed, can take another pass when this is closer to merge, please ping me!