Switch recommonmark to myst-parser

recommonmark is being phased out in favor of myst-parser, see Proposal to sunset recommonmark in favor of MyST-Parser · Issue #221 · readthedocs/recommonmark · GitHub . Feedback on the transition would be useful to the maintainers on that issue.

Thx for letting us know! I added an issue to the backlog of the infrastructure working group. Not sure if that is in scope for that group…


At some point fairly recently recommonmark has been introduced into the clang/docs for the life of me I can no longer build the HTML. No amount of pip’ing seems to be solving this for me, any clues?


/usr/bin/sphinx-build -n ./docs ./html
Running Sphinx v3.1.2

Configuration error:
There is a programmable error in your configuration file:

Traceback (most recent call last):
File “/usr/lib/python3.7/site-packages/sphinx/config.py”, line 319, in eval_config_file
execfile_(filename, namespace)
File “/usr/lib/python3.7/site-packages/sphinx/util/pycompat.py”, line 88, in execfile_
exec(code, _globals)
File “/buildareas/clang/llvm-project/clang/docs/conf.py”, line 41, in
import recommonmark
ModuleNotFoundError: No module named ‘recommonmark’

I’ve created a patch to migrate from recommonmark to myst-parser, any feedback would be much appreciated. It was fairly straightforward, just had to update some markdown documents to conform to myst-parser’s stricter parsing.
Not sure what needs to be done on the CI side but this seems to be enough anyway to get the llvm/clang/flang docs building locally.

1 Like