[clang] [Documentation] Replace recommonmark by myst-parser (PR #65664)
via cfe-commits
cfe-commits at lists.llvm.org
Thu Sep 7 12:47:42 PDT 2023
https://github.com/cor3ntin created https://github.com/llvm/llvm-project/pull/65664:
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: https://github.com/llvm/llvm-iwg/issues/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!
>From 9faad7e3b852391b566f9a18b78a850f4af9dd67 Mon Sep 17 00:00:00 2001
From: Corentin Jabot <corentinjabot at gmail.com>
Date: Thu, 7 Sep 2023 21:41:33 +0200
Subject: [PATCH] [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: https://github.com/llvm/llvm-iwg/issues/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 | 2 +-
clang/docs/conf.py | 23 ++--------
flang/docs/conf.py | 56 ++-----------------------
llvm/docs/MarkdownQuickstartTemplate.md | 4 +-
llvm/docs/SphinxQuickstartTemplate.rst | 8 ++--
llvm/docs/conf.py | 20 +++------
llvm/utils/release/build-docs.sh | 2 +-
7 files changed, 21 insertions(+), 94 deletions(-)
diff --git a/.github/workflows/release-tasks.yml b/.github/workflows/release-tasks.yml
index 5604b48857dbe25..afd3a7d97f00c4d 100644
--- a/.github/workflows/release-tasks.yml
+++ b/.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
diff --git a/clang/docs/conf.py b/clang/docs/conf.py
index de31a5dcd068eac..ca310026f53e2a9 100644
--- a/clang/docs/conf.py
+++ b/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'
diff --git a/flang/docs/conf.py b/flang/docs/conf.py
index 117cd1f1c97aea2..9950c9176c38798 100644
--- a/flang/docs/conf.py
+++ b/flang/docs/conf.py
@@ -9,10 +9,7 @@
# 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.
@@ -20,13 +17,6 @@
# -- 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'
diff --git a/llvm/docs/MarkdownQuickstartTemplate.md b/llvm/docs/MarkdownQuickstartTemplate.md
index 8d6434afe84ef39..add5985d5b40bb2 100644
--- a/llvm/docs/MarkdownQuickstartTemplate.md
+++ b/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
diff --git a/llvm/docs/SphinxQuickstartTemplate.rst b/llvm/docs/SphinxQuickstartTemplate.rst
index db9bd26bb3d9a4a..9998694932d686c 100644
--- a/llvm/docs/SphinxQuickstartTemplate.rst
+++ b/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:
diff --git a/llvm/docs/conf.py b/llvm/docs/conf.py
index 206f72285a830c2..5a11cc26f0e757b 100644
--- a/llvm/docs/conf.py
+++ b/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'
diff --git a/llvm/utils/release/build-docs.sh b/llvm/utils/release/build-docs.sh
index ef3784959b4f3aa..4f9e7d7768e7f54 100755
--- a/llvm/utils/release/build-docs.sh
+++ b/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
#===------------------------------------------------------------------------===#
More information about the cfe-commits
mailing list