[clang-doc] add async loading #93276
Merged
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
|
@llvm/pr-subscribers-clang-tools-extra Author: None (PeterChou1) Changesrelevant issue: #93273 Full diff: https://github.com/llvm/llvm-project/pull/93276.diff 5 Files Affected:
diff --git a/clang-tools-extra/clang-doc/HTMLGenerator.cpp b/clang-tools-extra/clang-doc/HTMLGenerator.cpp
index c0faf5f7e8fd9..fd3807014fd09 100644
--- a/clang-tools-extra/clang-doc/HTMLGenerator.cpp
+++ b/clang-tools-extra/clang-doc/HTMLGenerator.cpp
@@ -964,7 +964,7 @@ static llvm::Error SerializeIndex(ClangDocContext &CDCtx) {
std::error_code FileErr;
llvm::SmallString<128> FilePath;
llvm::sys::path::native(CDCtx.OutDirectory, FilePath);
- llvm::sys::path::append(FilePath, "index_json.js");
+ llvm::sys::path::append(FilePath, "index.json");
llvm::raw_fd_ostream OS(FilePath, FileErr, llvm::sys::fs::OF_None);
if (FileErr != OK) {
return llvm::createStringError(llvm::inconvertibleErrorCode(),
@@ -985,9 +985,7 @@ static llvm::Error SerializeIndex(ClangDocContext &CDCtx) {
});
});
};
- OS << "var JsonIndex = `\n";
IndexToJSON(CDCtx.Idx);
- OS << "`;\n";
return llvm::Error::success();
}
@@ -1050,30 +1048,33 @@ static llvm::Error CopyFile(StringRef FilePath, StringRef OutDirectory) {
if (FileErr != OK) {
return llvm::createStringError(llvm::inconvertibleErrorCode(),
"error creating file " +
- llvm::sys::path::filename(FilePath) +
+ FilePath +
": " + FileErr.message() + "\n");
}
return llvm::Error::success();
}
llvm::Error HTMLGenerator::createResources(ClangDocContext &CDCtx) {
- auto Err = SerializeIndex(CDCtx);
- if (Err)
+ if (auto Err = SerializeIndex(CDCtx)) {
return Err;
- Err = GenIndex(CDCtx);
- if (Err)
+ }
+
+ if (auto Err = GenIndex(CDCtx)) {
return Err;
+ }
for (const auto &FilePath : CDCtx.UserStylesheets) {
- Err = CopyFile(FilePath, CDCtx.OutDirectory);
- if (Err)
+ if (auto Err = CopyFile(FilePath, CDCtx.OutDirectory)) {
return Err;
+ }
}
+
for (const auto &FilePath : CDCtx.FilesToCopy) {
- Err = CopyFile(FilePath, CDCtx.OutDirectory);
- if (Err)
+ if (auto Err = CopyFile(FilePath, CDCtx.OutDirectory)) {
return Err;
+ }
}
+
return llvm::Error::success();
}
diff --git a/clang-tools-extra/clang-doc/Representation.h b/clang-tools-extra/clang-doc/Representation.h
index a6b144eb7fa2a..23323f1cbdf46 100644
--- a/clang-tools-extra/clang-doc/Representation.h
+++ b/clang-tools-extra/clang-doc/Representation.h
@@ -491,6 +491,7 @@ struct ClangDocContext {
std::string SourceRoot; // Directory where processed files are stored. Links
// to definition locations will only be generated if
// the file is in this dir.
+
// URL of repository that hosts code used for links to definition locations.
std::optional<std::string> RepositoryUrl;
// Path of CSS stylesheets that will be copied to OutDirectory and used to
diff --git a/clang-tools-extra/clang-doc/Serialize.cpp b/clang-tools-extra/clang-doc/Serialize.cpp
index 3b074d849e8a9..49062af637ea0 100644
--- a/clang-tools-extra/clang-doc/Serialize.cpp
+++ b/clang-tools-extra/clang-doc/Serialize.cpp
@@ -32,6 +32,7 @@ populateParentNamespaces(llvm::SmallVector<Reference, 4> &Namespaces,
static void populateMemberTypeInfo(MemberTypeInfo &I, const FieldDecl *D);
+
// A function to extract the appropriate relative path for a given info's
// documentation. The path returned is a composite of the parent namespaces.
//
diff --git a/clang-tools-extra/clang-doc/assets/index.js b/clang-tools-extra/clang-doc/assets/index.js
index a5ac90f2e06e7..b659b20069ac5 100644
--- a/clang-tools-extra/clang-doc/assets/index.js
+++ b/clang-tools-extra/clang-doc/assets/index.js
@@ -82,6 +82,9 @@ function createIndex(Index) {
document.addEventListener("DOMContentLoaded", function() {
// JsonIndex is a variable from another file that contains the index
// in JSON format
- var Index = JSON.parse(JsonIndex);
- createIndex(Index);
+ fetch("/index.json")
+ .then((response) => response.json())
+ .then((Index) => {
+ createIndex(Index);
+ });
});
diff --git a/clang-tools-extra/clang-doc/tool/ClangDocMain.cpp b/clang-tools-extra/clang-doc/tool/ClangDocMain.cpp
index 21b581fa6df2e..af892b5402092 100644
--- a/clang-tools-extra/clang-doc/tool/ClangDocMain.cpp
+++ b/clang-tools-extra/clang-doc/tool/ClangDocMain.cpp
@@ -155,6 +155,10 @@ Example usage for a project using a compile commands database:
return 1;
}
+ // add option to customize url fragment
+ // such as https://github.com/llvm/llvm-project/blob/main/clang-tools-extra/clang-doc/ClangDocMain.cpp#L1
+
+
// Fail early if an invalid format was provided.
std::string Format = getFormatString();
llvm::outs() << "Emiting docs in " << Format << " format.\n";
@@ -179,7 +183,7 @@ Example usage for a project using a compile commands database:
SourceRoot,
RepositoryUrl,
{UserStylesheets.begin(), UserStylesheets.end()},
- {"index.js", "index_json.js"}};
+ {"index.js"}};
if (Format == "html") {
void *MainAddr = (void *)(intptr_t)GetExecutablePath;
@@ -201,6 +205,7 @@ Example usage for a project using a compile commands database:
CDCtx.FilesToCopy.emplace_back(IndexJS.str());
}
+
// Mapping phase
llvm::outs() << "Mapping decls...\n";
auto Err =
|
|
✅ With the latest revision this PR passed the C/C++ code formatter. |
PeterChou1
force-pushed
the
clang-doc-async
branch
from
0fa00f0 to
0b6d536
Compare
ilovepi
requested changes
May 24, 2024
There was a problem hiding this comment.
I've noted several items that need to be addressed in line before this lands. Both the commit title and description need to be updated. Please add a tag [clang-doc] to the commit title, and include the full details of the problem you're addressing and how this patch addresses them in the description.
If this fixes the issue you've referenced, add Fixes #93273 after the body of the descripton. You can find more info on GitHub interactions w/ commits here https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue
Lastly, this patch badly needs tests. Please create a PR with that demonstrates the existing behavior in a test (or tests) that we can land first. You can rebase this patch on top of it, and we can easily understand the delta between the new and old behaviors based on how the test changed.
ilovepi
approved these changes
Jun 29, 2024
There was a problem hiding this comment.
LGTM modulo some minor nits, but please revise the commit message. The end is not clear, and looks like it may be a copy paste error. If you know how much this improves the performance/responsiveness of the generated documentation, that would also be good to include.
ilovepi
reviewed
Jun 29, 2024
|
LLVM Buildbot has detected a new failure on builder Full details are available at: https://lab.llvm.org/buildbot/#/builders/46/builds/863 Here is the relevant piece of the build log for the reference: |
lravenclaw
pushed a commit
to lravenclaw/llvm-project
that referenced
this pull request
Jul 3, 2024
Fixes llvm#93273 This patch changes the way clang-doc loads html indexes. Previously clang-doc loaded the index via an index_json.js file which uses JSON.parse to parse the file. This patches changes that to use an async function called LoadIndex which enables asynchronous loading making the initial page load not be blocked by loading a large JavaScript object.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Fixes #93273
This patch changes the way clang-doc loads html indexes. Previously clang-doc loaded the index via an index_json.js file which uses JSON.parse to parse the file. This patches changes that to use an async function called LoadIndex which enables asynchronous loading making the initial page load not be blocked by loading a large js object