[Documentation] Replace recommonmark by myst-parser by cor3ntin · Pull Request #65664 · llvm/llvm-project (original) (raw)

@llvm/pr-subscribers-openacc

ChangesThis 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!

Patch is 24.25 KiB, truncated to 20.00 KiB below, full version: https://github.com/llvm/llvm-project/pull/65664.diff

45 Files Affected:

diff --git a/.github/workflows/release-tasks.yml b/.github/workflows/release-tasks.yml index 013714005d1124e..656b8c49c556173 100644 --- a/.github/workflows/release-tasks.yml +++ b/.github/workflows/release-tasks.yml @@ -24,6 +24,9 @@ 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 @@ -31,14 +34,9 @@ jobs: doxygen
graphviz
python3-github
- python3-recommonmark
- python3-sphinx
ninja-build
texlive-font-utils - pip3 install --user sphinx-markdown-tables

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

+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 index f2805c731477160..652b766541fd467 100644 --- 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 index 9e61abe5670f370..8de1c760d281a04 100644 --- 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 index 996c490e7e19481..4a11626e3870a65 100644 --- 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 index 9e0120d2e4c5e69..b20364b03e060a4 100644 --- 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 index d4d692a522d0465..04579130aa7cbe9 100644 --- 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 index cbf689f199ef52f..f518dc00ed8e817 100644 --- 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 index 603dd8848ba1b99..4e1d40774d6db21 100644 --- 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 index 6faa1811fd6d0d1..d035658b90acd1c 100644 --- 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 index dcdecf1b77f6545..35eb4c4798d6d74 100644 --- 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 index 5c945cbf1300141..03357f21fd07eb4 100644 --- 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 index 14f6899e2c1c575..bd1008af86f6b4e 100644 --- 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 index 49e78a10fa6bcdb..df9b4fd4cade4a0 100644 --- 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 index 7fec24c6e783840..bea49eae37a38ab 100644 --- 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 index da4ae8c91397333..6e48a332eafcc97 100644 --- 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 index 184af189eee13a6..2c43a56e01502ef 100644 --- 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 index 572433ab7c15402..50c83ed7e9bfe2e 100644 --- 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 index ed322bd06fbf937..f9f8f6416b37aa1 100644 --- 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 index a6fffc8937ed808..62459e6a7b7020e 100644 --- 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 is a diff --git a/flang/docs/GettingInvolved.md b/flang/docs/GettingInvolved.md index 074564ceb355621..09f10fac7cf1b4c 100644 --- 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 index f470067e07f6093..f5319a7c38541fd 100644 --- 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, including the sphinx-markdown-tables extension. +- Install Sphinx, 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 index 2748fcf16fa3c21..d4e321348b2debf 100644 --- 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 index 4e19b041c392017..5b583d4f8031b89 100644 --- 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 index 3706b3f3e290ad0..fa9d64b377cdbc3 100644 --- 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 index 0128b4c96a5820f..ab0a940e53e5538 100644 --- 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 diff --git a/flang/docs/LabelResolution.md b/flang/docs/LabelResolution.md index c1227a8bc35a10b..5e2fbe72172cc8d 100644 --- a/flang/docs/LabelResolution.md +++ b/flang/docs/LabelResolution.md @@ -8,9 +8,10 @@ # Semantics: Resolving Labels and Construct Names -eval_rst -.. contents:: - :local: +{contents} +--- +local: +--- ## Overview diff --git a/flang/docs/ModFiles.md b/flang/docs/ModFiles.md index ccb849ab0decd96..e55d72fa3a705bb 100644 --- a/flang/docs/ModFiles.md +++ b/flang/docs/ModFiles.md @@ -8,9 +8,10 @@ # Module Files -eval_rst -.. contents:: - :local: +{contents} +--- +local: +--- Module files hold information from a module that is necessary to compile diff --git a/flang/docs/OpenACC.md b/flang/docs/OpenACC.md index 2becfb1aeac1a63..80258041a627b93 100644 --- a/flang/docs/OpenACC.md +++ b/flang/docs/OpenACC.md @@ -8,9 +8,10 @@ # OpenACC in Flang -eval_rst -.. contents:: - :local: +{contents} +--- +local: +--- ## Intentional deviation from the specification diff --git a/flang/docs/OpenMP-semantics.md b/flang/docs/OpenMP-semantics.md index 6f42b44726e9378..57938afba62ddb3 100644 --- a/flang/docs/OpenMP-semantics.md +++ b/flang/docs/OpenMP-semantics.md @@ -8,9 +8,10 @@ # OpenMP Semantic Analysis -eval_rst -.. contents:: - :local: +{contents} +--- +local: +--- ## OpenMP for F18 diff --git a/flang/docs/Overview.md b/flang/docs/Overview.md index a65bd9c84780098..561e9cfcf95c34d 100644 --- a/flang/docs/Overview.md +++ b/flang/docs/Overview.md @@ -8,9 +8,10 @@ # Overview of Compiler Phases -eval_rst -.. contents:: - :local: +{contents} +--- +local: +--- The Flang compiler transforms Fortran source code into an executable file. This transformation proceeds in three high level phases -- analysis, lowering, diff --git a/flang/docs/ParserCombinators.md b/flang/docs/ParserCombinators.md index b00347396471edd..2c5652ec36138ba 100644 --- a/flang/docs/ParserCombinators.md +++ b/flang/docs/ParserCombinators.md @@ -8,9 +8,10 @@ # Parser Combinators -eval_rst -.. contents:: - :local: +{contents} +--- +local: +--- This document is a primer on Parser Combinators and their use in Flang. diff --git a/flang/docs/Parsing.md b/flang/docs/Parsing.md index e960c33dcbf34c5..bedc1ea6aee9789 100644 --- a/flang/docs/Parsing.md +++ b/flang/docs/Parsing.md @@ -8,9 +8,10 @@ # The F18 Parser -eval_rst -.. contents:: - :local: +{contents} +--- +local: +--- This program source code implements a parser for the Fortran programming diff --git a/flang/docs/Preprocessing.md b/flang/docs/Preprocessing.md index 620fa568d1a7390..7465ff538e42e2c 100644 --- a/flang/docs/Preprocessing.md +++ b/flang/docs/Preprocessing.md @@ -8,9 +8,10 @@ # Fortran Preprocessing -eval_rst -.. contents:: - :local: +{contents} +--- +local: +--- ## Behavior common to (nearly) all compilers: diff --git a/flang/docs/RuntimeDescriptor.md b/flang/docs/RuntimeDescriptor.md index f0bbd2e3fedaf6f..e6ce825b044022c 100644 --- a/flang/docs/RuntimeDescriptor.md +++ b/flang/docs/RuntimeDescriptor.md @@ -8,9 +8,10 @@ # Runtime Descriptors -eval_rst -.. contents:: - :local: +{contents} +--- +local: +--- ## Concept diff --git a/flang/docs/RuntimeTypeInfo.md b/flang/docs/RuntimeTypeInfo.md index 391b6ea5f88b773..8bd5551c6667875 100644 --- a/flang/docs/RuntimeTypeInfo.md +++ b/flang/docs/RuntimeTypeInfo.md @@ -8,9 +8,10 @@ # The derived type runtime information table -eval_rst -.. contents:: - :local: +{contents} +--- +local: +--- ## Overview diff --git a/flang/docs/Semantics.md b/flang/docs/Semantics.md index 270a1033c4c9580..0fc1ebe4cff1d47 100644 --- a/flang/docs/Semantics.md +++ b/flang/docs/Semantics.md @@ -8,9 +8,10 @@ # Semantic Analysis -eval_rst -.. contents:: - :local: +{contents} +--- +local: +--- The semantic analysis pass determines if a syntactically correct Fortran diff --git a/flang/docs/conf.py b/flang/docs/conf.py index 117cd1f1c97aea2..dac089eeb37e9f3 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,65 +17,20 @@ # -- 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

-extensions = ["sphinx.ext.todo", "sphinx.ext.mathjax", "sphinx.ext.intersphinx"] +extensions = ["myst_parser", + "sphinx.ext.todo", + "sphinx.ext.mathjax", + "sphinx.ext.intersphinx", + "sphinx.ext.autodoc"] # 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