[libc-commits] [clang] [clang-tools-extra] [libc] [libcxx] [lld] [lldb] [llvm] [polly] [docs] Require MyST for Sphinx documentation builds (PR #223829)
Reid Kleckner via libc-commits
libc-commits at lists.llvm.org
Tue Sep 15 13:59:58 PDT 2026
https://github.com/rnk created https://github.com/llvm/llvm-project/pull/223829
Fedora plans to use the man pages we build in our binary releases for its packaging:
https://discourse.llvm.org/t/rfc-make-myst-markdown-the-llvm-docs-format-rip-rest/90840/37
I'm assuming that other distributions are either going to be able to install the necessary Python modules that we depend on (myst_parser etc), or will be able to adopt similar strategies. Therefore, I think we can remove this enum and associated complexity.
Assisted-by: codex
>From 1f823037abbc5c140770003bc1097e8ee1e8b599 Mon Sep 17 00:00:00 2001
From: Reid Kleckner <rkleckner at nvidia.com>
Date: Tue, 15 Sep 2026 20:29:37 +0000
Subject: [PATCH] [docs] Require MyST for Sphinx documentation builds
Fedora plans to use the man pages we build in our binary releases for
its packaging:
https://discourse.llvm.org/t/rfc-make-myst-markdown-the-llvm-docs-format-rip-rest/90840/37
I'm assuming that other distributions are either going to be able to
install the necessary Python modules that we depend on (myst_parser
etc), or will be able to adopt similar strategies. Therefore, I think we
can remove this enum and associated complexity.
Assisted-by: codex
---
clang-tools-extra/docs/conf.py | 2 +-
clang/docs/analyzer/conf.py | 2 +-
clang/docs/conf.py | 2 +-
libc/docs/conf.py | 2 +-
libcxx/docs/conf.py | 2 +-
lld/docs/conf.py | 2 +-
lldb/docs/conf.py | 2 +-
llvm/docs/conf.py | 2 +-
polly/docs/conf.py | 2 +-
utils/docs/llvm_sphinx/__init__.py | 29 ++++-------------------------
10 files changed, 13 insertions(+), 34 deletions(-)
diff --git a/clang-tools-extra/docs/conf.py b/clang-tools-extra/docs/conf.py
index a80bbcf8638b59..59a64efec97887 100644
--- a/clang-tools-extra/docs/conf.py
+++ b/clang-tools-extra/docs/conf.py
@@ -16,7 +16,7 @@
from llvm_sphinx import * # see llvm-project/utils/docs/README.md
-globals().update(common_conf(tags, markdown=Markdown.EXCEPT_MAN))
+globals().update(common_conf(tags))
# -- General configuration -----------------------------------------------------
diff --git a/clang/docs/analyzer/conf.py b/clang/docs/analyzer/conf.py
index 38cf375920bde2..dfa644cb55438d 100644
--- a/clang/docs/analyzer/conf.py
+++ b/clang/docs/analyzer/conf.py
@@ -16,7 +16,7 @@
from llvm_sphinx import * # see llvm-project/utils/docs/README.md
-globals().update(common_conf(tags, markdown=Markdown.NEVER))
+globals().update(common_conf(tags))
# 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
diff --git a/clang/docs/conf.py b/clang/docs/conf.py
index 122b3f50878a10..1280d70b3be71e 100644
--- a/clang/docs/conf.py
+++ b/clang/docs/conf.py
@@ -17,7 +17,7 @@
from llvm_sphinx import * # see llvm-project/utils/docs/README.md
-globals().update(common_conf(tags, markdown=Markdown.EXCEPT_MAN))
+globals().update(common_conf(tags))
myst_enable_extensions += ["deflist"]
diff --git a/libc/docs/conf.py b/libc/docs/conf.py
index 47d0d6c917a888..3aa9738922b954 100644
--- a/libc/docs/conf.py
+++ b/libc/docs/conf.py
@@ -15,7 +15,7 @@
from llvm_sphinx import * # see llvm-project/utils/docs/README.md
-globals().update(common_conf(tags, markdown=Markdown.EXCEPT_MAN))
+globals().update(common_conf(tags))
# -- General configuration -----------------------------------------------------
diff --git a/libcxx/docs/conf.py b/libcxx/docs/conf.py
index 98aa52edd5d2e2..691411af931761 100644
--- a/libcxx/docs/conf.py
+++ b/libcxx/docs/conf.py
@@ -15,7 +15,7 @@
from llvm_sphinx import * # see llvm-project/utils/docs/README.md
-globals().update(common_conf(tags, markdown=Markdown.NEVER))
+globals().update(common_conf(tags))
# -- General configuration -----------------------------------------------------
diff --git a/lld/docs/conf.py b/lld/docs/conf.py
index e97604e1f777fe..b3cad845938e9e 100644
--- a/lld/docs/conf.py
+++ b/lld/docs/conf.py
@@ -15,7 +15,7 @@
from llvm_sphinx import * # see llvm-project/utils/docs/README.md
-globals().update(common_conf(tags, markdown=Markdown.EXCEPT_MAN))
+globals().update(common_conf(tags))
# -- General configuration -----------------------------------------------------
diff --git a/lldb/docs/conf.py b/lldb/docs/conf.py
index e8d71ce4c4e63e..541ec3f9fd0cd6 100644
--- a/lldb/docs/conf.py
+++ b/lldb/docs/conf.py
@@ -16,7 +16,7 @@
from llvm_sphinx import * # see llvm-project/utils/docs/README.md
-globals().update(common_conf(tags, markdown=Markdown.EXCEPT_MAN))
+globals().update(common_conf(tags))
building_man_page = tags.has("builder-man")
diff --git a/llvm/docs/conf.py b/llvm/docs/conf.py
index 0a618b2643e0a4..f14582ac274d36 100644
--- a/llvm/docs/conf.py
+++ b/llvm/docs/conf.py
@@ -16,7 +16,7 @@
from llvm_sphinx import * # see llvm-project/utils/docs/README.md
-globals().update(common_conf(tags, markdown=Markdown.EXCEPT_MAN))
+globals().update(common_conf(tags))
# -- General configuration -----------------------------------------------------
diff --git a/polly/docs/conf.py b/polly/docs/conf.py
index 7d3ece63534a58..3a4b4b280ef448 100644
--- a/polly/docs/conf.py
+++ b/polly/docs/conf.py
@@ -16,7 +16,7 @@
from llvm_sphinx import * # see llvm-project/utils/docs/README.md
-globals().update(common_conf(tags, markdown=Markdown.NEVER))
+globals().update(common_conf(tags))
# -- General configuration -----------------------------------------------------
diff --git a/utils/docs/llvm_sphinx/__init__.py b/utils/docs/llvm_sphinx/__init__.py
index 2693218931b434..7bddfa905ce07b 100644
--- a/utils/docs/llvm_sphinx/__init__.py
+++ b/utils/docs/llvm_sphinx/__init__.py
@@ -17,42 +17,21 @@
"""
-import sys
from pathlib import Path
from typing import Any, Dict, Iterable, Optional
-from enum import Enum, auto
+
from sphinx.util.tags import Tags
-from llvm_sphinx.help import venv_help
_SHARED_STATIC_DIR = Path(__file__).parent / "_static"
-class Markdown(Enum):
- ALWAYS = auto()
- EXCEPT_MAN = auto()
- NEVER = auto()
-
-
-def common_conf(tags: Tags, markdown=Markdown.ALWAYS) -> Dict[str, Any]:
+def common_conf(tags: Tags) -> Dict[str, Any]:
# If your documentation needs a minimal Sphinx version, state it here.
# needs_sphinx = '1.0'
# The encoding of source files.
# source_encoding = 'utf-8-sig'
- extensions = ["llvm_sphinx.ext.mlir_pygments"]
- source_suffix = {".rst": "restructuredtext"}
- if markdown != Markdown.NEVER:
- # When building man pages, we do not use the markdown pages,
- # So, we can continue without the myst_parser dependencies.
- # Doing so reduces dependencies of some packaged llvm distributions.
- try:
- import myst_parser
- except ImportError as err:
- if markdown == Markdown.ALWAYS or not tags.has("builder-man"):
- print(venv_help(err), file=sys.stderr)
- raise
- else:
- extensions.append("myst_parser")
- source_suffix[".md"] = "markdown"
+ extensions = ["llvm_sphinx.ext.mlir_pygments", "myst_parser"]
+ source_suffix = {".rst": "restructuredtext", ".md": "markdown"}
myst_enable_extensions = ["substitution", "colon_fence"]
myst_heading_anchors = 6
myst_heading_slug_func = "llvm_sphinx.make_slug"
More information about the libc-commits
mailing list