MyST-Parser
MyST-Parser copied to clipboard
executablebooks
Issues with MyST documentation
Here are some issues I noticed with the MyST documentation as a new user:
- [ ] The docs don't mention anywhere how to do a table of contents. Since these are so essential in Sphinx, this seems like a major omission (as an aside, are there plans to implement something like recommonmark's auto toc tree?).
- [ ] I think it's a mistake to include
myst_config = {"disable_syntax": ["emphasis"], "math_delimiters": "brackets"}in the getting started config. Most people will just copy-paste that config, but this is not a config most people would want to use. Rather, the getting started should list what people should copy-paste to get started, and the config options should be documented somewhere else. There is a link to https://github.com/executablebooks/markdown-it-py which claims to list the syntax elements that can be disabled but I don't see any such list on that page. - [x] The instructions on how to run the benchmarks seem out of place in the "getting started" section. Why do I need to run the benchmarks to get started?
- [ ] The RST/Markdown Rosetta stone example is a good idea, but it should focus more on the source rather than the rendered pages, which appear to be identical. I would suggest inlining the sources directly in a code block, rather than having download links for them (which don't even open in the browser). If it is possible to put them side-by-side that would be better, but I don't know if that is easy to do.
- [x] I had issues finding the GitHub repo but that has already been fixed.
Another one: I didn't notice until a second read of https://myst-parser.readthedocs.io/en/latest/using/syntax.html#targets-and-cross-referencing that you can use Markdown syntax (I was starting to get quite angry that you just re-invented the terrible RST link syntax, and frankly, I don't understand why you don't use something like {ref}[name](target)). Why not show that at the top? Also it isn't obvious where the (header-target)= goes. Showing it in context would help.
that you just re-invented the terrible RST link syntax, and frankly, I don't understand why you don't use something like
{ref}[name](target)
Hey @asmeurer thanks for the feedback! It mostly sounds reasonable to me.
But one thing I want to stress (and maybe needs to be re-iterated in the docs) is that myst-parser is not re-inventing anything: for roles like {name}`content` , they are processed directly by the underlying docutils/sphinx functions/classes. For example, with {ref}`title <target>` the content is parsed by: https://github.com/sphinx-doc/sphinx/blob/c087d717f6ed183dd422359bf91210dc59689d63/sphinx/util/docutils.py#L404-L435. As such there was no "decision" to use {ref}`title <target>` over {ref}[name](target), it is mandated by sphinx.
The same goes for directives, such that roles and directives are basically the "primitive" constructs of the syntax; any of these will directly map to the relevant docutils/sphinx function/class, with no additional translation by myst-parser. This allows myst-parser to work for any role/directive that has or will be written for sphinx automatically.
For common roles/directives, like references, myst-parser then offers the additional "improved" markdown specific syntax; like [name](target) instead of {ref}`title <target>` .
(header-target)= directly maps to .. _header-target: in rST, and goes before the element (normally a header) that you want to target.
@asmeurer thanks - this is really helpful. I will try to work on a PR that implements some of the actionable things that you brought up. As @chrisjsewell mentions there are somethings that we don't have control over (like how the content of roles gets parsed in some cases) but in those cases we can also document their behavior. 👍
I see, so {ref}`stuff` (how on Earth did you put backticks in a code?) is just a shorthand to fallback to RST. That seems fine, although I guess there are cases where there are secondary syntaxes so that you don't have to use the RST (like (header-target)=). So presumably one could do the same for links. Although in my experience, any works 99% of the time. You only need something more specific if there is an ambiguity (although to be fair, Sphinx isn't as strict about this as it should be unless you set nitpicky=True). So maybe custom syntax here isn't warranted. But I do think that the Markdown syntax should be put front and center, and {ref}`stuff` only presented as a backup in case the Markdown isn't expressive enough.
yeah I agree that we should start with the most common or most basic / intuitive use-case, and then go into more detail later on.
and re: the backticks, markdown tends to "nest" literal blocks according to the number of ticks and whitespace / newlines, so
`` `hi` `` produces `hi`
and
````
```
hi
```
````
produces
```
hi
```
But yeh perhaps there could be something like "coming from rST" and "coming from Markdown" topics to offer explanations for both use-case.
I mean how did @chrisjsewell type "{ref}`stuff`" formatted as code in his GitHub comment above?
Yeh literally just type `` `{ref}`stuff` ``, or you if you want to show that type ``` `` `{ref}`stuff` `` ```, ...
Ah I didn't realize triple backticks could produce non-block code. I always thought you had to use <code> or something to get nested backticks (don't know why Markdown doesn't just let you escape backticks with a backslash like any other language would).
By the way, as long as you're answering questions here, the thing I'm actually stuck on is the toctree. I have something that works with recommonmark, but it doesn't work with Myst.
don't know why Markdown doesn't just let you escape backticks with a backslash like any other language would
It does? `a`
the thing I'm actually stuck on is the toctree. I have something that works with recommonmark, but it doesn't work with Myst.
Just this should work, in exactly the same way as rST?
```{toctree}
path1
path2
```
or with options:
```{toctree}
:hidden: true
:maxdepth: 2
:caption: My Title
path/file1
path/file2
```
I mean to produce nested backticks. Like in Python you can just do 'don\'t' but you can't write {ref}\`stuff\` (it just produces {ref}\stuff``)
Well I mean to produce nested backticks. Like in Python you can just do 'don't' but you can't write {ref}`stuff` (it just produces {ref}\stuff``)
Well code fences are more like using r'don\'t' in python
re: the toctree, there is no special syntax in MyST markdown for a "toctree", it just uses the directive syntax that Chris mentioned above
The reason recommonmark overloads markdown lists for this is because it doesn't have any syntax for a role or directive. We are in general trying not to introduce too much markdown-specific syntax beyond just the markdown equivalents of rST syntax (e.g., like (mylabel)= in myst for .. _mylabel: in rst)
Another documentation gripe is that the in-page table of contents on the right is very frustrating to use. It only appears when moused over and doesn't actually show the full table of contents. I don't know how much control you have over whatever Sphinx theme you are using.
It only appears when moused over
I feel the same 😉 , see https://github.com/executablebooks/sphinx-book-theme/issues/95
@asmeurer actually we have full control over it because we also develop it haha
the reason that the right-most TOC disappears is because many jupyter books use the right margin for their content. However, it is frustrating in cases like these docs where there is no right margin content...it's planned to make this optional but we just haven't had the hours in the day yet.
I just opened up https://github.com/executablebooks/sphinx-book-theme/issues/102 to track the right TOC issues
A dependencies section would be helpful.
-
[x] Add dependencies section to make clear that Sphinx math or dollarmath does not work "out of the box". Possibly add other dependencies.
(I'm getting an error about missing dvi2png here and am trying to fix it. Only get it for HTML builder, though, not for Confluence builder...)
/edit: clarified (see below).
Add dependencies section to make clear that Sphinx math or dollarmath
I'm not sure what you mean by this, since dollar math does work out of the box, i.e. if you write $a=1$ it will be picked up and rendered as math.
As per #322 and #323, perhaps it is something to do with the combination of sphinx extensions you are using?
it works out of the box for me but didn't get rendered because Sphinx was complaining that dvi2png executable was missing. I might have to install some other apt package for that - but neither the Sphinx nor the MyST docu tell me.
What actually helped for me was:
# Use dvi2svg in HTML output (sphinx.ext.imagemath)
imgmath_image_format = "svg"
but neither the Sphinx nor the MyST docu tell me.
Are you sure about that 😉: https://www.sphinx-doc.org/en/master/usage/extensions/math.html#module-sphinx.ext.imgmath specifically says "This extension renders math via LaTeX and dvipng"
Note you only need this because you have added the sphinx.ext.imgmath extension, by default sphinx uses sphinx.ext.mathjax for which dvipng is not required.
I got the error before I included sphinx.ext.imgmath.
Again, I could try to provide an atomic example once I find the time...
Anyhow: In general, it would be nice if the manual states which other extension this extension uses. Did I overlook this section?
I got the error before I included
sphinx.ext.imgmath.
that is definitely not the case if the only extension you have loaded is myst_parser, perhaps one of the other extensions you are using is loading sphinx.ext.imgmath?
In general, it would be nice if the manual states which other extension this extension uses.
myst-parser does not use any other extensions. For math it simply translates dollarmath to the internal sphinx AST math node representation, it does not dictate in any way how it is rendered.
If you load sphinx.ext.imgmath then you will also need dvipng (as it documents), but that is not anything to-do with myst-parser