Documentation of directives, roles, etc about myst-parser HOT 12 OPEN

Hi Chris,

thanks for opening this issue. Now that "version 2" of Jupyter Book is out, I've started creating a book. That obviously required me to read about MyST. I must say that it took me longer than I had thought to realized that MyST allows me to use all (or am I wrong?) Sphinx directives inside a Jupyter Book. For example, the MyST documentation shows an example with the code-block directive but it is not referenced anywhere in the documentation. It took me some googling to (find this issue and to) realize that it is the corresponding Sphinx directive.

I agree with you that additional documentation/guidance about the Sphinx directives would be beneficial.

Cheers.

from myst-parser.

nice - OK I opened up executablebooks/jupyter-book#607 to track this in the JB docs

from myst-parser.

Following the new issue!
Cheers.

from myst-parser.

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

from myst-parser.

Note sphinx also has a decent amount of documentation on reStructuredText, so we don't want to repeat too much of what they've already said, but I think a bit more documentation on our end would help.

from myst-parser.

Ordinarily I would just click the thumb under @filippo82 's comment, but that would be far too mild a sentiment. I spent something in the 15-30 minutes time frame looking for the list of directives in the MyST docs only to find nothing, then googled around, and after reading lots of stuff, ended up here, where I find that it's assumed you know rST first and are familiar with directives (!).

The links you're talking about are a 100% must have. In fact, I'd suggest that those links are insufficient, since you're supporting both Markdown and rST, and reading the rST-based docs is confusing for a Markdown native, since the conversion from the one syntax to the other isn't obvious.

But while I'm here and it looks like I'm just complaining, I'll also say that I was super excited to find out today about the existence of the Jupyter-Book project and all this tech like MyST that underlies it, and I'm definitely using it starting today! So thanks for all this great work!

from myst-parser.

Cheers. I guess the main point in the docs currently with the rST -> MyST comparison is here: https://myst-parser.readthedocs.io/en/latest/using/syntax.html#directives-a-block-level-extension-point.
Happy to receive PR's (even draft ones) of what would be ~minimally a good addition to the documentation to make this clear early on; as a stop gap before adding anything more substantial

from myst-parser.

I think another challenge that we're uncovering is the difference between Jupyter Book docs and myst-parser docs. The myst-parser is a Sphinx tool, and so I think we assume more knowledge about the Sphinx ecosystem for these docs. But, we should then make sure that the Jupyter Book docs do a better job of explaining the usage patterns for somebody that's not familiar with Sphinx.

@nathancarter can you think of a good place where this information would have helped you out in the Jupyter Book docs? I wanna make sure we don't confuse people who haven't used Sphinx/rST!

from myst-parser.

@choldgraf Directives appear in the Jupyter-Book documentation here. I would think it best to put there a link to the full list of directives.

from myst-parser.

@nathancarter it'd be a bit tricky to just add a list of all directives, since they're a combination of default docutils directives, default Sphinx directives, extra sphinx extensions, and Jupyter Book directives, which is why we've tried to just document the major ones through the JB docs.

Maybe one step is to just mention the broader Sphinx ecosystem of directives, mention that many will be written with rST and explain what that means, and note that many of them are documented throughout the JB docs.

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

from myst-parser.

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

I did something like this in https://github.com/chrisjsewell/rst-language-server and have used the result from that to populate the test fixtures in: https://github.com/executablebooks/MyST-Parser/tree/master/tests/test_renderers/fixtures (e.g. sphinx_directives.md, docutils_directives.md), and also to generate the auto-completes in https://marketplace.visualstudio.com/items?itemName=ExecutableBookProject.myst-highlight.
BTW Make sure you mention this VS Code extension in jupyter book 😁

from myst-parser.

that package intrigues me! I'm curious to see how it works!

from myst-parser.