recommonmark is deprecated

[sobolevn]

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

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

[vitkhab]

This project uses m2r2 module to translate markdown to restructured text. I see no trace of recommonmark usage in this project. It's only listed in requirements.txt. Also recommonmark is NOT a dependency for m2r2 and docs generation works ok on my computer with no recommonmark installed.

Configuration part where m2r2 module is used

Did I miss something?

What should be done? recommonmark removed from project? m2r2 changed to myst?

[sobolevn]

@vitkhab you are correct. This is not an issue for this repo.

[cruisen]

May I add my 2ct on this.

wemake-python-package is Great as is.

However myst-parser is a first class citizen of sphinx. Since it parses to docutils directly, instead of translating to rst like m2r2 does.

Why I believe this is important? Writing professional documentation profits from the available concepts within myst, like

• roles
• targets and cross-reference
• ...

So from my point of view switching to myst-parser seems to be a logical step for wemake.

But maybe I am missing something?

[sobolevn]

@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 🙂

[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 🙂.

[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.

[sobolevn]

@cruisen looks awesome! 🎉