Replace m2r and recommonmark with MyST

[luator]

recommonmark is officially deprecated in favour of MyST parser and m2r seems to be somewhat redundant (allowing a mix of both in one file if I understand it correctly).

I therefore suggest to drop both in favour of MyST

Pro:

• MyST It is the official suggestion in the Sphinx documentation.
• Clearer separation between Markdown and rst (you can use both md and rst files but within one file you have to be consistent).
• MyST has some special syntax (non-standard markdown) to support rst roles/directives, so you still have all the options to use references, add autodoc entries, etc. when using Markdown.

Con:

• It would be a breaking change as a mix-up of both markdown and rst within one file would not work anymore. However, my opinion is that this should not be done anyway, as it can be very confusing.

Originally posted by @luator in #1 (comment)

[luator]

@MaximilienNaveau Please let me know what you think of this. If you agree, I'll give it a try to see how complicated it will be to switch.

[luator]

I quickly tried and replacing recommonmark with MyST seems to be straight forward (see #5).

The bigger effort would be removing m2r as it provides the mdinclude directive used to integrate the README into the start page. For this I see two possible solutions:

1. Require packages to have a README in rst format
2. Provide a separate start page for the documentation that is independent of the README

I would prefer 2. as having one file that needs to work both as README on GitHub and as start page of the documentation can be very limiting (e.g. when including images or adding references). It would also allow more flexibility.

[MaximilienNaveau]

apparently: sphinx-doc/sphinx#7000
you can use myst_parser for including the readme file:
sphinx-doc/sphinx#7000 (comment)
sphinx-doc/sphinx#7000 (comment)

[MaximilienNaveau]

it is explained here:
https://myst-parser.readthedocs.io/en/latest/faq/index.html
I am not sure if this is working out of the box

[luator]

Ah, cool. Thanks for finding this, I'll give it a try.