Thanks to visit codestin.com
Credit goes to github.com

Skip to content

[clang-doc] Add HTMLMustacheGenerator methods #138061

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: users/ilovepi/clang-doc-mustache-basic
Choose a base branch
from

Conversation

ilovepi
Copy link
Contributor

@ilovepi ilovepi commented May 1, 2025

Split from #133161. This patch fills in the implementation for a number
of the MustacheHTMLGenerator methods. Many of these APIs are just
stubbed out, and will have their implementation filled in by later
patches.

Co-authored-by: Peter Chou [email protected]

@llvmbot
Copy link
Member

llvmbot commented May 1, 2025

@llvm/pr-subscribers-clang-tools-extra

Author: Paul Kirth (ilovepi)

Changes

Split from #133161. This patch fills in the implementation for a number
of the MustacheHTMLGenerator methods. Many of these APIs are just
stubbed out, and will have their implementation filled in by later
patches.

Co-authored-by: Peter Chou <[email protected]>


Full diff: https://github.com/llvm/llvm-project/pull/138061.diff

1 Files Affected:

  • (modified) clang-tools-extra/clang-doc/HTMLMustacheGenerator.cpp (+102)
diff --git a/clang-tools-extra/clang-doc/HTMLMustacheGenerator.cpp b/clang-tools-extra/clang-doc/HTMLMustacheGenerator.cpp
index 65e8e34b581d2..1288e4fbbc983 100644
--- a/clang-tools-extra/clang-doc/HTMLMustacheGenerator.cpp
+++ b/clang-tools-extra/clang-doc/HTMLMustacheGenerator.cpp
@@ -56,17 +56,119 @@ class MustacheTemplateFile : public Template {
 
   MustacheTemplateFile(StringRef TemplateStr) : Template(TemplateStr) {}
 };
+
+static std::unique_ptr<MustacheTemplateFile> NamespaceTemplate = nullptr;
+
+static std::unique_ptr<MustacheTemplateFile> RecordTemplate = nullptr;
+
+static Error setupTemplateFiles(const clang::doc::ClangDocContext &CDCtx) {
+  return Error::success();
+}
+
 Error MustacheHTMLGenerator::generateDocs(
     StringRef RootDir, StringMap<std::unique_ptr<doc::Info>> Infos,
     const clang::doc::ClangDocContext &CDCtx) {
+  if (auto Err = setupTemplateFiles(CDCtx))
+    return Err;
+  // Track which directories we already tried to create.
+  StringSet<> CreatedDirs;
+  // Collect all output by file name and create the necessary directories.
+  StringMap<std::vector<doc::Info *>> FileToInfos;
+  for (const auto &Group : Infos) {
+    doc::Info *Info = Group.getValue().get();
+
+    SmallString<128> Path;
+    sys::path::native(RootDir, Path);
+    sys::path::append(Path, Info->getRelativeFilePath(""));
+    if (!CreatedDirs.contains(Path)) {
+      if (std::error_code Err = sys::fs::create_directories(Path);
+          Err != std::error_code())
+        return createStringError(Err, "Failed to create directory '%s'.",
+                                 Path.c_str());
+      CreatedDirs.insert(Path);
+    }
+
+    sys::path::append(Path, Info->getFileBaseName() + ".html");
+    FileToInfos[Path].push_back(Info);
+  }
+
+  for (const auto &Group : FileToInfos) {
+    std::error_code FileErr;
+    raw_fd_ostream InfoOS(Group.getKey(), FileErr, sys::fs::OF_None);
+    if (FileErr)
+      return createStringError(FileErr, "Error opening file '%s'",
+                               Group.getKey().data());
+
+    for (const auto &Info : Group.getValue()) {
+      if (Error Err = generateDocForInfo(Info, InfoOS, CDCtx))
+        return Err;
+    }
+  }
   return Error::success();
 }
+
+static json::Value extractValue(const NamespaceInfo &I,
+                                const ClangDocContext &CDCtx) {
+  Object NamespaceValue = Object();
+  return NamespaceValue;
+}
+
+static json::Value extractValue(const RecordInfo &I,
+                                const ClangDocContext &CDCtx) {
+  Object RecordValue = Object();
+  return RecordValue;
+}
+
+static void setupTemplateValue(const ClangDocContext &CDCtx, json::Value &V,
+                               Info *I) {}
+
 Error MustacheHTMLGenerator::generateDocForInfo(Info *I, raw_ostream &OS,
                                                 const ClangDocContext &CDCtx) {
+  switch (I->IT) {
+  case InfoType::IT_namespace: {
+    json::Value V =
+        extractValue(*static_cast<clang::doc::NamespaceInfo *>(I), CDCtx);
+    setupTemplateValue(CDCtx, V, I);
+    NamespaceTemplate->render(V, OS);
+    break;
+  }
+  case InfoType::IT_record: {
+    json::Value V =
+        extractValue(*static_cast<clang::doc::RecordInfo *>(I), CDCtx);
+    setupTemplateValue(CDCtx, V, I);
+    // Serialize the JSON value to the output stream in a readable format.
+    outs() << "Visit: " << I->Name << "\n";
+    // outs() << formatv("{0:2}", V) << "\n";
+    RecordTemplate->render(V, outs());
+    break;
+  }
+  case InfoType::IT_enum:
+    outs() << "IT_enum\n";
+    break;
+  case InfoType::IT_function:
+    outs() << "IT_Function\n";
+    break;
+  case InfoType::IT_typedef:
+    outs() << "IT_typedef\n";
+    break;
+  case InfoType::IT_default:
+    return createStringError(inconvertibleErrorCode(), "unexpected InfoType");
+  }
   return Error::success();
 }
+
 Error MustacheHTMLGenerator::createResources(ClangDocContext &CDCtx) {
   Error Err = Error::success();
+  for (const auto &FilePath : CDCtx.UserStylesheets) {
+    Err = copyFile(FilePath, CDCtx.OutDirectory);
+    if (Err)
+      return Err;
+  }
+  for (const auto &FilePath : CDCtx.JsScripts) {
+    Err = copyFile(FilePath, CDCtx.OutDirectory);
+    if (Err)
+      return Err;
+  }
   return Error::success();
 }
 

@ilovepi ilovepi force-pushed the users/ilovepi/clang-doc-mustache-basic branch from 397d5dc to 5773942 Compare May 6, 2025 21:33
@ilovepi ilovepi force-pushed the users/ilovepi/clang-doc-mustache-generators branch from 57c7cf8 to 5b34441 Compare May 6, 2025 21:33
Copy link

github-actions bot commented May 6, 2025

✅ With the latest revision this PR passed the C/C++ code formatter.

@ilovepi ilovepi force-pushed the users/ilovepi/clang-doc-mustache-generators branch 2 times, most recently from 10fe47d to 48e9893 Compare May 7, 2025 01:59
@ilovepi ilovepi force-pushed the users/ilovepi/clang-doc-mustache-basic branch from 5773942 to 6098ca3 Compare May 7, 2025 01:59
Comment on lines +148 to +155
case InfoType::IT_enum:
OS << "IT_enum\n";
break;
case InfoType::IT_function:
OS << "IT_Function\n";
break;
case InfoType::IT_typedef:
OS << "IT_typedef\n";
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@PeterChou1 I don't see the implementation for these up the stack. Did you ever get these working? Your example webpage had things for Enums and Functions IIRC. Do yo have time to help w/ this and/or reviews?

@ilovepi ilovepi force-pushed the users/ilovepi/clang-doc-mustache-generators branch from 48e9893 to dd0bf73 Compare May 7, 2025 03:23
@ilovepi ilovepi force-pushed the users/ilovepi/clang-doc-mustache-basic branch 2 times, most recently from 77d9ece to c4fd639 Compare May 7, 2025 03:25
@ilovepi ilovepi force-pushed the users/ilovepi/clang-doc-mustache-generators branch 2 times, most recently from b67b6ac to ffafdb7 Compare May 7, 2025 03:26
@ilovepi ilovepi force-pushed the users/ilovepi/clang-doc-mustache-basic branch 2 times, most recently from d5b198f to a4ebe3e Compare May 7, 2025 03:33
@ilovepi ilovepi force-pushed the users/ilovepi/clang-doc-mustache-generators branch from ffafdb7 to f919251 Compare May 7, 2025 03:34
std::error_code FileErr;
raw_fd_ostream InfoOS(Group.getKey(), FileErr, sys::fs::OF_None);
if (FileErr)
return createStringError(FileErr, "Error opening file '%s'",
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
return createStringError(FileErr, "Error opening file '%s'",
return createStringError(FileErr, "error opening file '%s'",

@petrhosek
Copy link
Member

Here's an idea that doesn't need to be addressed in this PR.

We already have the YAML backend for Clang-doc which is primarily used for testing and also to allow external backends. We chose YAML because back when we started working on it, there was no JSON support in LLVM, but today I think we would have gone with JSON since it's more universally supported (e.g. in languages like Go or Python it's part of the standard library as opposed to YAML).

What if we replaced the YAML backend with JSON backend? We could then use its output with the Mustache templates rather than building what is essentially an internal JSON backend inside the HTMLMustacheGenerator. We could do the same for Markdown as well, using a different set of Mustache templates with the output from the JSON backend.

@ilovepi ilovepi force-pushed the users/ilovepi/clang-doc-mustache-generators branch from f919251 to abc97d2 Compare May 7, 2025 17:10
@ilovepi ilovepi force-pushed the users/ilovepi/clang-doc-mustache-basic branch from a4ebe3e to 027a37d Compare May 7, 2025 17:10
Copy link
Contributor Author

ilovepi commented May 7, 2025

I think that's a solid direction. I've already been thinking that we'd probably want to start consolidating the other backends around Mustache templates. I think too much duplication/reimplementation/lack of abstraction is one of the big issues w/ clang-doc's implementation ATM. Having to copy large parts of the tests from the HTMLGenerator, kind of shows that.

Split from #133161. This patch fills in the implementation for a number
of the MustacheHTMLGenerator methods. Many of these APIs are just
stubbed out, and will have their implementation filled in by later
patches.

Co-authored-by: Peter Chou <[email protected]>
@ilovepi ilovepi force-pushed the users/ilovepi/clang-doc-mustache-generators branch from abc97d2 to 5c5bacb Compare May 7, 2025 17:19
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants