[clang] [Documentation] Replace recommonmark by myst-parser (PR #65664)
via cfe-commits
cfe-commits at lists.llvm.org
Thu Sep 14 04:18:29 PDT 2023
https://github.com/cor3ntin updated https://github.com/llvm/llvm-project/pull/65664:
>From 144892d671cac5851096ca3521ce23ad736b48dc 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 1/3] [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 013714005d1124e..d0da5a76c0c1cf0 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
#===------------------------------------------------------------------------===#
>From c25d901361c6e7c5d5ba75e34ab68990af77e898 Mon Sep 17 00:00:00 2001
From: Corentin Jabot <corentinjabot at gmail.com>
Date: Tue, 12 Sep 2023 11:36:32 +0200
Subject: [PATCH 2/3] Put the documentation requirements in a requirement
files.
---
.github/workflows/release-tasks.yml | 10 ++++------
llvm/docs/SphinxQuickstartTemplate.rst | 14 +++-----------
llvm/docs/requirements.txt | 5 +++++
llvm/utils/release/build-docs.sh | 8 ++++----
4 files changed, 16 insertions(+), 21 deletions(-)
create mode 100644 llvm/docs/requirements.txt
diff --git a/.github/workflows/release-tasks.yml b/.github/workflows/release-tasks.yml
index d0da5a76c0c1cf0..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 at v4
+
- name: Install Dependencies
run: |
sudo apt-get update
@@ -31,14 +34,9 @@ jobs:
doxygen \
graphviz \
python3-github \
- python3-myst-parser \
- python3-sphinx \
ninja-build \
texlive-font-utils
- pip3 install --user sphinx-markdown-tables
-
- - name: Checkout LLVM
- uses: actions/checkout at v4
+ pip3 install --user -r ./llvm/docs/requirements.txt
- name: Create Release
run: |
diff --git a/llvm/docs/SphinxQuickstartTemplate.rst b/llvm/docs/SphinxQuickstartTemplate.rst
index 9998694932d686c..956adabce78c24b 100644
--- a/llvm/docs/SphinxQuickstartTemplate.rst
+++ b/llvm/docs/SphinxQuickstartTemplate.rst
@@ -171,20 +171,12 @@ Generating the documentation
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
-`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 python3-myst-parser
-
-On Ubuntu use pip to get an up-to-date version of python3-myst-parser:
+you need to install `Sphinx`_ and the necessary extensions
+using the following command inside the ``llvm-project`` checkout:
.. code-block:: console
- sudo pip install sphinx myst-parser
+ pip install --user -r ./llvm/docs/requirements.txt
Then run cmake to build the documentation inside the ``llvm-project`` checkout:
diff --git a/llvm/docs/requirements.txt b/llvm/docs/requirements.txt
new file mode 100644
index 000000000000000..fbfd258178c8ecb
--- /dev/null
+++ b/llvm/docs/requirements.txt
@@ -0,0 +1,5 @@
+sphinx
+myst-parser
+sphinx-markdown-tables
+sphinx-automodapi
+furo
diff --git a/llvm/utils/release/build-docs.sh b/llvm/utils/release/build-docs.sh
index 4f9e7d7768e7f54..fd226434b95a3bf 100755
--- a/llvm/utils/release/build-docs.sh
+++ b/llvm/utils/release/build-docs.sh
@@ -11,13 +11,13 @@
#
# Required Packages:
# * Fedora:
-# * dnf install doxygen python3-sphinx texlive-epstopdf ghostscript \
+# * dnf install doxygen texlive-epstopdf ghostscript \
# ninja-build gcc-c++
-# * pip install sphinx-markdown-tables
+# * pip install --user -r ./llvm/docs/requirements.txt
# * Ubuntu:
-# * apt-get install doxygen sphinx-common python3-myst-parser \
+# * apt-get install doxygen \
# ninja-build graphviz texlive-font-utils
-# * pip install sphinx-markdown-tables
+# * pip install --user -r ./llvm/docs/requirements.txt
#===------------------------------------------------------------------------===#
set -ex
>From 1f58fe78d12ce5cdb29558531cff7297cfb6ca1f Mon Sep 17 00:00:00 2001
From: Corentin Jabot <corentinjabot at gmail.com>
Date: Thu, 14 Sep 2023 10:57:03 +0200
Subject: [PATCH 3/3] - Fix flang content directives directives - Removed
uneeded sphinx-markdown-tables package (myst handles table natively) - Fix
llvm docs extension configuration
---
flang/docs/Aliasing.md | 7 ++++---
flang/docs/ArrayComposition.md | 7 ++++---
flang/docs/BijectiveInternalNameUniquing.md | 7 ++++---
flang/docs/C++17.md | 7 ++++---
flang/docs/C++style.md | 7 ++++---
flang/docs/Calls.md | 7 ++++---
flang/docs/Character.md | 7 ++++---
flang/docs/ComplexOperations.md | 4 ++--
flang/docs/ControlFlowGraph.md | 7 ++++---
flang/docs/DesignGuideline.md | 7 ++++---
flang/docs/DoConcurrent.md | 7 ++++---
flang/docs/Extensions.md | 7 ++++---
flang/docs/FIRArrayOperations.md | 7 ++++---
flang/docs/FlangDriver.md | 7 ++++---
flang/docs/FortranFeatureHistory.md | 7 ++++---
flang/docs/FortranForCProgrammers.md | 7 ++++---
flang/docs/FortranIR.md | 7 ++++---
flang/docs/FortranLLVMTestSuite.md | 7 ++++---
flang/docs/GettingInvolved.md | 7 ++++---
flang/docs/GettingStarted.md | 10 ++++++----
flang/docs/IORuntimeInternals.md | 7 ++++---
flang/docs/ImplementingASemanticCheck.md | 7 ++++---
flang/docs/IntrinsicTypes.md | 7 ++++---
flang/docs/Intrinsics.md | 7 ++++---
flang/docs/LabelResolution.md | 7 ++++---
flang/docs/ModFiles.md | 7 ++++---
flang/docs/OpenACC.md | 7 ++++---
flang/docs/OpenMP-semantics.md | 7 ++++---
flang/docs/Overview.md | 7 ++++---
flang/docs/ParserCombinators.md | 7 ++++---
flang/docs/Parsing.md | 7 ++++---
flang/docs/Preprocessing.md | 7 ++++---
flang/docs/RuntimeDescriptor.md | 7 ++++---
flang/docs/RuntimeTypeInfo.md | 7 ++++---
flang/docs/Semantics.md | 7 ++++---
flang/docs/conf.py | 10 +++++-----
flang/docs/index.md | 8 ++++----
llvm/docs/GwpAsan.rst | 1 +
llvm/docs/conf.py | 11 ++---------
llvm/docs/requirements.txt | 1 -
40 files changed, 152 insertions(+), 124 deletions(-)
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](https://github.com/llvm/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](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
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 9950c9176c38798..dac089eeb37e9f3 100644
--- a/flang/docs/conf.py
+++ b/flang/docs/conf.py
@@ -21,17 +21,17 @@
# needs_sphinx = '1.0'
# Add any Sphinx extension module names here, as strings. They can be extensions
# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-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"]
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/flang/docs/index.md b/flang/docs/index.md
index b91fb453ffeb6bb..0e4b47995e271f4 100644
--- a/flang/docs/index.md
+++ b/flang/docs/index.md
@@ -9,7 +9,7 @@ is capable of generating executables for a number of examples, some
functionality is still missing. See [GettingInvolved](GettingInvolved) for tips
on how to get in touch with us and to learn more about the current status.
-```eval_rst
+```{eval-rst}
.. toctree::
:titlesonly:
@@ -18,7 +18,7 @@ on how to get in touch with us and to learn more about the current status.
# Contributing to Flang
-```eval_rst
+```{eval-rst}
.. toctree::
:titlesonly:
@@ -33,7 +33,7 @@ on how to get in touch with us and to learn more about the current status.
# Design Documents
-```eval_rst
+```{eval-rst}
.. toctree::
:titlesonly:
@@ -70,7 +70,7 @@ on how to get in touch with us and to learn more about the current status.
# Indices and tables
-```eval_rst
+```{eval-rst}
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`
diff --git a/llvm/docs/GwpAsan.rst b/llvm/docs/GwpAsan.rst
index 293f75d71ac3f50..136506483101ed3 100644
--- a/llvm/docs/GwpAsan.rst
+++ b/llvm/docs/GwpAsan.rst
@@ -257,6 +257,7 @@ anything fails. This results in the following output:
.. code:: console
+
$ cat my_gwp_asan_error.txt | symbolize.sh
|
| *** GWP-ASan detected a memory error ***
diff --git a/llvm/docs/conf.py b/llvm/docs/conf.py
index 5a11cc26f0e757b..efc77dc7c71abfc 100644
--- a/llvm/docs/conf.py
+++ b/llvm/docs/conf.py
@@ -26,22 +26,15 @@
# Add any Sphinx extension module names here, as strings. They can be extensions
# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = ["sphinx.ext.intersphinx", "sphinx.ext.todo"]
+extensions = ["myst_parser", "sphinx.ext.intersphinx", "sphinx.ext.todo"]
# Add any paths that contain templates here, relative to this directory.
templates_path = ["_templates"]
-# The suffix of source filenames.
-source_suffix = {
- ".rst": "restructuredtext",
-}
+source_suffix = ['.rst', '.md']
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/requirements.txt b/llvm/docs/requirements.txt
index fbfd258178c8ecb..4d08973d2558597 100644
--- a/llvm/docs/requirements.txt
+++ b/llvm/docs/requirements.txt
@@ -1,5 +1,4 @@
sphinx
myst-parser
-sphinx-markdown-tables
sphinx-automodapi
furo
More information about the cfe-commits
mailing list