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 <[email protected]> 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" _______________________________________________ cfe-commits mailing list [email protected] https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits
