Documentation of directives, roles, etc

It would be good to include in the documentation some guidance for users on how to get the most out of MyST; particularly those that haven’t used rST before.

Most of the directives are documented at:

• https://docutils.sourceforge.io/docs/ref/rst/directives.html
• https://www.sphinx-doc.org/en/1.8/usage/restructuredtext/directives.html

So at a minimum these links should be provided. It would be ideal though to (a) show what these directives look like in MyST format, and (b) also provide some more ‘user-friendly’ tutorials on some specific aspects (the include directive being one of these, as discussed in #80).

A good example of some user-friendly documentation is what the Overleaf knowledge base has for LaTex.

For a full list of available (core) roles and directives (with tested input/output), see tests/test_renderers/sphinx_roles.json and tests/test_renderers/sphinx_directives.json.

@jstac & @mmcky this could be something that your guys helped with 😄

[chrisjsewell]

I wonder if there’s some way we could auto-generate a list of directives that are available to a default jupyter-book build…

This will now be achieved in https://github.com/executablebooks/sphinx-ext-autodoc

[filippo82]

Following the new issue! Cheers.