[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
llvm · Sep 25, 2023 · b7ff032 · b7ff032
1 parent 92a394e
commit b7ff032
Show file tree

Hide file tree

Showing 44 changed files with 173 additions and 225 deletions.
diff --git a/.github/workflows/release-tasks.yml b/.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: |

diff --git 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/Aliasing.md b/flang/docs/Aliasing.md
@@ -8,9 +8,10 @@
 
 # Aliasing in Fortran
 
-```eval_rst
-.. contents::
-   :local:
+```{contents}
+---
+local:
+---
 ```
 
 ## Introduction

diff --git a/flang/docs/ArrayComposition.md b/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

diff --git a/flang/docs/BijectiveInternalNameUniquing.md b/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

diff --git a/flang/docs/C++17.md b/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

diff --git a/flang/docs/C++style.md b/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.

diff --git a/flang/docs/Calls.md b/flang/docs/Calls.md
@@ -8,9 +8,10 @@
 
 # Representation of Fortran function calls
 
-```eval_rst
-.. contents::
-   :local:
+```{contents}
+---
+local:
+---
 ```
 
 ## Procedure reference implementation protocol

diff --git a/flang/docs/Character.md b/flang/docs/Character.md
@@ -8,9 +8,10 @@
 
 # Implementation of `CHARACTER` types in f18
 
-```eval_rst
-.. contents::
-   :local:
+```{contents}
+---
+local:
+---
 ```
 
 ## Kinds and Character Sets

diff --git a/flang/docs/ComplexOperations.md b/flang/docs/ComplexOperations.md
@@ -1,7 +1,7 @@
 # Complex Operations
 
-```eval_rst
-.. contents::
+```{eval-rst}
+.. toctree::
    :local:
 ```
 

diff --git a/flang/docs/ControlFlowGraph.md b/flang/docs/ControlFlowGraph.md
@@ -8,9 +8,10 @@
 
 # Control Flow Graph
 
-```eval_rst
-.. contents::
-   :local:
+```{contents}
+---
+local:
+---
 ```
 
 ## Concept

diff --git a/flang/docs/DesignGuideline.md b/flang/docs/DesignGuideline.md
@@ -7,9 +7,10 @@
 -->
 # Design Guideline
 
-```eval_rst
-.. contents::
-   :local:
+```{contents}
+---
+local:
+---
 ```
 ## Documenting the design
 

diff --git a/flang/docs/DoConcurrent.md b/flang/docs/DoConcurrent.md
@@ -8,9 +8,10 @@
 
 # `DO CONCURRENT` isn't necessarily concurrent
 
-```eval_rst
-.. contents::
-   :local:
+```{contents}
+---
+local:
+---
 ```
 
 A variant form of Fortran's primary looping construct was

diff --git a/flang/docs/Extensions.md b/flang/docs/Extensions.md
@@ -8,9 +8,10 @@
 
 # Fortran Extensions supported by Flang
 
-```eval_rst
-.. contents::
-   :local:
+```{contents}
+---
+local:
+---
 ```
 
 As a general principle, this compiler will accept by default and

diff --git a/flang/docs/FIRArrayOperations.md b/flang/docs/FIRArrayOperations.md
@@ -8,9 +8,10 @@
 
 # Design: FIR Array operations
 
-```eval_rst
-.. contents::
-   :local:
+```{contents}
+---
+local:
+---
 ```
 
 ## General

diff --git a/flang/docs/FlangDriver.md b/flang/docs/FlangDriver.md
@@ -8,9 +8,10 @@
 
 # Flang drivers
 
-```eval_rst
-.. contents::
-   :local:
+```{contents}
+---
+local:
+---
 ```
 
 There are two main drivers in Flang:

diff --git a/flang/docs/FortranFeatureHistory.md b/flang/docs/FortranFeatureHistory.md
@@ -8,9 +8,10 @@
 
 # A Fortran feature history cheat sheet
 
-```eval_rst
-.. contents::
-   :local:
+```{contents}
+---
+local:
+---
 ```
 
 ## Original IBM 704 FORTRAN

diff --git a/flang/docs/FortranForCProgrammers.md b/flang/docs/FortranForCProgrammers.md
@@ -8,9 +8,10 @@
 
 # Fortran For C Programmers
 
-```eval_rst
-.. contents::
-   :local:
+```{contents}
+---
+local:
+---
 ```
 
 This note is limited to essential information about Fortran so that

diff --git a/flang/docs/FortranIR.md b/flang/docs/FortranIR.md
@@ -8,9 +8,10 @@
 
 # Design: Fortran IR
 
-```eval_rst
-.. contents::
-   :local:
+```{contents}
+---
+local:
+---
 ```
 
 ## Introduction

diff --git a/flang/docs/FortranLLVMTestSuite.md b/flang/docs/FortranLLVMTestSuite.md
@@ -1,8 +1,9 @@
 # Fortran Tests in the LLVM Test Suite
 
-```eval_rst
-.. contents::
-   :local:
+```{contents}
+---
+local:
+---
 ```
 
 The [LLVM Test Suite](https://github.com/llvm/llvm-test-suite) is a

diff --git a/flang/docs/GettingInvolved.md b/flang/docs/GettingInvolved.md
@@ -7,9 +7,10 @@
 -->
 # Getting Involved
 
-```eval_rst
-.. contents::
-   :local:
+```{contents}
+---
+local:
+---
 ```
 
 The Flang Project welcomes contributions of all kinds.

diff --git a/flang/docs/GettingStarted.md b/flang/docs/GettingStarted.md
@@ -8,9 +8,10 @@
 
 # Getting Started
 
-```eval_rst
-.. contents::
-   :local:
+```{contents}
+---
+local:
+---
 ```
 
 ## Building flang
@@ -443,7 +444,8 @@ system to create HTML pages which would be hosted on the webpage of flang and
 updated periodically.
 
 If you would like to generate and view the HTML locally:
-- Install [Sphinx](http://sphinx-doc.org/), including the [sphinx-markdown-tables](https://pypi.org/project/sphinx-markdown-tables/) extension.
+- Install [Sphinx](http://sphinx-doc.org/), and the required extensions
+  using `pip install --user -r ~/llvm-projects/docs/requirements.txt`
 - Pass `-DLLVM_ENABLE_SPHINX=ON -DSPHINX_WARNINGS_AS_ERRORS=OFF` to the cmake command.
 
 ```bash

diff --git a/flang/docs/IORuntimeInternals.md b/flang/docs/IORuntimeInternals.md
@@ -8,9 +8,10 @@
 
 # Fortran I/O Runtime Library Internal Design
 
-```eval_rst
-.. contents::
-   :local:
+```{contents}
+---
+local:
+---
 ```
 
 This note is meant to be an overview of the design of the *implementation*

diff --git a/flang/docs/ImplementingASemanticCheck.md b/flang/docs/ImplementingASemanticCheck.md
@@ -7,9 +7,10 @@
 -->
 # How to implement a Sematic Check in Flang
 
-```eval_rst
-.. contents::
-   :local:
+```{contents}
+---
+local:
+---
 ```
 
 I recently added a semantic check to the Flang compiler front end.  This document

diff --git a/flang/docs/IntrinsicTypes.md b/flang/docs/IntrinsicTypes.md
@@ -8,9 +8,10 @@
 
 # Implementation of `Intrinsic` types in f18
 
-```eval_rst
-.. contents::
-   :local:
+```{contents}
+---
+local:
+---
 ```
 
 Intrinsic types are integer, real, complex, character, and logical.

diff --git a/flang/docs/Intrinsics.md b/flang/docs/Intrinsics.md
@@ -8,9 +8,10 @@
 
 # A categorization of standard (2018) and extended Fortran intrinsic procedures
 
-```eval_rst
-.. contents::
-   :local:
+```{contents}
+---
+local:
+---
 ```
 
 This note attempts to group the intrinsic procedures of Fortran into categories