diff --git a/.github/templates/validate-sphinx-docs/action.yml b/.github/templates/validate-sphinx-docs/action.yml new file mode 100644 index 0000000000000..b087ef7e6ab81 --- /dev/null +++ b/.github/templates/validate-sphinx-docs/action.yml @@ -0,0 +1,14 @@ +name: validate-sphinx-docs + +inputs: + path: + required: true + +runs: + using: "composite" + steps: + - name: Validate Sphinx documentation in ${{ inputs.path }} + uses: cor3ntin/sphinx-action@main + with: + docs-folder: ${{ inputs.path }} + build-command: "sphinx-build -b html . _build -Dsuppress_warnings=toc.not_readable,ref.doc" diff --git a/.github/workflows/documentation-checks.yml b/.github/workflows/documentation-checks.yml new file mode 100644 index 0000000000000..8937d34c926a9 --- /dev/null +++ b/.github/workflows/documentation-checks.yml @@ -0,0 +1,74 @@ +name: Checking Documentation + +on: + pull_request: + path: '**/docs/**/*.rst' + +jobs: + verify-sphinx-documentation: + runs-on: ubuntu-latest + env: + SPHINX_ACTION: "./.github/templates/validate-sphinx-docs" + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Check Bolt documentation + uses: "./.github/templates/validate-sphinx-docs" + with: + path: ./bolt/docs + + - name: Check Clang documentation + uses: "./.github/templates/validate-sphinx-docs" + with: + path: ./clang/docs + + - name: Check Clang Tools documentation + uses: "./.github/templates/validate-sphinx-docs" + with: + path: ./clang-tools-extra/docs + + - name: Check Flang documentation + uses: "./.github/templates/validate-sphinx-docs" + with: + path: ./flang/docs + + - name: Check libc documentation + uses: "./.github/templates/validate-sphinx-docs" + with: + path: ./libc/docs + + - name: Check libcxx documentation + uses: "./.github/templates/validate-sphinx-docs" + with: + path: ./libcxx/docs + + - name: Check libunwind documentation + uses: "./.github/templates/validate-sphinx-docs" + with: + path: ./libunwind/docs + + - name: Check lldb documentation + uses: "./.github/templates/validate-sphinx-docs" + with: + path: ./lldb/docs + + - name: Check lld documentation + uses: "./.github/templates/validate-sphinx-docs" + with: + path: ./lld/docs + + - name: Check llvm documentation + uses: "./.github/templates/validate-sphinx-docs" + with: + path: ./llvm/docs + + - name: Check openmp documentation + uses: "./.github/templates/validate-sphinx-docs" + with: + path: ./openmp/docs + + - name: Check polly documentation + uses: "./.github/templates/validate-sphinx-docs" + with: + path: ./polly/docs diff --git a/.github/workflows/release-tasks.yml b/.github/workflows/release-tasks.yml index 5604b48857dbe..afd3a7d97f00c 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/ReleaseNotes.rst b/clang/docs/ReleaseNotes.rst index acce35e231e71..c1b1a52c45a11 100644 --- a/clang/docs/ReleaseNotes.rst +++ b/clang/docs/ReleaseNotes.rst @@ -16,7 +16,7 @@ Written by the `LLVM Team `_ `the Releases Page `_. Introduction -============ +======= This document contains the release notes for the Clang C/C++/Objective-C frontend, part of the LLVM Compiler Infrastructure, release |release|. Here we @@ -215,7 +215,7 @@ Bug Fixes in This Version - Support MSVC predefined macro expressions in constant expressions and in local structs. - Correctly parse non-ascii identifiers that appear immediately after a line splicing - (`#65156 `_`) + (`#65156 `) Bug Fixes to Compiler Builtins ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/clang/docs/conf.py b/clang/docs/conf.py index de31a5dcd068e..ca310026f53e2 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 117cd1f1c97ae..9950c9176c387 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 8d6434afe84ef..add5985d5b40b 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 db9bd26bb3d9a..9998694932d68 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 206f72285a830..5a11cc26f0e75 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 ef3784959b4f3..4f9e7d7768e7f 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 #===------------------------------------------------------------------------===#