[llvm-branch-commits] [clang-tools-extra] [clang-doc] Add HTMLMustacheGenerator.cpp (PR #138060)
Paul Kirth via llvm-branch-commits
llvm-branch-commits at lists.llvm.org
Tue May 6 19:00:00 PDT 2025
https://github.com/ilovepi updated https://github.com/llvm/llvm-project/pull/138060
>From 6098ca321c7095536ce24636fad42b0abb1cd770 Mon Sep 17 00:00:00 2001
From: Paul Kirth <paulkirth at google.com>
Date: Wed, 30 Apr 2025 07:59:01 -0700
Subject: [PATCH] [clang-doc] Add HTMLMustacheGenerator.cpp
Split from #133161. This patch adds HTMLMustacheGenerator.cpp, and
the most basic class defintion for the generator. Future patches will
add functionality.
Co-authored-by: Peter Chou <peter.chou at mail.utoronto.ca>
---
clang-tools-extra/clang-doc/CMakeLists.txt | 3 +-
clang-tools-extra/clang-doc/Generators.cpp | 3 +-
clang-tools-extra/clang-doc/Generators.h | 1 +
.../clang-doc/HTMLMustacheGenerator.cpp | 85 ++++++++++++++++++
clang-tools-extra/clang-doc/Representation.h | 2 +
.../unittests/clang-doc/CMakeLists.txt | 2 +
.../clang-doc/HTMLMustacheGeneratorTest.cpp | 87 +++++++++++++++++++
7 files changed, 181 insertions(+), 2 deletions(-)
create mode 100644 clang-tools-extra/clang-doc/HTMLMustacheGenerator.cpp
create mode 100644 clang-tools-extra/unittests/clang-doc/HTMLMustacheGeneratorTest.cpp
diff --git a/clang-tools-extra/clang-doc/CMakeLists.txt b/clang-tools-extra/clang-doc/CMakeLists.txt
index 915e14c3ee16d..79563c41435eb 100644
--- a/clang-tools-extra/clang-doc/CMakeLists.txt
+++ b/clang-tools-extra/clang-doc/CMakeLists.txt
@@ -16,6 +16,7 @@ add_clang_library(clangDoc STATIC
Representation.cpp
Serialize.cpp
YAMLGenerator.cpp
+ HTMLMustacheGenerator.cpp
DEPENDS
omp_gen
@@ -24,7 +25,7 @@ add_clang_library(clangDoc STATIC
clang_target_link_libraries(clangDoc
PRIVATE
- clangDocSupport
+ clangDocSupport
clangAnalysis
clangAST
clangASTMatchers
diff --git a/clang-tools-extra/clang-doc/Generators.cpp b/clang-tools-extra/clang-doc/Generators.cpp
index 4bb5366800f7f..a3c2773412cff 100644
--- a/clang-tools-extra/clang-doc/Generators.cpp
+++ b/clang-tools-extra/clang-doc/Generators.cpp
@@ -103,6 +103,7 @@ static int LLVM_ATTRIBUTE_UNUSED MDGeneratorAnchorDest =
MDGeneratorAnchorSource;
static int LLVM_ATTRIBUTE_UNUSED HTMLGeneratorAnchorDest =
HTMLGeneratorAnchorSource;
-
+static int LLVM_ATTRIBUTE_UNUSED MHTMLGeneratorAnchorDest =
+ MHTMLGeneratorAnchorSource;
} // namespace doc
} // namespace clang
diff --git a/clang-tools-extra/clang-doc/Generators.h b/clang-tools-extra/clang-doc/Generators.h
index 2e71890389256..aee04b9d58d9d 100644
--- a/clang-tools-extra/clang-doc/Generators.h
+++ b/clang-tools-extra/clang-doc/Generators.h
@@ -57,6 +57,7 @@ std::string getTagType(TagTypeKind AS);
extern volatile int YAMLGeneratorAnchorSource;
extern volatile int MDGeneratorAnchorSource;
extern volatile int HTMLGeneratorAnchorSource;
+extern volatile int MHTMLGeneratorAnchorSource;
} // namespace doc
} // namespace clang
diff --git a/clang-tools-extra/clang-doc/HTMLMustacheGenerator.cpp b/clang-tools-extra/clang-doc/HTMLMustacheGenerator.cpp
new file mode 100644
index 0000000000000..491448b8c9a51
--- /dev/null
+++ b/clang-tools-extra/clang-doc/HTMLMustacheGenerator.cpp
@@ -0,0 +1,85 @@
+//===-- HTMLMustacheGenerator.cpp - HTML Mustache Generator -----*- C++ -*-===//
+//
+// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+// See https://llvm.org/LICENSE.txt for license information.
+// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+//
+//===----------------------------------------------------------------------===//
+#include "Generators.h"
+#include "Representation.h"
+#include "support/File.h"
+#include "llvm/Support/MemoryBuffer.h"
+#include "llvm/Support/Mustache.h"
+
+using namespace llvm;
+using namespace llvm::json;
+using namespace llvm::mustache;
+
+namespace clang {
+namespace doc {
+
+class MustacheHTMLGenerator : public Generator {
+public:
+ static const char *Format;
+ Error generateDocs(StringRef RootDir,
+ StringMap<std::unique_ptr<doc::Info>> Infos,
+ const ClangDocContext &CDCtx) override;
+ Error createResources(ClangDocContext &CDCtx) override;
+ Error generateDocForInfo(Info *I, raw_ostream &OS,
+ const ClangDocContext &CDCtx) override;
+};
+
+class MustacheTemplateFile : public Template {
+public:
+ static ErrorOr<std::unique_ptr<MustacheTemplateFile>>
+ createMustacheFile(StringRef FileName) {
+ ErrorOr<std::unique_ptr<MemoryBuffer>> BufferOrError =
+ MemoryBuffer::getFile(FileName);
+ if (auto EC = BufferOrError.getError())
+ return EC;
+
+ std::unique_ptr<MemoryBuffer> Buffer = std::move(BufferOrError.get());
+ StringRef FileContent = Buffer->getBuffer();
+ return std::make_unique<MustacheTemplateFile>(FileContent);
+ }
+
+ Error registerPartialFile(StringRef Name, StringRef FileName) {
+ ErrorOr<std::unique_ptr<MemoryBuffer>> BufferOrError =
+ MemoryBuffer::getFile(FileName);
+ if (auto EC = BufferOrError.getError())
+ return createFileError("cannot open file", EC);
+ std::unique_ptr<MemoryBuffer> Buffer = std::move(BufferOrError.get());
+ StringRef FileContent = Buffer->getBuffer();
+ registerPartial(Name.str(), FileContent.str());
+ return Error::success();
+ }
+
+ MustacheTemplateFile(StringRef TemplateStr) : Template(TemplateStr) {}
+};
+
+Error MustacheHTMLGenerator::generateDocs(
+ StringRef RootDir, StringMap<std::unique_ptr<doc::Info>> Infos,
+ const clang::doc::ClangDocContext &CDCtx) {
+ return Error::success();
+}
+
+Error MustacheHTMLGenerator::generateDocForInfo(Info *I, raw_ostream &OS,
+ const ClangDocContext &CDCtx) {
+ return Error::success();
+}
+
+Error MustacheHTMLGenerator::createResources(ClangDocContext &CDCtx) {
+ return Error::success();
+}
+
+const char *MustacheHTMLGenerator::Format = "mhtml";
+
+static GeneratorRegistry::Add<MustacheHTMLGenerator>
+ MHTML(MustacheHTMLGenerator::Format, "Generator for mustache HTML output.");
+
+// This anchor is used to force the linker to link in the generated object
+// file and thus register the generator.
+volatile int MHTMLGeneratorAnchorSource = 0;
+
+} // namespace doc
+} // namespace clang
diff --git a/clang-tools-extra/clang-doc/Representation.h b/clang-tools-extra/clang-doc/Representation.h
index 1d5c4dcaeaf37..71377d10b2f40 100644
--- a/clang-tools-extra/clang-doc/Representation.h
+++ b/clang-tools-extra/clang-doc/Representation.h
@@ -535,6 +535,8 @@ struct ClangDocContext {
// JavaScript files that will be imported in all HTML files.
std::vector<std::string> JsScripts;
StringRef Base;
+ // Mustache Template files
+ llvm::StringMap<std::string> MustacheTemplates;
Index Idx;
};
diff --git a/clang-tools-extra/unittests/clang-doc/CMakeLists.txt b/clang-tools-extra/unittests/clang-doc/CMakeLists.txt
index 043d68f5a1dcb..81c18e6014072 100644
--- a/clang-tools-extra/unittests/clang-doc/CMakeLists.txt
+++ b/clang-tools-extra/unittests/clang-doc/CMakeLists.txt
@@ -15,6 +15,7 @@ add_extra_unittest(ClangDocTests
ClangDocTest.cpp
GeneratorTest.cpp
HTMLGeneratorTest.cpp
+ HTMLMustacheGeneratorTest.cpp
MDGeneratorTest.cpp
MergeTest.cpp
SerializeTest.cpp
@@ -36,4 +37,5 @@ clang_target_link_libraries(ClangDocTests
target_link_libraries(ClangDocTests
PRIVATE
clangDoc
+ LLVMTestingSupport
)
diff --git a/clang-tools-extra/unittests/clang-doc/HTMLMustacheGeneratorTest.cpp b/clang-tools-extra/unittests/clang-doc/HTMLMustacheGeneratorTest.cpp
new file mode 100644
index 0000000000000..2d54c26fee570
--- /dev/null
+++ b/clang-tools-extra/unittests/clang-doc/HTMLMustacheGeneratorTest.cpp
@@ -0,0 +1,87 @@
+//===-- clang-doc/HTMLMustacheGeneratorTest.cpp ---------------------------===//
+//
+// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+// See https://llvm.org/LICENSE.txt for license information.
+// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+//
+//===----------------------------------------------------------------------===//
+
+#include "ClangDocTest.h"
+#include "Generators.h"
+#include "Representation.h"
+#include "clang/Basic/Version.h"
+#include "llvm/Testing/Support/Error.h"
+#include "gmock/gmock.h"
+#include "gtest/gtest.h"
+
+using namespace llvm;
+using namespace testing;
+using namespace clang::doc;
+
+static const std::string ClangDocVersion =
+ clang::getClangToolFullVersion("clang-doc");
+
+static std::unique_ptr<Generator> getHTMLMustacheGenerator() {
+ auto G = findGeneratorByName("mhtml");
+ if (!G)
+ return nullptr;
+ return std::move(G.get());
+}
+
+static ClangDocContext
+getClangDocContext(std::vector<std::string> UserStylesheets = {},
+ StringRef RepositoryUrl = "",
+ StringRef RepositoryLinePrefix = "", StringRef Base = "") {
+ ClangDocContext CDCtx{
+ {}, "test-project", {}, {}, {}, RepositoryUrl, RepositoryLinePrefix,
+ Base, UserStylesheets};
+ CDCtx.UserStylesheets.insert(CDCtx.UserStylesheets.begin(), "");
+ CDCtx.JsScripts.emplace_back("");
+ return CDCtx;
+}
+
+TEST(HTMLMustacheGeneratorTest, createResources) {
+ auto G = getHTMLMustacheGenerator();
+ ASSERT_THAT(G, NotNull()) << "Could not find HTMLMustacheGenerator";
+ ClangDocContext CDCtx = getClangDocContext();
+
+ EXPECT_THAT_ERROR(G->createResources(CDCtx), Succeeded())
+ << "Failed to create resources.";
+}
+
+TEST(HTMLMustacheGeneratorTest, generateDocs) {
+ auto G = getHTMLMustacheGenerator();
+ assert(G && "Could not find HTMLMustacheGenerator");
+ ClangDocContext CDCtx = getClangDocContext();
+
+ StringRef RootDir = "";
+ EXPECT_THAT_ERROR(G->generateDocs(RootDir, {}, CDCtx), Succeeded())
+ << "Failed to generate docs.";
+}
+
+TEST(HTMLMustacheGeneratorTest, generateDocsForInfo) {
+ auto G = getHTMLMustacheGenerator();
+ assert(G && "Could not find HTMLMustacheGenerator");
+ ClangDocContext CDCtx = getClangDocContext();
+ std::string Buffer;
+ llvm::raw_string_ostream Actual(Buffer);
+ NamespaceInfo I;
+ I.Name = "Namespace";
+ I.Namespace.emplace_back(EmptySID, "A", InfoType::IT_namespace);
+
+ I.Children.Namespaces.emplace_back(EmptySID, "ChildNamespace",
+ InfoType::IT_namespace,
+ "Namespace::ChildNamespace", "Namespace");
+ I.Children.Records.emplace_back(EmptySID, "ChildStruct", InfoType::IT_record,
+ "Namespace::ChildStruct", "Namespace");
+ I.Children.Functions.emplace_back();
+ I.Children.Functions.back().Access = clang::AccessSpecifier::AS_none;
+ I.Children.Functions.back().Name = "OneFunction";
+ I.Children.Enums.emplace_back();
+
+ EXPECT_THAT_ERROR(G->generateDocForInfo(&I, Actual, CDCtx), Succeeded())
+ << "Failed to generate docs.";
+
+ std::string Expected = R"raw()raw";
+ EXPECT_THAT(Actual.str(), Eq(Expected));
+}
More information about the llvm-branch-commits
mailing list