DOC: First pass at format conversion, rst -> myst #4863
Conversation
* Add myst-parser to doc requirements * Add myst-parser extension to conf.py * Start working on the overview doc.
* Switch to #-based headings to suppress markdown parse warnings * ignore inconsistencies between emph/literal - assume all are intended to be inline literals
* Leave link to INSTALL.rst using include directive.
* Illustrate the toctree directive in myst syntax.
* NOTE: Left CONTRIBUTING.TXT alone even though it has rst syntax as it might be used elsewhere.
|
Thanks @rossbar ! myst seems to be a really cool project. I was a bit surprised to see your PR since since had not been discussed in an issue previously but this is definitely interesting. Could you please give us a bit of context and information about how you did the reformatting (completely manually or with some script?)? Did you notice any pain points concerning myST during the conversion? |
Sorry about dropping this in out of the blue with no context! Re: the conversion itself, I manually converted all of the files as an exercise rather than trying to automate the process. In general this was very straightforward, especially for a lot of the linking roles, where simple find/replace is sufficient (e.g. |
|
Thanks for this feedback @rossbar. From what I read in the MyST doc, it's possible to have a mixture of |
Yes exactly, that's why I left e.g. |
|
@emmanuelle Just to provide some background: I asked @rossbar to look into converting our documentation, especially narrative, into MyST, so that we can write in Markdown. I think this lowers the barrier for documentation contributors, and also for ourselves. I noticed, e.g., that people often forget how to use RST links properly (I do too, it's pretty obcure). Is it one underscore, or two? I previously tried to do this with recommonmark, but never had much success. MyST has worked flawlessly with other projects, though, so I thought we could give it a go. And, since @rossbar is the resident expert on MyST... :) |
|
Reviewers: you can take a look at the newly added doc artifact to see the doc corresponding to this PR. Handy isn't it :-). Ross: please pull from your branch as I solved a conflict. |
|
One comment I have is that I think we should try to get sphinx-gallery to support MyST before converting. Otherwise, we are stuck using a mixture of ReST and Markdown. Or does this PR achieve that effect automagically? I think most new contributions are to the gallery examples, anyway. |
|
I think Sphinx-Gallery supporting markdown / MyST is still a ways off. I don't see any reason not to make our documentation more pleasant to work on in the mean time? |
|
Well, it complicates the contributing guide: "If working on these docs, do this. If working on these other docs, do this other thing..." But, point taken. We have indeed had issues with sphinx building in some recent PRs. I was just flagging for discussion, I don't consider it a blocker. |
|
See sphinx-gallery/sphinx-gallery#710 for sphinx-gallery and myst/markdown. |
Not ideal, I agree. Let's see how this PR turns out, then we can decide. |
|
The formatting of some links in https://93-2014929-gh.circle-artifacts.com/0/doc/build/html/contribute.html did not turn out well. |
Good catch - this was a tricky one because all that |
| @@ -11,4 +11,4 @@ Release notes | |||
| Installation | |||
| ============ | |||
|
|
|||
| .. include:: install.rst | |||
| .. include:: install.md | |||
There was a problem hiding this comment.
there seems to be a problem here, see https://114-2014929-gh.circle-artifacts.com/0/doc/build/html/release_notes_and_installation.html#installation
There was a problem hiding this comment.
Another good catch - this seems to stem from the same cause as the problem in the above comment (include-ing an .rst formatted file from outside of the docs build inside a markdown document). Reverted back to rST in ef33c3a
|
I think I found another rst/md problem but when it's resolved I'll be ready to approve this PR. If someone disagrees with using mystify, now is the time :-). |
This reverts commit 3fa567c and updates include directives accordingly
|
I'm happy to switch to markdown. |
|
Cool. I'll leave the PR open for one or two more days in case someone else wants to comment, since this is an important decision to make, but to @sciunto and me this PR is ready and represents an improvement. @rossbar do you think the problem of rst files included from an md file should be reported to the mystify team? There will be some files which we're not interested in porting to markdown, like the release notes from previous versions, and it'd be great to find a way to circumvent this problem. |
Would it be painful to convert them with pandoc? |
maybe not :-) |
Good idea! I've opened a new issue (linked above). |
|
Hey guys 👋 @rossbar just pointed me toward this PR in executablebooks/MyST-Parser#204. As the main author of MyST I love it lol 😁 and just wanted to say if you have any questions, issues or suggestions, don't hesitate to get in touch. |
|
Oh and its probably too late for here, but I'd note there is some work going on to create an rST to MyST converter currently here: https://github.com/mmcky/sphinxcontrib-rst2myst (but will move to executablebooks soon) |
|
thanks @chrisjsewell ! We'll definitely ping you if needed in future conversations! I think the biggest problem we've encountered so far is that it's not possible to include a rst file within an md one, do you have any suggestions about this issue? For now I'll be merging this PR. |
no problem @emmanuelle, yes as discussed with @rossbar in executablebooks/MyST-Parser#204 (comment) its a work in progress 😬 But hopefully sooner than later |
This is now possible in v0.12.2 😄 https://myst-parser.readthedocs.io/en/latest/using/howto.html#include-rst-files-into-a-markdown-file |
|
Fantastic, thanks @chrisjsewell! |
Description
This PR encompasses a first past at converting the existing (non-generated) documentation from rST to myst markdown. Most of the files in the top-level
toctreeinsource/index.rsthave been converted.The documentation build system requires an additional sphinx extension (
myst_parser) in order to properly parse and build the docs. This extra dependency and associated configuration were added in 025424f, so the following procedure should be sufficient to build the docs:For reviewers
later.
__init__.py.doc/release/release_dev.rst.