https://github.com/rnk updated https://github.com/llvm/llvm-project/pull/222196
>From 40fc345bcbbed0a4eaa74f6ca3d0734321d63a05 Mon Sep 17 00:00:00 2001 From: Reid Kleckner <[email protected]> Date: Tue, 11 Aug 2026 23:45:02 +0000 Subject: [PATCH 1/4] [clang-tools-extra][docs] Use Furo theme Adopt the shared Furo configuration for the clang-tools-extra documentation. Remove page-local TOCs mechanically with the included `utils/docs/remove_page_tocs.py` helper. Clang Furo PR: https://github.com/llvm/llvm-project/pull/214869 RFC: https://discourse.llvm.org/t/rfc-use-furo-theme-for-clang-docs/91505/7 Preview: https://clangdocs.staging.reidkleckner.dev/after/clang-tools-extra/docs/ --- clang-tools-extra/Maintainers.md | 3 - clang-tools-extra/docs/ReleaseNotes.md | 4 -- .../docs/_static/clang-tools-extra-styles.css | 21 ++++++ .../docs/clang-change-namespace.md | 2 - clang-tools-extra/docs/clang-doc.md | 2 - clang-tools-extra/docs/clang-include-fixer.md | 2 - .../docs/clang-reorder-fields.md | 2 - clang-tools-extra/docs/clang-tidy/index.rst | 2 - clang-tools-extra/docs/conf.py | 20 ++---- utils/docs/remove_page_tocs.py | 72 +++++++++++++++++++ 10 files changed, 100 insertions(+), 30 deletions(-) create mode 100644 utils/docs/remove_page_tocs.py diff --git a/clang-tools-extra/Maintainers.md b/clang-tools-extra/Maintainers.md index 57f7d96213d75..8830b86e09d7d 100644 --- a/clang-tools-extra/Maintainers.md +++ b/clang-tools-extra/Maintainers.md @@ -4,9 +4,6 @@ This file is a list of the [maintainers](https://llvm.org/docs/DeveloperPolicy.html#maintainers) for the [Extra Clang Tools](https://clang.llvm.org/extra/index.html) project. -```{contents} Table of Contents -:depth: 2 -``` # Active Maintainers diff --git a/clang-tools-extra/docs/ReleaseNotes.md b/clang-tools-extra/docs/ReleaseNotes.md index 93fbe57a58321..c8030b55376f3 100644 --- a/clang-tools-extra/docs/ReleaseNotes.md +++ b/clang-tools-extra/docs/ReleaseNotes.md @@ -12,10 +12,6 @@ myst: {#extra-clang-tools-release-releasenotestitle} # Extra Clang Tools {{env.config.release}} {{ (('(In-Progress) ' if env.app.tags.has('PreRelease') else '') ~ 'Release Notes') }} -```{contents} -:depth: 3 -:local: true -``` Written by the [LLVM Team](https://llvm.org/) diff --git a/clang-tools-extra/docs/_static/clang-tools-extra-styles.css b/clang-tools-extra/docs/_static/clang-tools-extra-styles.css index 1a6cd710e483a..7fe4207cf680e 100644 --- a/clang-tools-extra/docs/_static/clang-tools-extra-styles.css +++ b/clang-tools-extra/docs/_static/clang-tools-extra-styles.css @@ -21,3 +21,24 @@ details summary:hover { background-color: rgba(50, 150, 220, 0.2); cursor: pointer; } + +/* Use the full viewport on ordinary desktop displays, where Furo's fixed + content width leaves little room after both sidebars. Once the content area + reaches 90em (84em plus padding), grow symmetric outer margins instead. */ +@media (min-width: 67em) { + .page .sidebar-drawer { + width: max(15em, calc(50% - 45em)); + } + + .main > .content { + width: min(84em, calc(100vw - 36em)); + } +} + +/* Furo moves the page-local TOC into a drawer below 82em, freeing its 15em + column for the main content. */ +@media (min-width: 67em) and (max-width: 82em) { + .main > .content { + width: calc(100vw - 21em); + } +} diff --git a/clang-tools-extra/docs/clang-change-namespace.md b/clang-tools-extra/docs/clang-change-namespace.md index b44c1a359f8ac..7e5eb3fb11268 100644 --- a/clang-tools-extra/docs/clang-change-namespace.md +++ b/clang-tools-extra/docs/clang-change-namespace.md @@ -1,7 +1,5 @@ # Clang-Change-Namespace -```{contents} -``` ```{toctree} :maxdepth: 1 diff --git a/clang-tools-extra/docs/clang-doc.md b/clang-tools-extra/docs/clang-doc.md index 11aa4ddaf943d..f24a4697a4991 100644 --- a/clang-tools-extra/docs/clang-doc.md +++ b/clang-tools-extra/docs/clang-doc.md @@ -1,7 +1,5 @@ # Clang-Doc -```{contents} -``` ```{toctree} :maxdepth: 1 diff --git a/clang-tools-extra/docs/clang-include-fixer.md b/clang-tools-extra/docs/clang-include-fixer.md index 6be1251457310..b16c46f4553b0 100644 --- a/clang-tools-extra/docs/clang-include-fixer.md +++ b/clang-tools-extra/docs/clang-include-fixer.md @@ -1,7 +1,5 @@ # Clang-Include-Fixer -```{contents} -``` One of the major nuisances of C++ compared to other languages is the manual management of `#include` directives in any file. diff --git a/clang-tools-extra/docs/clang-reorder-fields.md b/clang-tools-extra/docs/clang-reorder-fields.md index 632583e90feaa..b2114d5df7203 100644 --- a/clang-tools-extra/docs/clang-reorder-fields.md +++ b/clang-tools-extra/docs/clang-reorder-fields.md @@ -1,7 +1,5 @@ # Clang-Reorder-Fields -```{contents} -``` ```{toctree} :maxdepth: 1 diff --git a/clang-tools-extra/docs/clang-tidy/index.rst b/clang-tools-extra/docs/clang-tidy/index.rst index cfa77eb670ecf..9325307b6c9e4 100644 --- a/clang-tools-extra/docs/clang-tidy/index.rst +++ b/clang-tools-extra/docs/clang-tidy/index.rst @@ -2,8 +2,6 @@ Clang-Tidy ========== -.. contents:: - See also: .. toctree:: diff --git a/clang-tools-extra/docs/conf.py b/clang-tools-extra/docs/conf.py index a80bbcf8638b5..d0ca4e9902dc3 100644 --- a/clang-tools-extra/docs/conf.py +++ b/clang-tools-extra/docs/conf.py @@ -70,14 +70,13 @@ # -- Options for HTML output --------------------------------------------------- -# The theme to use for HTML and HTML Help pages. See the documentation for -# a list of builtin themes. -html_theme = "haiku" - -# Theme options are theme-specific and customize the look and feel of a theme -# further. For a list of options available for each theme, see the -# documentation. -# html_theme_options = {} +configure_furo( + globals(), + source_directory="clang-tools-extra/docs/", + html_title="Extra Clang Tools", + local_static_path=["_static"], + extra_css_files=["clang-tools-extra-styles.css"], +) # Add any paths that contain custom themes here, relative to this directory. # html_theme_path = [] @@ -98,11 +97,6 @@ # pixels large. # html_favicon = None -# Add any paths that contain custom static files (such as style sheets) here, -# relative to this directory. They are copied after the builtin static files, -# so a file named "default.css" will overwrite the builtin "default.css". -html_static_path = ["_static"] - # 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' diff --git a/utils/docs/remove_page_tocs.py b/utils/docs/remove_page_tocs.py new file mode 100644 index 0000000000000..148dd300d73b3 --- /dev/null +++ b/utils/docs/remove_page_tocs.py @@ -0,0 +1,72 @@ +#!/usr/bin/env python3 +"""Remove page-local contents directives from Sphinx documentation.""" + +from __future__ import annotations + +import argparse +import re +from pathlib import Path + +CONTENTS = re.compile( + r"(?m)^```\{contents\}[^\n]*\n(?:.*\n)*?^```\n?|" + r"\n*^\.\. contents::[^\n]*(?:\n(?:[ \t].*|[ \t]*))*\n*" +) +SUFFIXES = (".rst", ".md", ".td") + + +def iter_sources(root: Path): + if root.is_file(): + if root.suffix in SUFFIXES: + yield root + return + + for suffix in SUFFIXES: + yield from root.rglob(f"*{suffix}") + + +def rewrite(path: Path) -> int: + text = path.read_text(encoding="utf-8") + + def replacement(match: re.Match[str]) -> str: + if match.group(0).lstrip("\n").startswith("```") or not match.start(): + return "" + return "\n\n" if match.end() < len(text) else "\n" + + new_text, removed = CONTENTS.subn(replacement, text) + if new_text != text: + path.write_text(new_text, encoding="utf-8") + return removed + + +def main() -> int: + parser = argparse.ArgumentParser(description=__doc__) + parser.add_argument( + "roots", + nargs="*", + type=Path, + default=[ + Path("clang/docs"), + Path("clang/Maintainers.md"), + Path("clang/include/clang/Basic"), + Path("clang/include/clang/Options"), + ], + help="Documentation roots to scan, defaults to Clang docs and generated-doc inputs.", + ) + args = parser.parse_args() + + removals = [ + (path, rewrite(path)) + for root in args.roots + for path in sorted(iter_sources(root)) + ] + changed = [(path, count) for path, count in removals if count] + for path, count in changed: + print(f"{path}: removed {count} contents directive(s)") + print( + f"removed {sum(count for _, count in changed)} contents directive(s) from {len(changed)} file(s)" + ) + return 0 + + +if __name__ == "__main__": + raise SystemExit(main()) >From 7ff8a385189791f35f8248053f179c9610ef137f Mon Sep 17 00:00:00 2001 From: Reid Kleckner <[email protected]> Date: Wed, 9 Sep 2026 22:01:23 +0000 Subject: [PATCH 2/4] [clang-tools-extra][docs] Fix stylesheet cache busting and table wrapping Generate Furo's combined light and dark Pygments stylesheet before Sphinx renders HTML so the cache-busting query matches the final file. Rebuild HTML when the generated stylesheet changes. Allow the two clang-tidy check tables to wrap long identifiers and give their columns semantic widths. --- .../docs/_static/clang-tools-extra-styles.css | 7 ++++ .../docs/clang-tidy/checks/list.md | 12 ++++++ utils/docs/llvm_sphinx/ext/furo.py | 42 +++++++++++++++++++ 3 files changed, 61 insertions(+) diff --git a/clang-tools-extra/docs/_static/clang-tools-extra-styles.css b/clang-tools-extra/docs/_static/clang-tools-extra-styles.css index 7fe4207cf680e..35fd39e907f41 100644 --- a/clang-tools-extra/docs/_static/clang-tools-extra-styles.css +++ b/clang-tools-extra/docs/_static/clang-tools-extra-styles.css @@ -22,6 +22,13 @@ details summary:hover { cursor: pointer; } +/* The two check tables contain long identifiers whose dots are not natural + line-breaking opportunities. Let table layout wrap them when needed. */ +.clang-tidy-checks-table th, +.clang-tidy-checks-table td { + overflow-wrap: anywhere; +} + /* Use the full viewport on ordinary desktop displays, where Furo's fixed content width leaves little room after both sidebars. Once the content area reaches 90em (84em plus padding), grow symmetric outer margins instead. */ diff --git a/clang-tools-extra/docs/clang-tidy/checks/list.md b/clang-tools-extra/docs/clang-tidy/checks/list.md index ea6f13365e206..a74a26e691053 100644 --- a/clang-tools-extra/docs/clang-tidy/checks/list.md +++ b/clang-tools-extra/docs/clang-tidy/checks/list.md @@ -32,6 +32,10 @@ portability/* readability/* ``` +:::{table} +:class: clang-tidy-checks-table +:widths: 90 10 + | Name | Offers fixes | | --- | --- | | {doc}`abseil-cleanup-ctad <abseil/cleanup-ctad>` | Yes | @@ -445,8 +449,14 @@ readability/* | {doc}`readability-use-concise-preprocessor-directives <readability/use-concise-preprocessor-directives>` | Yes | | {doc}`readability-use-std-min-max <readability/use-std-min-max>` | Yes | +::: + ## Check aliases +:::{table} +:class: clang-tidy-checks-table +:widths: 45 45 10 + | Name | Redirect | Offers fixes | | --- | --- | --- | | {doc}`cert-arr39-c <cert/arr39-c>` | {doc}`bugprone-sizeof-expression <bugprone/sizeof-expression>` | | @@ -626,3 +636,5 @@ readability/* | {doc}`llvm-else-after-return <llvm/else-after-return>` | {doc}`readability-else-after-return <readability/else-after-return>` | Yes | | {doc}`llvm-qualified-auto <llvm/qualified-auto>` | {doc}`readability-qualified-auto <readability/qualified-auto>` | Yes | | {doc}`performance-faster-string-find <performance/faster-string-find>` | {doc}`performance-prefer-single-char-overloads <performance/prefer-single-char-overloads>` | Yes | + +::: diff --git a/utils/docs/llvm_sphinx/ext/furo.py b/utils/docs/llvm_sphinx/ext/furo.py index 7bb876c448daa..76b0334586375 100644 --- a/utils/docs/llvm_sphinx/ext/furo.py +++ b/utils/docs/llvm_sphinx/ext/furo.py @@ -1,5 +1,6 @@ """Shared Furo theme assets for LLVM Sphinx projects.""" +import zlib from pathlib import Path from sphinx.util.fileutil import copy_asset @@ -8,6 +9,43 @@ _SHARED_STATIC_DIR = Path(__file__).parents[1] / "_static" +def _furo_pygments_stylesheet(): + from furo import get_pygments_stylesheet + + return get_pygments_stylesheet() + + +def _rebuild_on_pygments_change(app, env, added, changed, removed): + if app.builder.format != "html": + return () + + stylesheet = _furo_pygments_stylesheet().encode() + checksum = zlib.crc32(stylesheet.translate(None, b"\r")) + previous_checksum = getattr(env, "_llvm_furo_pygments_checksum", None) + env._llvm_furo_pygments_checksum = checksum + if checksum != previous_checksum: + return env.found_docs + return () + + +def _install_furo_pygments_writer(app): + if app.builder.format != "html": + return + + # Sphinx normally writes pygments.css immediately before rendering HTML, + # which lets it add a checksum of that file to the stylesheet URL. Furo + # replaces the file at build-finished to add dark-mode styles, after Sphinx + # has already calculated the checksum. Generate Furo's final contents at + # Sphinx's normal asset-writing point so the checksum matches the file that + # Furo writes again at build-finished. + def create_pygments_style_file(): + pygments_css = Path(app.builder.outdir) / "_static" / "pygments.css" + pygments_css.parent.mkdir(parents=True, exist_ok=True) + pygments_css.write_text(_furo_pygments_stylesheet(), encoding="utf-8") + + app.builder.create_pygments_style_file = create_pygments_style_file + + def _add_shared_static_files(app): if app.builder.format != "html": return @@ -27,6 +65,10 @@ def _copy_shared_static_files(app, exception): def setup(app): + # Furo initializes the light and dark Pygments styles in its own + # builder-inited handler at the default priority (500). + app.connect("builder-inited", _install_furo_pygments_writer, priority=600) + app.connect("env-get-outdated", _rebuild_on_pygments_change) app.connect("builder-inited", _add_shared_static_files) app.connect("build-finished", _copy_shared_static_files) return { >From 366a4f897cd2be9021a34257ce2478d47546142d Mon Sep 17 00:00:00 2001 From: Reid Kleckner <[email protected]> Date: Fri, 11 Sep 2026 05:10:59 +0000 Subject: [PATCH 3/4] [clang-tools-extra][docs] Remove empty navigation trees Remove stale, empty toctree directives from standalone tool documentation. Furo interpreted these directives as child navigation trees and displayed disclosure triangles with no useful entries. --- clang-tools-extra/docs/clang-change-namespace.md | 4 ---- clang-tools-extra/docs/clang-doc.md | 4 ---- clang-tools-extra/docs/clang-reorder-fields.md | 5 ----- clang-tools-extra/docs/pp-trace.md | 5 ----- 4 files changed, 18 deletions(-) diff --git a/clang-tools-extra/docs/clang-change-namespace.md b/clang-tools-extra/docs/clang-change-namespace.md index 7e5eb3fb11268..febeb10edf63d 100644 --- a/clang-tools-extra/docs/clang-change-namespace.md +++ b/clang-tools-extra/docs/clang-change-namespace.md @@ -1,10 +1,6 @@ # Clang-Change-Namespace -```{toctree} -:maxdepth: 1 -``` - {program}`clang-change-namespace` can be used to change the surrounding namespaces of class/function definitions. diff --git a/clang-tools-extra/docs/clang-doc.md b/clang-tools-extra/docs/clang-doc.md index f24a4697a4991..dfaf5df106123 100644 --- a/clang-tools-extra/docs/clang-doc.md +++ b/clang-tools-extra/docs/clang-doc.md @@ -1,10 +1,6 @@ # Clang-Doc -```{toctree} -:maxdepth: 1 -``` - {program}`clang-doc` is a tool for generating C and C++ documentation from source code and comments. diff --git a/clang-tools-extra/docs/clang-reorder-fields.md b/clang-tools-extra/docs/clang-reorder-fields.md index b2114d5df7203..870723b4dc84d 100644 --- a/clang-tools-extra/docs/clang-reorder-fields.md +++ b/clang-tools-extra/docs/clang-reorder-fields.md @@ -1,10 +1,6 @@ # Clang-Reorder-Fields -```{toctree} -:maxdepth: 1 -``` - {program}`clang-reorder-fields` is a refactoring tool to reorder fields in C/C++ structs and classes. This tool automatically updates: @@ -401,4 +397,3 @@ by type, or by access pattern). ### Field grouping Group related fields together for better code organization and readability. - diff --git a/clang-tools-extra/docs/pp-trace.md b/clang-tools-extra/docs/pp-trace.md index 21b7588703483..73acf26d6f045 100644 --- a/clang-tools-extra/docs/pp-trace.md +++ b/clang-tools-extra/docs/pp-trace.md @@ -3,10 +3,6 @@ # pp-trace User's Manual -```{toctree} -:hidden: true -``` - {program}`pp-trace` is a standalone tool that traces preprocessor activity. It's also used as a test of Clang's PPCallbacks interface. It runs a given source file through the Clang preprocessor, displaying @@ -771,4 +767,3 @@ To build from source: [building llvm with cmake]: https://llvm.org/docs/CMake.html [clang tools documentation]: https://clang.llvm.org/docs/ClangTools.html [getting started with the llvm system]: https://llvm.org/docs/GettingStarted.html - >From bb8d68010aebf011d69076ead8a3dfbfd7c7fbbf Mon Sep 17 00:00:00 2001 From: Reid Kleckner <[email protected]> Date: Wed, 16 Sep 2026 22:49:21 +0000 Subject: [PATCH 4/4] [clang-tidy] Preserve table styles when updating docs --- clang-tools-extra/clang-tidy/add_new_check.py | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/clang-tools-extra/clang-tidy/add_new_check.py b/clang-tools-extra/clang-tidy/add_new_check.py index 36e3aa6106e55..0e6692038fbf1 100755 --- a/clang-tools-extra/clang-tidy/add_new_check.py +++ b/clang-tools-extra/clang-tidy/add_new_check.py @@ -598,12 +598,16 @@ def format_link_alias(doc_file: Tuple[str, str]) -> str: f.write("| --- | --- |\n") f.writelines(sorted(filter(None, map(format_link, doc_files)))) # and the aliases - f.write("\n## Check aliases\n\n") + f.write("\n:::\n\n## Check aliases\n\n") + f.write(":::{table}\n") + f.write(":class: clang-tidy-checks-table\n") + f.write(":widths: 45 45 10\n\n") f.write("| Name | Redirect | Offers fixes |\n") f.write("| --- | --- | --- |\n") alias_rows = list(map(format_link_alias, doc_files)) alias_rows.extend(clang_analyzer_alias_rows) f.writelines(sorted(filter(None, alias_rows))) + f.write("\n:::\n") break _______________________________________________ cfe-commits mailing list [email protected] https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits
