[Github] Validate documentation

Author: cor3ntin

.github/templates/validate-sphinx-docs/action.yml

@@ -0,0 +1,15 @@
+name: Documentation Checks
+
+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 }}
+      # We exclude references errors so that we do not have to build the table gen documentation
+      build-command: "sphinx-build -b html . _build -Dsuppress_warnings=toc.not_readable,ref.*"

.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

.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

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/conf.py

@@ -9,24 +9,14 @@
 # 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.
 # sys.path.insert(0, os.path.abspath('.'))
 
 # -- 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'

lldb/docs/conf.py

@@ -10,10 +10,12 @@
 #
 # All configuration values have a default; values that are commented out
 # serve to show the default.
+import pathlib
 import sys, os, re, shutil
 from datetime import date
 
 building_man_page = tags.has("builder-man")
+SWIG_MODULE = os.getenv("LLDB_SWIG_MODULE")
 
 # For the website we need to setup the path to the generated LLDB module that
 # we can generate documentation for its API.
@@ -24,10 +26,11 @@
 
     # Add the current directory that contains the mock _lldb native module which
     # is imported by the `lldb` module.
-    sys.path.insert(0, os.path.abspath("."))
+    sys.path.insert(0, pathlib.Path(__file__).parent.resolve())
     # Add the build directory that contains the `lldb` module. LLDB_SWIG_MODULE is
     # set by CMake.
-    sys.path.insert(0, os.getenv("LLDB_SWIG_MODULE"))
+    if SWIG_MODULE:
+        sys.path.insert(0, SWIG_MODULE)
 
 # Put the generated Python API documentation in the 'python_api' folder. This
 # also defines the URL these files will have in the generated website.
@@ -113,7 +116,7 @@
 # Without this we will get a lot of warnings about doc pages that aren't
 # included by any doctree (as the manpage ignores those pages but they are
 # potentially still around from a previous website generation).
-if building_man_page:
+if not SWIG_MODULE or building_man_page :
     exclude_patterns.append(automodapi_toctreedirnm)
 # Use the recommended 'any' rule so that referencing SB API classes is possible
 # by just writing `SBData`.
@@ -176,7 +179,7 @@
 
 # If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
 # using the given strftime format.
-html_last_updated_fmt = "%b %d, %Y"
+# html_last_updated_fmt = "%b %d, %Y"
 
 # If true, SmartyPants will be used to convert quotes and dashes to
 # typographically correct entities.

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
 

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:
 

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'

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
 #===------------------------------------------------------------------------===#