[Documentation] Replace recommonmark by myst-parser (#65664)

Recommonmark has been deprecated, then archived last year. This was tracked by: llvm/llvm-iwg#30 See https://github.com/readthedocs/recommonmark This patch migrates all our doc to use myst Additional details for bot maintainers: https://discourse.llvm.org/t/maintenance-required-on-sphinx-build-bots/73612

Author: cor3ntin

.github/workflows/release-tasks.yml

@@ -24,21 +24,19 @@ jobs:
  release_version=$(echo "${{ github.ref_name }}" | sed 's/llvmorg-//g')
  echo "release-version=$release_version" >> "$GITHUB_OUTPUT"
 
+ - name: Checkout LLVM
+ uses: actions/checkout@v4
+
  - name: Install Dependencies
  run: |
  sudo apt-get update
  sudo apt-get install -y \
  doxygen \
  graphviz \
  python3-github \
- python3-recommonmark \
- python3-sphinx \
  ninja-build \
  texlive-font-utils
- pip3 install --user sphinx-markdown-tables
-
- - name: Checkout LLVM
- uses: actions/checkout@v4
+ pip3 install --user -r ./llvm/docs/requirements.txt
 
  - name: Create Release
  run: |

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/Aliasing.md

@@ -8,9 +8,10 @@
 
 # Aliasing in Fortran
 
-```eval_rst
-.. contents::
- :local:
+```{contents}
+---
+local:
+---
 ```
 
 ## Introduction

flang/docs/ArrayComposition.md

@@ -8,9 +8,10 @@
 
 # Array Composition
 
-```eval_rst
-.. contents::
- :local:
+```{contents}
+---
+local:
+---
 ```
 
 This note attempts to describe the motivation for and design of an

flang/docs/BijectiveInternalNameUniquing.md

@@ -8,9 +8,10 @@
 
 # Bijective Internal Name Uniquing
 
-```eval_rst
-.. contents::
- :local:
+```{contents}
+---
+local:
+---
 ```
 
 FIR has a flat namespace. No two objects may have the same name at the module

flang/docs/C++17.md

@@ -8,9 +8,10 @@
 
 # C++14/17 features used in f18
 
-```eval_rst
-.. contents::
- :local:
+```{contents}
+---
+local:
+---
 ```
 
 The C++ dialect used in this project constitutes a subset of the

flang/docs/C++style.md

@@ -8,9 +8,10 @@
 
 # Flang C++ Style Guide
 
-```eval_rst
-.. contents::
- :local:
+```{contents}
+---
+local:
+---
 ```
 
 This document captures the style guide rules that are followed in the Flang codebase.

flang/docs/Calls.md

@@ -8,9 +8,10 @@
 
 # Representation of Fortran function calls
 
-```eval_rst
-.. contents::
- :local:
+```{contents}
+---
+local:
+---
 ```
 
 ## Procedure reference implementation protocol

flang/docs/Character.md

@@ -8,9 +8,10 @@
 
 # Implementation of `CHARACTER` types in f18
 
-```eval_rst
-.. contents::
- :local:
+```{contents}
+---
+local:
+---
 ```
 
 ## Kinds and Character Sets

flang/docs/ComplexOperations.md

@@ -1,7 +1,7 @@
 # Complex Operations
 
-```eval_rst
-.. contents::
+```{eval-rst}
+.. toctree::
  :local:
 ```