[Documentation] Replace recommonmark by myst-parser

This is a bit rough, but i did that while trying to
figure out if there would be a good way to do
pre commit checks on RsT files.

Recommonmark has been deprecated, then archived last year.
This was tracked by: llvm/llvm-iwg#30

https://github.com/readthedocs/recommonmark

Before merging that we would have to update the bots,
which I'm not in a good position to do, so feel free to take over!

.github/workflows/release-tasks.yml

@@ -31,7 +31,7 @@ jobs:
               doxygen \
               graphviz \
               python3-github \
-              python3-recommonmark \
+              python3-myst-parser \
               python3-sphinx \
               ninja-build \
               texlive-font-utils

clang/docs/conf.py

@@ -32,26 +32,11 @@
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]
 
-# The suffix of source filenames.
-source_suffix = {
-    ".rst": "restructuredtext",
-}
 
-try:
-    import recommonmark
-except ImportError:
-    # manpages do not use any .md sources
-    if not tags.has("builder-man"):
-        raise
-else:
-    import sphinx
-
-    if sphinx.version_info >= (3, 0):
-        # This requires 0.5 or later.
-        extensions.append("recommonmark")
-    else:
-        source_parsers = {".md": "recommonmark.parser.CommonMarkParser"}
-    source_suffix[".md"] = "markdown"
+import sphinx
+
+if sphinx.version_info >= (3, 0):
+    extensions.append("myst_parser")
 
 # The encoding of source files.
 # source_encoding = 'utf-8-sig'

flang/docs/conf.py

@@ -9,24 +9,14 @@
 # All configuration values have a default; values that are commented out
 # serve to show the default.
 
-import sys, os
 from datetime import date
-from recommonmark.parser import CommonMarkParser
-
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 # sys.path.insert(0, os.path.abspath('.'))
 
 # -- General configuration -----------------------------------------------------
 
-# https://github.com/readthedocs/recommonmark/issues/177
-# Method used to remove the warning message.
-class CustomCommonMarkParser(CommonMarkParser):
-    def visit_document(self, node):
-        pass
-
-
 # If your documentation needs a minimal Sphinx version, state it here.
 # needs_sphinx = '1.0'
 # Add any Sphinx extension module names here, as strings. They can be extensions
@@ -36,49 +26,11 @@ def visit_document(self, node):
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]
 
-# The suffix of source filenames.
-source_suffix = {
-    ".rst": "restructuredtext",
-}
-try:
-    import recommonmark
-except ImportError:
-    # manpages do not use any .md sources
-    if not tags.has("builder-man"):
-        raise
-else:
-    import sphinx
-
-    if sphinx.version_info >= (3, 0):
-        # This requires 0.5 or later.
-        extensions.append("recommonmark")
-    else:
-        source_parsers = {".md": CustomCommonMarkParser}
-    source_suffix[".md"] = "markdown"
-    extensions.append("sphinx_markdown_tables")
-
-    # Setup AutoStructify for inline .rst toctrees in index.md
-    from recommonmark.transform import AutoStructify
-
-    # Stolen from https://github.com/readthedocs/recommonmark/issues/93
-    # Monkey patch to fix recommonmark 0.4 doc reference issues.
-    from recommonmark.states import DummyStateMachine
-
-    orig_run_role = DummyStateMachine.run_role
-
-    def run_role(self, name, options=None, content=None):
-        if name == "doc":
-            name = "any"
-            return orig_run_role(self, name, options, content)
-
-    DummyStateMachine.run_role = run_role
-
-    def setup(app):
-        # Disable inline math to avoid
-        # https://github.com/readthedocs/recommonmark/issues/120 in Extensions.md
-        app.add_config_value("recommonmark_config", {"enable_inline_math": False}, True)
-        app.add_transform(AutoStructify)
+import sphinx
 
+if sphinx.version_info >= (3, 0):
+    extensions.append("myst_parser")
+extensions.append("sphinx_markdown_tables")
 
 # The encoding of source files.
 # source_encoding = 'utf-8-sig'

llvm/docs/MarkdownQuickstartTemplate.md

@@ -151,10 +151,10 @@ without any syntax highlighting like this:
 
 If you need to do fancier things than what has been shown in this document,
 you can mail the list or check the [Common Mark spec].  Sphinx specific
-integration documentation can be found in the [recommonmark docs].
+integration documentation can be found in the [myst-parser docs].
 
 [Common Mark spec]: http://spec.commonmark.org/0.28/
-[recommonmark docs]: http://recommonmark.readthedocs.io/en/latest/index.html
+[myst-parser docs]: https://myst-parser.readthedocs.io/en/latest/
 
 ## Generating the documentation
 

llvm/docs/SphinxQuickstartTemplate.rst

@@ -172,19 +172,19 @@ You can generate the HTML documentation from the sources locally if you want to
 see what they would look like. In addition to the normal
 `build tools <docs/GettingStarted.html>`_
 you need to install `Sphinx`_ and the
-`recommonmark <https://recommonmark.readthedocs.io/en/latest/>`_ extension.
+`myst-parser <https://myst-parser.readthedocs.io/en/latest/>`_ extension.
 
 On Debian you can install these with:
 
 .. code-block:: console
 
-   sudo apt install -y sphinx-doc python-recommonmark-doc
+   sudo apt install -y sphinx-doc python3-myst-parser
 
-On Ubuntu use pip to get an up-to-date version of recommonmark:
+On Ubuntu use pip to get an up-to-date version of python3-myst-parser:
 
 .. code-block:: console
 
-   sudo pip install sphinx recommonmark
+   sudo pip install sphinx myst-parser
 
 Then run cmake to build the documentation inside the ``llvm-project`` checkout:
 

llvm/docs/conf.py

@@ -36,21 +36,11 @@
     ".rst": "restructuredtext",
 }
 
-try:
-    import recommonmark
-except ImportError:
-    # manpages do not use any .md sources
-    if not tags.has("builder-man"):
-        raise
-else:
-    import sphinx
-
-    if sphinx.version_info >= (3, 0):
-        # This requires 0.5 or later.
-        extensions.append("recommonmark")
-    else:
-        source_parsers = {".md": "recommonmark.parser.CommonMarkParser"}
-    source_suffix[".md"] = "markdown"
+import sphinx
+
+if sphinx.version_info >= (3, 0):
+    extensions.append("myst_parser")
+extensions.append("sphinx_markdown_tables")
 
 # The encoding of source files.
 # source_encoding = 'utf-8-sig'

llvm/utils/release/build-docs.sh

@@ -15,7 +15,7 @@
 #                 ninja-build gcc-c++
 #   * pip install sphinx-markdown-tables
 # * Ubuntu:
-#   * apt-get install doxygen sphinx-common python3-recommonmark \
+#   * apt-get install doxygen sphinx-common python3-myst-parser \
 #             ninja-build graphviz texlive-font-utils
 #   * pip install sphinx-markdown-tables
 #===------------------------------------------------------------------------===#