Skip to content

Commit 97dee78

Browse files
ilovepiPeterChou1
ilovepi
and
PeterChou1
authored
[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 <[email protected]>
1 parent 0c42aef commit 97dee78

File tree

9 files changed

+159
-4
lines changed

9 files changed

+159
-4
lines changed

‎clang-tools-extra/clang-doc/HTMLMustacheGenerator.cpp‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,7 @@
1818
#include "llvm/Support/Error.h"
1919
#include "llvm/Support/MemoryBuffer.h"
2020
#include "llvm/Support/Mustache.h"
21+
#include "llvm/Support/Path.h"
2122

2223
using namespace llvm;
2324
using namespace llvm::json;
@@ -74,7 +75,50 @@ static std::unique_ptr<MustacheTemplateFile> NamespaceTemplate = nullptr;
7475

7576
static std::unique_ptr<MustacheTemplateFile> RecordTemplate = nullptr;
7677

78+
static Error
79+
setupTemplate(std::unique_ptr<MustacheTemplateFile> &Template,
80+
StringRef TemplatePath,
81+
std::vector<std::pair<StringRef, StringRef>> Partials) {
82+
auto T = MustacheTemplateFile::createMustacheFile(TemplatePath);
83+
if (Error Err = T.takeError())
84+
return Err;
85+
Template = std::move(T.get());
86+
for (const auto [Name, FileName] : Partials)
87+
if (auto Err = Template->registerPartialFile(Name, FileName))
88+
return Err;
89+
return Error::success();
90+
}
91+
7792
static Error setupTemplateFiles(const clang::doc::ClangDocContext &CDCtx) {
93+
// Template files need to use the native path when they're opened,
94+
// but have to be used in POSIX style when used in HTML.
95+
auto ConvertToNative = [](std::string &&Path) -> std::string {
96+
SmallString<128> PathBuf(Path);
97+
llvm::sys::path::native(PathBuf);
98+
return PathBuf.str().str();
99+
};
100+
101+
std::string NamespaceFilePath =
102+
ConvertToNative(CDCtx.MustacheTemplates.lookup("namespace-template"));
103+
std::string ClassFilePath =
104+
ConvertToNative(CDCtx.MustacheTemplates.lookup("class-template"));
105+
std::string CommentFilePath =
106+
ConvertToNative(CDCtx.MustacheTemplates.lookup("comment-template"));
107+
std::string FunctionFilePath =
108+
ConvertToNative(CDCtx.MustacheTemplates.lookup("function-template"));
109+
std::string EnumFilePath =
110+
ConvertToNative(CDCtx.MustacheTemplates.lookup("enum-template"));
111+
std::vector<std::pair<StringRef, StringRef>> Partials = {
112+
{"Comments", CommentFilePath},
113+
{"FunctionPartial", FunctionFilePath},
114+
{"EnumPartial", EnumFilePath}};
115+
116+
if (Error Err = setupTemplate(NamespaceTemplate, NamespaceFilePath, Partials))
117+
return Err;
118+
119+
if (Error Err = setupTemplate(RecordTemplate, ClassFilePath, Partials))
120+
return Err;
121+
78122
return Error::success();
79123
}
80124

‎clang-tools-extra/clang-doc/assets/comments-template.mustache‎ renamed to ‎clang-tools-extra/clang-doc/assets/comment-template.mustache‎

File renamed without changes.

‎clang-tools-extra/clang-doc/support/CMakeLists.txt‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,4 +6,5 @@ set(LLVM_LINK_COMPONENTS
66

77
add_clang_library(clangDocSupport STATIC
88
File.cpp
9-
)
9+
Utils.cpp
10+
)

‎clang-tools-extra/clang-doc/support/Utils.cpp‎

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
//===----------------------------------------------------------------------===//
2+
//
3+
// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
4+
// See https://llvm.org/LICENSE.txt for license information.
5+
// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
6+
//
7+
//===----------------------------------------------------------------------===//
8+
9+
#include "Utils.h"
10+
#include "llvm/ADT/SmallString.h"
11+
#include "llvm/ADT/StringRef.h"
12+
#include "llvm/Support/FileSystem.h"
13+
#include "llvm/Support/Path.h"
14+
15+
using namespace llvm;
16+
17+
SmallString<128> appendPathNative(StringRef Base, StringRef Path) {
18+
SmallString<128> Default;
19+
sys::path::native(Base, Default);
20+
sys::path::append(Default, Path);
21+
return Default;
22+
}
23+
24+
SmallString<128> appendPathPosix(StringRef Base, StringRef Path) {
25+
SmallString<128> Default;
26+
sys::path::native(Base, Default, sys::path::Style::posix);
27+
sys::path::append(Default, Path);
28+
return Default;
29+
}
30+
31+
void getMustacheHtmlFiles(StringRef AssetsPath,
32+
clang::doc::ClangDocContext &CDCtx) {
33+
assert(!AssetsPath.empty());
34+
assert(sys::fs::is_directory(AssetsPath));
35+
36+
SmallString<128> DefaultStylesheet =
37+
appendPathPosix(AssetsPath, "clang-doc-mustache.css");
38+
SmallString<128> NamespaceTemplate =
39+
appendPathPosix(AssetsPath, "namespace-template.mustache");
40+
SmallString<128> ClassTemplate =
41+
appendPathPosix(AssetsPath, "class-template.mustache");
42+
SmallString<128> EnumTemplate =
43+
appendPathPosix(AssetsPath, "enum-template.mustache");
44+
SmallString<128> FunctionTemplate =
45+
appendPathPosix(AssetsPath, "function-template.mustache");
46+
SmallString<128> CommentTemplate =
47+
appendPathPosix(AssetsPath, "comment-template.mustache");
48+
SmallString<128> IndexJS = appendPathPosix(AssetsPath, "mustache-index.js");
49+
50+
CDCtx.JsScripts.insert(CDCtx.JsScripts.begin(), IndexJS.c_str());
51+
CDCtx.UserStylesheets.insert(CDCtx.UserStylesheets.begin(),
52+
DefaultStylesheet.c_str());
53+
CDCtx.MustacheTemplates.insert(
54+
{"namespace-template", NamespaceTemplate.c_str()});
55+
CDCtx.MustacheTemplates.insert({"class-template", ClassTemplate.c_str()});
56+
CDCtx.MustacheTemplates.insert({"enum-template", EnumTemplate.c_str()});
57+
CDCtx.MustacheTemplates.insert(
58+
{"function-template", FunctionTemplate.c_str()});
59+
CDCtx.MustacheTemplates.insert({"comment-template", CommentTemplate.c_str()});
60+
}

‎clang-tools-extra/clang-doc/support/Utils.h‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
//===----------------------------------------------------------------------===//
2+
//
3+
// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
4+
// See https://llvm.org/LICENSE.txt for license information.
5+
// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
6+
//
7+
//===----------------------------------------------------------------------===//
8+
#ifndef LLVM_CLANG_TOOLS_EXTRA_CLANG_DOC_FILE_H
9+
#define LLVM_CLANG_TOOLS_EXTRA_CLANG_DOC_FILE_H
10+
11+
#include "../Representation.h"
12+
#include "llvm/ADT/SmallString.h"
13+
#include "llvm/ADT/StringRef.h"
14+
15+
/// Appends \p Path to \p Base and returns the appended path.
16+
llvm::SmallString<128> appendPathNative(llvm::StringRef Base,
17+
llvm::StringRef Path);
18+
19+
/// Appends \p Path to \p Base and returns the appended path in posix style.
20+
llvm::SmallString<128> appendPathPosix(llvm::StringRef Base,
21+
llvm::StringRef Path);
22+
23+
void getMustacheHtmlFiles(llvm::StringRef AssetsPath,
24+
clang::doc::ClangDocContext &CDCtx);
25+
26+
#endif

‎clang-tools-extra/clang-doc/tool/CMakeLists.txt‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -25,7 +25,7 @@ set(assets
2525
clang-doc-default-stylesheet.css
2626
clang-doc-mustache.css
2727
class-template.mustache
28-
comments-template.mustache
28+
comment-template.mustache
2929
enum-template.mustache
3030
function-template.mustache
3131
namespace-template.mustache

‎clang-tools-extra/unittests/clang-doc/CMakeLists.txt‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,10 +4,21 @@ set(LLVM_LINK_COMPONENTS
44
FrontendOpenMP
55
)
66

7+
# Unittests need access to mustache template files, so we use a config file to
8+
# inject those into a config.h header that can provide it to the unittests.
9+
set(CLANG_DOC_TEST_ASSET_DIR "${LLVM_RUNTIME_OUTPUT_INTDIR}/../share/clang-doc")
10+
configure_file(
11+
"${CMAKE_CURRENT_SOURCE_DIR}/config.h.cmake"
12+
"${CMAKE_CURRENT_BINARY_DIR}/config.h"
13+
)
14+
15+
# The config.h file is in ${CMAKE_CURRENT_BINARY_DIR}, so add it to
16+
# include_directories.
717
get_filename_component(CLANG_DOC_SOURCE_DIR
818
${CMAKE_CURRENT_SOURCE_DIR}/../../clang-doc REALPATH)
919
include_directories(
1020
${CLANG_DOC_SOURCE_DIR}
21+
${CMAKE_CURRENT_BINARY_DIR}
1122
)
1223

1324
add_extra_unittest(ClangDocTests

‎clang-tools-extra/unittests/clang-doc/HTMLMustacheGeneratorTest.cpp‎

Lines changed: 9 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,8 @@
99
#include "ClangDocTest.h"
1010
#include "Generators.h"
1111
#include "Representation.h"
12+
#include "config.h"
13+
#include "support/Utils.h"
1214
#include "clang/Basic/Version.h"
1315
#include "llvm/Support/Path.h"
1416
#include "llvm/Testing/Support/Error.h"
@@ -86,8 +88,13 @@ TEST(HTMLMustacheGeneratorTest, generateDocs) {
8688
assert(G && "Could not find HTMLMustacheGenerator");
8789
ClangDocContext CDCtx = getClangDocContext();
8890

89-
StringRef RootDir = "";
90-
EXPECT_THAT_ERROR(G->generateDocs(RootDir, {}, CDCtx), Succeeded())
91+
unittest::TempDir RootTestDirectory("generateDocsTest", /*Unique=*/true);
92+
CDCtx.OutDirectory = RootTestDirectory.path();
93+
94+
getMustacheHtmlFiles(CLANG_DOC_TEST_ASSET_DIR, CDCtx);
95+
96+
EXPECT_THAT_ERROR(G->generateDocs(RootTestDirectory.path(), {}, CDCtx),
97+
Succeeded())
9198
<< "Failed to generate docs.";
9299
}
93100

‎clang-tools-extra/unittests/clang-doc/config.h.cmake‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
#ifndef CLANG_TOOLS_EXTRA_UNITTESTS_CLANG_DOC_CONFIG_H
2+
#define CLANG_TOOLS_EXTRA_UNITTESTS_CLANG_DOC_CONFIG_H
3+
4+
#define CLANG_DOC_TEST_ASSET_DIR "${CLANG_DOC_TEST_ASSET_DIR}"
5+
6+
#endif // CLANG_TOOLS_EXTRA_UNITTESTS_CLANG_DOC_CONFIG_H

0 commit comments

Comments
 (0)