docs: use myst-parser for md

[henryiii]

Closes #559 again.

See readthedocs/recommonmark#221 - recommonmark has been sun-setted, myst-parser is the replacement.

[FollowTheProcess]

LGTM, might it be worth another PR build to check? @dhermes

[henryiii]

I think we were just merging then trying to rebuild readthedocs, since PR docs builds are not working. But this does work both locally and with the GHA docs build.

[henryiii]

https://readthedocs.org/projects/nox/builds/15750719/ :D

[henryiii]

So latest is working, stable need to be rebuilt. @dhermes could you retrigger stable, probably pointing it at main temporarily? Not sure the best way to do that.

[dhermes]

The point of stable is that it points at a released version of the code / docs. Not really sure what a good strategy is for that (short of cutting a release).

[henryiii]

I believe no changes have been made since the last release, so rebuilding with the current main would be identical to the last release. (As long as you don't leave it on current main).

[cjolowicz]

Another possibility would be to make a post-release, 2022.1.7.post1. That would trigger the stable build, and give us a PyPI release that's clearly marked as a minor correction without user-visible changes.

[henryiii]

Post releases should be metadata only (which is pretty much exactly what this is - docs), so that would also be fine. Though I'd still think that's a little overkill, the point of stable is to have docs for the latest release that don't also include features/changes added since the latest release, not that they have to be tied to an exact tag, but yes, it's fine.

[henryiii]

(In pybind11 we have a stable branch and that's what the stable docs builds from, which allows us to make docs fixes after a release if we really need to - thought usually we don't)