[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]>

Author: ilovepi

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();
 }
 

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

@@ -6,4 +6,5 @@ set(LLVM_LINK_COMPONENTS
 
 add_clang_library(clangDocSupport STATIC
   File.cpp
-  )
+  Utils.cpp
+  )

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

@@ -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()});
+}

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

@@ -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

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

@@ -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

clang-tools-extra/clang-doc/tool/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

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

@@ -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.";
 }
 

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

@@ -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