Author: Paul Kirth Date: 2025-05-22T14:20:08-07:00 New Revision: 97dee78eb364efab6ddb57bc6580c55971994f41
URL: https://github.com/llvm/llvm-project/commit/97dee78eb364efab6ddb57bc6580c55971994f41 DIFF: https://github.com/llvm/llvm-project/commit/97dee78eb364efab6ddb57bc6580c55971994f41.diff LOG: [clang-doc] Add helpers for Template config (#138062) This patch adds or fills in some helper functions related to template setup when initializing the mustache backend. It was split from #133161. Co-authored-by: Peter Chou <peter.c...@mail.utoronto.ca> Added: clang-tools-extra/clang-doc/assets/comment-template.mustache clang-tools-extra/clang-doc/support/Utils.cpp clang-tools-extra/clang-doc/support/Utils.h clang-tools-extra/unittests/clang-doc/config.h.cmake Modified: clang-tools-extra/clang-doc/HTMLMustacheGenerator.cpp clang-tools-extra/clang-doc/support/CMakeLists.txt clang-tools-extra/clang-doc/tool/CMakeLists.txt clang-tools-extra/unittests/clang-doc/CMakeLists.txt clang-tools-extra/unittests/clang-doc/HTMLMustacheGeneratorTest.cpp Removed: clang-tools-extra/clang-doc/assets/comments-template.mustache ################################################################################ diff --git a/clang-tools-extra/clang-doc/HTMLMustacheGenerator.cpp b/clang-tools-extra/clang-doc/HTMLMustacheGenerator.cpp index 366deb55b77b9..fd68b2e08ad98 100644 --- a/clang-tools-extra/clang-doc/HTMLMustacheGenerator.cpp +++ b/clang-tools-extra/clang-doc/HTMLMustacheGenerator.cpp @@ -18,6 +18,7 @@ #include "llvm/Support/Error.h" #include "llvm/Support/MemoryBuffer.h" #include "llvm/Support/Mustache.h" +#include "llvm/Support/Path.h" using namespace llvm; using namespace llvm::json; @@ -74,7 +75,50 @@ static std::unique_ptr<MustacheTemplateFile> NamespaceTemplate = nullptr; static std::unique_ptr<MustacheTemplateFile> RecordTemplate = nullptr; +static Error +setupTemplate(std::unique_ptr<MustacheTemplateFile> &Template, + StringRef TemplatePath, + std::vector<std::pair<StringRef, StringRef>> Partials) { + auto T = MustacheTemplateFile::createMustacheFile(TemplatePath); + if (Error Err = T.takeError()) + return Err; + Template = std::move(T.get()); + for (const auto [Name, FileName] : Partials) + if (auto Err = Template->registerPartialFile(Name, FileName)) + return Err; + return Error::success(); +} + static Error setupTemplateFiles(const clang::doc::ClangDocContext &CDCtx) { + // Template files need to use the native path when they're opened, + // but have to be used in POSIX style when used in HTML. + auto ConvertToNative = [](std::string &&Path) -> std::string { + SmallString<128> PathBuf(Path); + llvm::sys::path::native(PathBuf); + return PathBuf.str().str(); + }; + + std::string NamespaceFilePath = + ConvertToNative(CDCtx.MustacheTemplates.lookup("namespace-template")); + std::string ClassFilePath = + ConvertToNative(CDCtx.MustacheTemplates.lookup("class-template")); + std::string CommentFilePath = + ConvertToNative(CDCtx.MustacheTemplates.lookup("comment-template")); + std::string FunctionFilePath = + ConvertToNative(CDCtx.MustacheTemplates.lookup("function-template")); + std::string EnumFilePath = + ConvertToNative(CDCtx.MustacheTemplates.lookup("enum-template")); + std::vector<std::pair<StringRef, StringRef>> Partials = { + {"Comments", CommentFilePath}, + {"FunctionPartial", FunctionFilePath}, + {"EnumPartial", EnumFilePath}}; + + if (Error Err = setupTemplate(NamespaceTemplate, NamespaceFilePath, Partials)) + return Err; + + if (Error Err = setupTemplate(RecordTemplate, ClassFilePath, Partials)) + return Err; + return Error::success(); } diff --git a/clang-tools-extra/clang-doc/assets/comments-template.mustache b/clang-tools-extra/clang-doc/assets/comment-template.mustache similarity index 100% rename from clang-tools-extra/clang-doc/assets/comments-template.mustache rename to clang-tools-extra/clang-doc/assets/comment-template.mustache diff --git a/clang-tools-extra/clang-doc/support/CMakeLists.txt b/clang-tools-extra/clang-doc/support/CMakeLists.txt index a4f7993d5c9d8..8ac913ffbe998 100644 --- a/clang-tools-extra/clang-doc/support/CMakeLists.txt +++ b/clang-tools-extra/clang-doc/support/CMakeLists.txt @@ -6,4 +6,5 @@ set(LLVM_LINK_COMPONENTS add_clang_library(clangDocSupport STATIC File.cpp - ) \ No newline at end of file + Utils.cpp + ) diff --git a/clang-tools-extra/clang-doc/support/Utils.cpp b/clang-tools-extra/clang-doc/support/Utils.cpp new file mode 100644 index 0000000000000..6ed56033738b5 --- /dev/null +++ b/clang-tools-extra/clang-doc/support/Utils.cpp @@ -0,0 +1,60 @@ +//===----------------------------------------------------------------------===// +// +// 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 "Utils.h" +#include "llvm/ADT/SmallString.h" +#include "llvm/ADT/StringRef.h" +#include "llvm/Support/FileSystem.h" +#include "llvm/Support/Path.h" + +using namespace llvm; + +SmallString<128> appendPathNative(StringRef Base, StringRef Path) { + SmallString<128> Default; + sys::path::native(Base, Default); + sys::path::append(Default, Path); + return Default; +} + +SmallString<128> appendPathPosix(StringRef Base, StringRef Path) { + SmallString<128> Default; + sys::path::native(Base, Default, sys::path::Style::posix); + sys::path::append(Default, Path); + return Default; +} + +void getMustacheHtmlFiles(StringRef AssetsPath, + clang::doc::ClangDocContext &CDCtx) { + assert(!AssetsPath.empty()); + assert(sys::fs::is_directory(AssetsPath)); + + SmallString<128> DefaultStylesheet = + appendPathPosix(AssetsPath, "clang-doc-mustache.css"); + SmallString<128> NamespaceTemplate = + appendPathPosix(AssetsPath, "namespace-template.mustache"); + SmallString<128> ClassTemplate = + appendPathPosix(AssetsPath, "class-template.mustache"); + SmallString<128> EnumTemplate = + appendPathPosix(AssetsPath, "enum-template.mustache"); + SmallString<128> FunctionTemplate = + appendPathPosix(AssetsPath, "function-template.mustache"); + SmallString<128> CommentTemplate = + appendPathPosix(AssetsPath, "comment-template.mustache"); + SmallString<128> IndexJS = appendPathPosix(AssetsPath, "mustache-index.js"); + + CDCtx.JsScripts.insert(CDCtx.JsScripts.begin(), IndexJS.c_str()); + CDCtx.UserStylesheets.insert(CDCtx.UserStylesheets.begin(), + DefaultStylesheet.c_str()); + CDCtx.MustacheTemplates.insert( + {"namespace-template", NamespaceTemplate.c_str()}); + CDCtx.MustacheTemplates.insert({"class-template", ClassTemplate.c_str()}); + CDCtx.MustacheTemplates.insert({"enum-template", EnumTemplate.c_str()}); + CDCtx.MustacheTemplates.insert( + {"function-template", FunctionTemplate.c_str()}); + CDCtx.MustacheTemplates.insert({"comment-template", CommentTemplate.c_str()}); +} diff --git a/clang-tools-extra/clang-doc/support/Utils.h b/clang-tools-extra/clang-doc/support/Utils.h new file mode 100644 index 0000000000000..8161c37503f81 --- /dev/null +++ b/clang-tools-extra/clang-doc/support/Utils.h @@ -0,0 +1,26 @@ +//===----------------------------------------------------------------------===// +// +// 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 +// +//===----------------------------------------------------------------------===// +#ifndef LLVM_CLANG_TOOLS_EXTRA_CLANG_DOC_FILE_H +#define LLVM_CLANG_TOOLS_EXTRA_CLANG_DOC_FILE_H + +#include "../Representation.h" +#include "llvm/ADT/SmallString.h" +#include "llvm/ADT/StringRef.h" + +/// Appends \p Path to \p Base and returns the appended path. +llvm::SmallString<128> appendPathNative(llvm::StringRef Base, + llvm::StringRef Path); + +/// Appends \p Path to \p Base and returns the appended path in posix style. +llvm::SmallString<128> appendPathPosix(llvm::StringRef Base, + llvm::StringRef Path); + +void getMustacheHtmlFiles(llvm::StringRef AssetsPath, + clang::doc::ClangDocContext &CDCtx); + +#endif diff --git a/clang-tools-extra/clang-doc/tool/CMakeLists.txt b/clang-tools-extra/clang-doc/tool/CMakeLists.txt index e359beb5f9079..f380c621890fb 100644 --- a/clang-tools-extra/clang-doc/tool/CMakeLists.txt +++ b/clang-tools-extra/clang-doc/tool/CMakeLists.txt @@ -25,7 +25,7 @@ set(assets clang-doc-default-stylesheet.css clang-doc-mustache.css class-template.mustache - comments-template.mustache + comment-template.mustache enum-template.mustache function-template.mustache namespace-template.mustache diff --git a/clang-tools-extra/unittests/clang-doc/CMakeLists.txt b/clang-tools-extra/unittests/clang-doc/CMakeLists.txt index fd14d85c63485..59a856ed987dc 100644 --- a/clang-tools-extra/unittests/clang-doc/CMakeLists.txt +++ b/clang-tools-extra/unittests/clang-doc/CMakeLists.txt @@ -4,10 +4,21 @@ set(LLVM_LINK_COMPONENTS FrontendOpenMP ) +# Unittests need access to mustache template files, so we use a config file to +# inject those into a config.h header that can provide it to the unittests. +set(CLANG_DOC_TEST_ASSET_DIR "${LLVM_RUNTIME_OUTPUT_INTDIR}/../share/clang-doc") +configure_file( + "${CMAKE_CURRENT_SOURCE_DIR}/config.h.cmake" + "${CMAKE_CURRENT_BINARY_DIR}/config.h" +) + +# The config.h file is in ${CMAKE_CURRENT_BINARY_DIR}, so add it to +# include_directories. get_filename_component(CLANG_DOC_SOURCE_DIR ${CMAKE_CURRENT_SOURCE_DIR}/../../clang-doc REALPATH) include_directories( ${CLANG_DOC_SOURCE_DIR} + ${CMAKE_CURRENT_BINARY_DIR} ) add_extra_unittest(ClangDocTests diff --git a/clang-tools-extra/unittests/clang-doc/HTMLMustacheGeneratorTest.cpp b/clang-tools-extra/unittests/clang-doc/HTMLMustacheGeneratorTest.cpp index c0ff3f0bbaa74..70491f0754b3d 100644 --- a/clang-tools-extra/unittests/clang-doc/HTMLMustacheGeneratorTest.cpp +++ b/clang-tools-extra/unittests/clang-doc/HTMLMustacheGeneratorTest.cpp @@ -9,6 +9,8 @@ #include "ClangDocTest.h" #include "Generators.h" #include "Representation.h" +#include "config.h" +#include "support/Utils.h" #include "clang/Basic/Version.h" #include "llvm/Support/Path.h" #include "llvm/Testing/Support/Error.h" @@ -86,8 +88,13 @@ TEST(HTMLMustacheGeneratorTest, generateDocs) { assert(G && "Could not find HTMLMustacheGenerator"); ClangDocContext CDCtx = getClangDocContext(); - StringRef RootDir = ""; - EXPECT_THAT_ERROR(G->generateDocs(RootDir, {}, CDCtx), Succeeded()) + unittest::TempDir RootTestDirectory("generateDocsTest", /*Unique=*/true); + CDCtx.OutDirectory = RootTestDirectory.path(); + + getMustacheHtmlFiles(CLANG_DOC_TEST_ASSET_DIR, CDCtx); + + EXPECT_THAT_ERROR(G->generateDocs(RootTestDirectory.path(), {}, CDCtx), + Succeeded()) << "Failed to generate docs."; } diff --git a/clang-tools-extra/unittests/clang-doc/config.h.cmake b/clang-tools-extra/unittests/clang-doc/config.h.cmake new file mode 100644 index 0000000000000..38edb3530e994 --- /dev/null +++ b/clang-tools-extra/unittests/clang-doc/config.h.cmake @@ -0,0 +1,6 @@ +#ifndef CLANG_TOOLS_EXTRA_UNITTESTS_CLANG_DOC_CONFIG_H +#define CLANG_TOOLS_EXTRA_UNITTESTS_CLANG_DOC_CONFIG_H + +#define CLANG_DOC_TEST_ASSET_DIR "${CLANG_DOC_TEST_ASSET_DIR}" + +#endif // CLANG_TOOLS_EXTRA_UNITTESTS_CLANG_DOC_CONFIG_H _______________________________________________ cfe-commits mailing list cfe-commits@lists.llvm.org https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits
