wemake-services/wemake-python-package

`recommonmark` is deprecated

sobolevn opened this issue · 7 comments

vitkhab commented

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 commented

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

cruisen commented

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

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

But maybe I am missing something?

  • 👍1
sobolevn commented

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

  • 👍1
cruisen commented

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

  • 👍1
cruisen commented

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

  • 👍1
sobolevn commented

@cruisen looks awesome! 🎉