[clang-tools-extra] [clang-doc] Create a partial for the navbar (PR #171669)
Erick Velez via cfe-commits
cfe-commits at lists.llvm.org
Thu Dec 11 09:00:10 PST 2025
https://github.com/evelez7 updated https://github.com/llvm/llvm-project/pull/171669
>From 8a9223981de584858f669da448f5ff7ea9b33089 Mon Sep 17 00:00:00 2001
From: Erick Velez <erickvelez7 at gmail.com>
Date: Fri, 14 Nov 2025 21:15:11 -0800
Subject: [PATCH 1/2] [clang-doc] Create a partial for HTML <head> sections
The <head> sections of the existing partials are already identical, so
creating a partial will help reduce lines in the templates. Now
changes to <head> sections can easily propogate and can easily be added
to future HTML pages.
---
clang-tools-extra/clang-doc/HTMLGenerator.cpp | 5 ++++-
.../clang-doc/assets/class-template.mustache | 15 +--------------
.../clang-doc/assets/head-template.mustache | 14 ++++++++++++++
.../clang-doc/assets/namespace-template.mustache | 15 +--------------
clang-tools-extra/clang-doc/support/Utils.cpp | 3 +++
clang-tools-extra/clang-doc/tool/CMakeLists.txt | 1 +
6 files changed, 24 insertions(+), 29 deletions(-)
create mode 100644 clang-tools-extra/clang-doc/assets/head-template.mustache
diff --git a/clang-tools-extra/clang-doc/HTMLGenerator.cpp b/clang-tools-extra/clang-doc/HTMLGenerator.cpp
index 6f58c3d00fa28..19018f2cf845d 100644
--- a/clang-tools-extra/clang-doc/HTMLGenerator.cpp
+++ b/clang-tools-extra/clang-doc/HTMLGenerator.cpp
@@ -66,10 +66,13 @@ Error HTMLGenerator::setupTemplateFiles(const ClangDocContext &CDCtx) {
ConvertToNative(CDCtx.MustacheTemplates.lookup("function-template"));
std::string EnumFilePath =
ConvertToNative(CDCtx.MustacheTemplates.lookup("enum-template"));
+ std::string HeadFilePath =
+ ConvertToNative(CDCtx.MustacheTemplates.lookup("head-template"));
std::vector<std::pair<StringRef, StringRef>> Partials = {
{"Comments", CommentFilePath},
{"FunctionPartial", FunctionFilePath},
- {"EnumPartial", EnumFilePath}};
+ {"EnumPartial", EnumFilePath},
+ {"HeadPartial", HeadFilePath}};
if (Error Err = setupTemplate(NamespaceTemplate, NamespaceFilePath, Partials))
return Err;
diff --git a/clang-tools-extra/clang-doc/assets/class-template.mustache b/clang-tools-extra/clang-doc/assets/class-template.mustache
index 1197e76ab553c..9c5019510b43c 100644
--- a/clang-tools-extra/clang-doc/assets/class-template.mustache
+++ b/clang-tools-extra/clang-doc/assets/class-template.mustache
@@ -7,20 +7,7 @@
}}
<!DOCTYPE html>
<html lang="en-US">
-<head>
- <meta charset="utf-8"/>
- <title>{{Name}}</title>
- {{#Stylesheets}}
- <link rel="stylesheet" type="text/css" href="{{.}}"/>
- {{/Stylesheets}}
- {{#Scripts}}
- <script src="{{.}}"></script>
- {{/Scripts}}
- {{! Highlight.js dependency for syntax highlighting }}
- <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0/styles/default.min.css">
- <script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0/highlight.min.js"></script>
- <script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0/languages/cpp.min.js"></script>
-</head>
+{{>HeadPartial}}
<body>
<nav class="navbar">
<div class="navbar__container">
diff --git a/clang-tools-extra/clang-doc/assets/head-template.mustache b/clang-tools-extra/clang-doc/assets/head-template.mustache
new file mode 100644
index 0000000000000..f0a8057a9c3dc
--- /dev/null
+++ b/clang-tools-extra/clang-doc/assets/head-template.mustache
@@ -0,0 +1,14 @@
+<head>
+ <meta charset="utf-8"/>
+ <title>{{Name}}</title>
+ {{#Stylesheets}}
+ <link rel="stylesheet" type="text/css" href="{{.}}"/>
+ {{/Stylesheets}}
+ {{#Scripts}}
+ <script src="{{.}}"></script>
+ {{/Scripts}}
+ {{! Highlight.js dependency for syntax highlighting }}
+ <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0/styles/default.min.css">
+ <script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0/highlight.min.js"></script>
+ <script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0/languages/cpp.min.js"></script>
+</head>
diff --git a/clang-tools-extra/clang-doc/assets/namespace-template.mustache b/clang-tools-extra/clang-doc/assets/namespace-template.mustache
index 7fb66cadbb8e8..f386eb2e6a581 100644
--- a/clang-tools-extra/clang-doc/assets/namespace-template.mustache
+++ b/clang-tools-extra/clang-doc/assets/namespace-template.mustache
@@ -7,20 +7,7 @@
}}
<!DOCTYPE html>
<html lang="en-US">
-<head>
- <meta charset="utf-8"/>
- <title>{{NamespaceTitle}}</title>
- {{#Stylesheets}}
- <link rel="stylesheet" type="text/css" href="{{.}}"/>
- {{/Stylesheets}}
- {{#Scripts}}
- <script src="{{.}}"></script>
- {{/Scripts}}
- {{! Highlight.js dependency for syntax highlighting }}
- <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0/styles/default.min.css">
- <script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0/highlight.min.js"></script>
- <script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0/languages/cpp.min.js"></script>
-</head>
+{{>HeadPartial}}
<body>
<nav class="navbar">
<div class="navbar__container">
diff --git a/clang-tools-extra/clang-doc/support/Utils.cpp b/clang-tools-extra/clang-doc/support/Utils.cpp
index f410bfcf956d4..50e849dc26c79 100644
--- a/clang-tools-extra/clang-doc/support/Utils.cpp
+++ b/clang-tools-extra/clang-doc/support/Utils.cpp
@@ -56,6 +56,8 @@ void getHtmlFiles(StringRef AssetsPath, clang::doc::ClangDocContext &CDCtx) {
appendPathPosix(AssetsPath, "function-template.mustache");
SmallString<128> CommentTemplate =
appendPathPosix(AssetsPath, "comment-template.mustache");
+ SmallString<128> HeadTemplate =
+ appendPathPosix(AssetsPath, "head-template.mustache");
CDCtx.MustacheTemplates.insert(
{"namespace-template", NamespaceTemplate.c_str()});
@@ -64,4 +66,5 @@ void getHtmlFiles(StringRef AssetsPath, clang::doc::ClangDocContext &CDCtx) {
CDCtx.MustacheTemplates.insert(
{"function-template", FunctionTemplate.c_str()});
CDCtx.MustacheTemplates.insert({"comment-template", CommentTemplate.c_str()});
+ CDCtx.MustacheTemplates.insert({"head-template", HeadTemplate.c_str()});
}
diff --git a/clang-tools-extra/clang-doc/tool/CMakeLists.txt b/clang-tools-extra/clang-doc/tool/CMakeLists.txt
index 7c9a94adec8a4..eb8f937bae831 100644
--- a/clang-tools-extra/clang-doc/tool/CMakeLists.txt
+++ b/clang-tools-extra/clang-doc/tool/CMakeLists.txt
@@ -31,6 +31,7 @@ set(assets
function-template.mustache
namespace-template.mustache
template.mustache
+ head-template.mustache
)
set(asset_dir "${CMAKE_CURRENT_SOURCE_DIR}/../assets")
>From 1d32cb2b5eded74705d269fa8140982459ae0e70 Mon Sep 17 00:00:00 2001
From: Erick Velez <erickvelez7 at gmail.com>
Date: Thu, 4 Dec 2025 12:33:18 -0800
Subject: [PATCH 2/2] [clang-doc] Create a partial for the navbar
Move navbar section to its own template so ensure consistency across
templates
---
clang-tools-extra/clang-doc/HTMLGenerator.cpp | 5 ++++-
.../clang-doc/assets/class-template.mustache | 20 +------------------
.../assets/namespace-template.mustache | 20 +------------------
.../clang-doc/assets/navbar-template.mustache | 19 ++++++++++++++++++
clang-tools-extra/clang-doc/support/Utils.cpp | 3 +++
.../clang-doc/tool/CMakeLists.txt | 1 +
6 files changed, 29 insertions(+), 39 deletions(-)
create mode 100644 clang-tools-extra/clang-doc/assets/navbar-template.mustache
diff --git a/clang-tools-extra/clang-doc/HTMLGenerator.cpp b/clang-tools-extra/clang-doc/HTMLGenerator.cpp
index 19018f2cf845d..77b287476423e 100644
--- a/clang-tools-extra/clang-doc/HTMLGenerator.cpp
+++ b/clang-tools-extra/clang-doc/HTMLGenerator.cpp
@@ -68,11 +68,14 @@ Error HTMLGenerator::setupTemplateFiles(const ClangDocContext &CDCtx) {
ConvertToNative(CDCtx.MustacheTemplates.lookup("enum-template"));
std::string HeadFilePath =
ConvertToNative(CDCtx.MustacheTemplates.lookup("head-template"));
+ std::string NavbarFilePath =
+ ConvertToNative(CDCtx.MustacheTemplates.lookup("navbar-template"));
std::vector<std::pair<StringRef, StringRef>> Partials = {
{"Comments", CommentFilePath},
{"FunctionPartial", FunctionFilePath},
{"EnumPartial", EnumFilePath},
- {"HeadPartial", HeadFilePath}};
+ {"HeadPartial", HeadFilePath},
+ {"NavbarPartial", NavbarFilePath}};
if (Error Err = setupTemplate(NamespaceTemplate, NamespaceFilePath, Partials))
return Err;
diff --git a/clang-tools-extra/clang-doc/assets/class-template.mustache b/clang-tools-extra/clang-doc/assets/class-template.mustache
index 9c5019510b43c..fcd923cd9db93 100644
--- a/clang-tools-extra/clang-doc/assets/class-template.mustache
+++ b/clang-tools-extra/clang-doc/assets/class-template.mustache
@@ -9,25 +9,7 @@
<html lang="en-US">
{{>HeadPartial}}
<body>
- <nav class="navbar">
- <div class="navbar__container">
- {{#ProjectName}}
- <div class="navbar__logo">
- {{ProjectName}}
- </div>
- {{/ProjectName}}
- <div class="navbar__menu">
- <ul class="navbar__links">
- <li class="navbar__item">
- <a href="/" class="navbar__link">Namespace</a>
- </li>
- <li class="navbar__item">
- <a href="/" class="navbar__link">Class</a>
- </li>
- </ul>
- </div>
- </div>
- </nav>
+ {{>NavbarPartial}}
<main>
<div class="container">
<div class="sidebar">
diff --git a/clang-tools-extra/clang-doc/assets/namespace-template.mustache b/clang-tools-extra/clang-doc/assets/namespace-template.mustache
index f386eb2e6a581..5c0d2fb14d3c9 100644
--- a/clang-tools-extra/clang-doc/assets/namespace-template.mustache
+++ b/clang-tools-extra/clang-doc/assets/namespace-template.mustache
@@ -9,25 +9,7 @@
<html lang="en-US">
{{>HeadPartial}}
<body>
- <nav class="navbar">
- <div class="navbar__container">
- {{#ProjectName}}
- <div class="navbar__logo">
- {{ProjectName}}
- </div>
- {{/ProjectName}}
- <div class="navbar__menu">
- <ul class="navbar__links">
- <li class="navbar__item">
- <a href="/" class="navbar__link">Namespace</a>
- </li>
- <li class="navbar__item">
- <a href="/" class="navbar__link">Class</a>
- </li>
- </ul>
- </div>
- </div>
- </nav>
+ {{>NavbarPartial}}
<main>
<div class="container">
<div class="sidebar">
diff --git a/clang-tools-extra/clang-doc/assets/navbar-template.mustache b/clang-tools-extra/clang-doc/assets/navbar-template.mustache
new file mode 100644
index 0000000000000..178d147a556d3
--- /dev/null
+++ b/clang-tools-extra/clang-doc/assets/navbar-template.mustache
@@ -0,0 +1,19 @@
+<nav class="navbar">
+ <div class="navbar__container">
+ {{#ProjectName}}
+ <div class="navbar__logo">
+ {{ProjectName}}
+ </div>
+ {{/ProjectName}}
+ <div class="navbar__menu">
+ <ul class="navbar__links">
+ <li class="navbar__item">
+ <a href="/" class="navbar__link">Namespace</a>
+ </li>
+ <li class="navbar__item">
+ <a href="/" class="navbar__link">Class</a>
+ </li>
+ </ul>
+ </div>
+ </div>
+</nav>
diff --git a/clang-tools-extra/clang-doc/support/Utils.cpp b/clang-tools-extra/clang-doc/support/Utils.cpp
index 50e849dc26c79..d0fd6f45b8a02 100644
--- a/clang-tools-extra/clang-doc/support/Utils.cpp
+++ b/clang-tools-extra/clang-doc/support/Utils.cpp
@@ -58,6 +58,8 @@ void getHtmlFiles(StringRef AssetsPath, clang::doc::ClangDocContext &CDCtx) {
appendPathPosix(AssetsPath, "comment-template.mustache");
SmallString<128> HeadTemplate =
appendPathPosix(AssetsPath, "head-template.mustache");
+ SmallString<128> NavbarTemplate =
+ appendPathPosix(AssetsPath, "navbar-template.mustache");
CDCtx.MustacheTemplates.insert(
{"namespace-template", NamespaceTemplate.c_str()});
@@ -67,4 +69,5 @@ void getHtmlFiles(StringRef AssetsPath, clang::doc::ClangDocContext &CDCtx) {
{"function-template", FunctionTemplate.c_str()});
CDCtx.MustacheTemplates.insert({"comment-template", CommentTemplate.c_str()});
CDCtx.MustacheTemplates.insert({"head-template", HeadTemplate.c_str()});
+ CDCtx.MustacheTemplates.insert({"navbar-template", NavbarTemplate.c_str()});
}
diff --git a/clang-tools-extra/clang-doc/tool/CMakeLists.txt b/clang-tools-extra/clang-doc/tool/CMakeLists.txt
index eb8f937bae831..c8b4162a0e716 100644
--- a/clang-tools-extra/clang-doc/tool/CMakeLists.txt
+++ b/clang-tools-extra/clang-doc/tool/CMakeLists.txt
@@ -32,6 +32,7 @@ set(assets
namespace-template.mustache
template.mustache
head-template.mustache
+ navbar-template.mustache
)
set(asset_dir "${CMAKE_CURRENT_SOURCE_DIR}/../assets")
More information about the cfe-commits
mailing list