`recommonmark` is deprecated

https://github.com/readthedocs/recommonmark#recommonmark

We should switch to myst: https://github.com/executablebooks/MyST-Parser

[cruisen]

@sobolevn please comment.

Here are some comments and a little feasibility study:

wemake-python-styleguide:

• dependencies: If the motivation is only to reduce the amount of external dependencies, which is a very good reason to begin with, then this PR is not worth the effort. - It basically adds four new ones.

  poetry add -D myst-parser • Installing mdurl (0.1.0) • Installing markdown-it-py (2.0.1) • Installing mdit-py-plugins (0.3.0) • Installing myst-parser (0.16.1)

• make html does not fail anymore: Please note, a PR already was tried and rejected due to doc building problems. As described in here, apparently you had problems to rebuild your doctree.

  So I cloned gh repo clone wemake-services/wemake-python-package. Installed sphinx and myst-parser and configured conf.py and index.rstfollowing the myst instructions and included the README.md and CONTRIBUTING.md to the doctree and it worked for me, no errors 🙂.

  make html Running Sphinx v4.4.0 loading pickled environment… done myst v0.16.1: MdParserConfig(renderer=‘sphinx’, commonmark_only=False, enable_extensions=[‘dollarmath’], […] build succeeded. The HTML pages are in build/html.

wemake-python-styleguide

• dependencies: Here we remove two but add four.

  poetry remove -D m2r2 • Removing m2r2 (0.3.2) • Removing mistune (0.8.4)

  poetry add -D myst-parser • Installing mdurl (0.1.0) • Installing markdown-it-py (2.0.1) • Installing mdit-py-plugins (0.3.0) • Installing myst-parser (0.16.1)

• make html: with minimal md to myst adaption like mdincude -> include …:

  Running Sphinx v4.3.2 […] build succeeded, 28 warnings. The HTML pages are in _build/html.

  See attached warnings.txt.

Conclusion

• myst-parser: So if the motivation is to replace the m2r2 translation layer with, and/or adapt to what I call sphinx best practice myst-parser, then, based on the mentioned PR, I will happily have a look to estimate the amount of work needed, and then discuss and decide on two new PR’s, most probable one each on both repositories?

Please comment.

[cruisen]

@cruisen I would love to get rid of any extra dependencies. If you have the time to work on this, I will accept this PR 🙂

@sobolevn Thank you 🙂.