[clang-doc] add option to delete JSON residuals

[evelez7]

This new option defaults to delete the json dir after HTML generation.

[evelez7]

Warning

This pull request is not mergeable via GitHub because a downstack PR is open. Once all requirements are satisfied, merge this PR as a stack on Graphite.
Learn more

• [clang-doc] add option to delete JSON residuals #150656 👈 (View in Graphite)
• [clang-doc] place HTML/JSON output inside their own directories #150655
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[llvmbot]

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

Author: Erick Velez (evelez7)

Changes

This new option defaults to delete the json dir after HTML generation.

---

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

6 Files Affected:

• (modified) clang-tools-extra/clang-doc/HTMLMustacheGenerator.cpp (+3)
• (modified) clang-tools-extra/clang-doc/Representation.cpp (+2-2)
• (modified) clang-tools-extra/clang-doc/Representation.h (+2-1)
• (modified) clang-tools-extra/clang-doc/tool/ClangDocMain.cpp (+6)
• (modified) clang-tools-extra/unittests/clang-doc/HTMLGeneratorTest.cpp (+2-2)
• (modified) clang-tools-extra/unittests/clang-doc/HTMLMustacheGeneratorTest.cpp (+2-2)

diff --git a/clang-tools-extra/clang-doc/HTMLMustacheGenerator.cpp b/clang-tools-extra/clang-doc/HTMLMustacheGenerator.cpp
index 1ab40aacbfe09..4e225f721a9e7 100644
--- a/clang-tools-extra/clang-doc/HTMLMustacheGenerator.cpp
+++ b/clang-tools-extra/clang-doc/HTMLMustacheGenerator.cpp
@@ -196,6 +196,9 @@ Error MustacheHTMLGenerator::generateDocs(
     }
   }
 
+  if (!CDCtx.KeepJSON)
+    sys::fs::remove_directories(JSONPath);
+
   return Error::success();
 }
 
diff --git a/clang-tools-extra/clang-doc/Representation.cpp b/clang-tools-extra/clang-doc/Representation.cpp
index 79850e1f90253..e9a557e96e0a1 100644
--- a/clang-tools-extra/clang-doc/Representation.cpp
+++ b/clang-tools-extra/clang-doc/Representation.cpp
@@ -481,9 +481,9 @@ ClangDocContext::ClangDocContext(tooling::ExecutionContext *ECtx,
                                  StringRef RepositoryUrl,
                                  StringRef RepositoryLinePrefix, StringRef Base,
                                  std::vector<std::string> UserStylesheets,
-                                 bool FTimeTrace)
+                                 bool KeepJSON, bool FTimeTrace)
     : ECtx(ECtx), ProjectName(ProjectName), PublicOnly(PublicOnly),
-      FTimeTrace(FTimeTrace), OutDirectory(OutDirectory),
+      FTimeTrace(FTimeTrace), KeepJSON(KeepJSON), OutDirectory(OutDirectory),
       UserStylesheets(UserStylesheets), Base(Base) {
   llvm::SmallString<128> SourceRootDir(SourceRoot);
   if (SourceRoot.empty())
diff --git a/clang-tools-extra/clang-doc/Representation.h b/clang-tools-extra/clang-doc/Representation.h
index 2a75f89696b7d..ddb8f3abbee27 100644
--- a/clang-tools-extra/clang-doc/Representation.h
+++ b/clang-tools-extra/clang-doc/Representation.h
@@ -610,11 +610,12 @@ struct ClangDocContext {
                   bool PublicOnly, StringRef OutDirectory, StringRef SourceRoot,
                   StringRef RepositoryUrl, StringRef RepositoryCodeLinePrefix,
                   StringRef Base, std::vector<std::string> UserStylesheets,
-                  bool FTimeTrace = false);
+                  bool KeepJSON, bool FTimeTrace = false);
   tooling::ExecutionContext *ECtx;
   std::string ProjectName; // Name of project clang-doc is documenting.
   bool PublicOnly; // Indicates if only public declarations are documented.
   bool FTimeTrace; // Indicates if ftime trace is turned on
+  bool KeepJSON; // Indicates if JSON files should be kept after HTML generation
   int Granularity; // Granularity of ftime trace
   std::string OutDirectory; // Directory for outputting generated files.
   std::string SourceRoot;   // Directory where processed files are stored. Links
diff --git a/clang-tools-extra/clang-doc/tool/ClangDocMain.cpp b/clang-tools-extra/clang-doc/tool/ClangDocMain.cpp
index 3bb67baf65739..29a766d51084c 100644
--- a/clang-tools-extra/clang-doc/tool/ClangDocMain.cpp
+++ b/clang-tools-extra/clang-doc/tool/ClangDocMain.cpp
@@ -110,6 +110,11 @@ Turn on time profiler. Generates clang-doc-tracing.json)"),
                                       llvm::cl::init(false),
                                       llvm::cl::cat(ClangDocCategory));
 
+static llvm::cl::opt<bool>
+    KeepJSON("keep-json",
+             llvm::cl::desc("Keep JSON residuals after processing."),
+             llvm::cl::init(false), llvm::cl::cat(ClangDocCategory));
+
 enum OutputFormatTy { md, yaml, html, mustache, json };
 
 static llvm::cl::opt<OutputFormatTy> FormatEnum(
@@ -325,6 +330,7 @@ Example usage for a project using a compile commands database:
         RepositoryCodeLinePrefix,
         BaseDirectory,
         {UserStylesheets.begin(), UserStylesheets.end()},
+        KeepJSON,
         FTimeTrace};
 
     if (Format == "html") {
diff --git a/clang-tools-extra/unittests/clang-doc/HTMLGeneratorTest.cpp b/clang-tools-extra/unittests/clang-doc/HTMLGeneratorTest.cpp
index 143414354d36c..cf4541c0922ad 100644
--- a/clang-tools-extra/unittests/clang-doc/HTMLGeneratorTest.cpp
+++ b/clang-tools-extra/unittests/clang-doc/HTMLGeneratorTest.cpp
@@ -30,8 +30,8 @@ getClangDocContext(std::vector<std::string> UserStylesheets = {},
                    StringRef RepositoryUrl = "",
                    StringRef RepositoryLinePrefix = "", StringRef Base = "") {
   ClangDocContext CDCtx{
-      {},   "test-project", {}, {}, {}, RepositoryUrl, RepositoryLinePrefix,
-      Base, UserStylesheets};
+      {},   "test-project",  {}, {}, {}, RepositoryUrl, RepositoryLinePrefix,
+      Base, UserStylesheets, {}};
   CDCtx.UserStylesheets.insert(
       CDCtx.UserStylesheets.begin(),
       "../share/clang/clang-doc-default-stylesheet.css");
diff --git a/clang-tools-extra/unittests/clang-doc/HTMLMustacheGeneratorTest.cpp b/clang-tools-extra/unittests/clang-doc/HTMLMustacheGeneratorTest.cpp
index 602058f5d9eb8..a24598e0c93c0 100644
--- a/clang-tools-extra/unittests/clang-doc/HTMLMustacheGeneratorTest.cpp
+++ b/clang-tools-extra/unittests/clang-doc/HTMLMustacheGeneratorTest.cpp
@@ -41,8 +41,8 @@ getClangDocContext(std::vector<std::string> UserStylesheets = {},
                    StringRef RepositoryUrl = "",
                    StringRef RepositoryLinePrefix = "", StringRef Base = "") {
   ClangDocContext CDCtx{
-      {},   "test-project", {}, {}, {}, RepositoryUrl, RepositoryLinePrefix,
-      Base, UserStylesheets};
+      {},   "test-project",  {}, {}, {}, RepositoryUrl, RepositoryLinePrefix,
+      Base, UserStylesheets, {}};
   CDCtx.UserStylesheets.insert(CDCtx.UserStylesheets.begin(), "");
   CDCtx.JsScripts.emplace_back("");
   return CDCtx;

[evelez7]

It'd be nice to have a test for this but I'm not sure how to check for the existence of something after a LIT test is done.

[ilovepi]

does this actually need to be in the context? you have a cl::opt, right? it doesn't have to be a static variable, and then you could use it from other TUs. This is pretty common in LLVM.

Alternatively, the cl::opt could just be in the mustache generator, since its the only generator that uses it.

[ilovepi]

Suggested change

	{}, "test-project", {}, {}, {}, RepositoryUrl, RepositoryLinePrefix,
	{}, "test-project", {}, {}, {}, RepositoryUrl, RepositoryLinePrefix,

Seems like an extra space slipped in.

[ilovepi]

It'd be nice to have a test for this but I'm not sure how to check for the existence of something after a LIT test is done.

Why not just another RUN line?