From 9faad7e3b852391b566f9a18b78a850f4af9dd67 Mon Sep 17 00:00:00 2001 From: Corentin Jabot 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 5604b48857dbe2..afd3a7d97f00c4 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 de31a5dcd068ea..ca310026f53e2a 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 117cd1f1c97aea..9950c9176c3879 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 8d6434afe84ef3..add5985d5b40bb 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 db9bd26bb3d9a4..9998694932d686 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 `_ you need to install `Sphinx`_ and the -`recommonmark `_ extension. +`myst-parser `_ 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 206f72285a830c..5a11cc26f0e757 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 ef3784959b4f3a..4f9e7d7768e7f5 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 #===------------------------------------------------------------------------===#