Skip to content

[clang-doc] Allow setting a base directory for hosted pages #132482

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.

Sign up for GitHub

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

Merged
merged 1 commit into from
Mar 28, 2025
Merged

[clang-doc] Allow setting a base directory for hosted pages #132482

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions clang-tools-extra/clang-doc/HTMLGenerator.cpp
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1078,6 +1078,11 @@ static llvm::Error serializeIndex(ClangDocContext &CDCtx) {
std::replace(RootPathEscaped.begin(), RootPathEscaped.end(), '\\', '/');
OS << "var RootPath = \"" << RootPathEscaped << "\";\n";

llvm::SmallString<128> Base(CDCtx.Base);
std::string BaseEscaped = Base.str().str();
std::replace(BaseEscaped.begin(), BaseEscaped.end(), '\\', '/');
OS << "var Base = \"" << BaseEscaped << "\";\n";

CDCtx.Idx.sort();
llvm::json::OStream J(OS, 2);
std::function<void(Index)> IndexToJSON = [&](const Index &I) {
Expand Down
4 changes: 2 additions & 2 deletions clang-tools-extra/clang-doc/Representation.cpp
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -367,10 +367,10 @@ void Index::sort() {
ClangDocContext::ClangDocContext(tooling::ExecutionContext *ECtx,
StringRef ProjectName, bool PublicOnly,
StringRef OutDirectory, StringRef SourceRoot,
StringRef RepositoryUrl,
StringRef RepositoryUrl, StringRef Base,
std::vector<std::string> UserStylesheets)
: ECtx(ECtx), ProjectName(ProjectName), PublicOnly(PublicOnly),
OutDirectory(OutDirectory), UserStylesheets(UserStylesheets) {
OutDirectory(OutDirectory), UserStylesheets(UserStylesheets), Base(Base) {
llvm::SmallString<128> SourceRootDir(SourceRoot);
if (SourceRoot.empty())
// If no SourceRoot was provided the current path is used as the default
Expand Down
3 changes: 2 additions & 1 deletion clang-tools-extra/clang-doc/Representation.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -507,7 +507,7 @@ struct ClangDocContext {
ClangDocContext() = default;
ClangDocContext(tooling::ExecutionContext *ECtx, StringRef ProjectName,
bool PublicOnly, StringRef OutDirectory, StringRef SourceRoot,
StringRef RepositoryUrl,
StringRef RepositoryUrl, StringRef Base,
std::vector<std::string> UserStylesheets);
tooling::ExecutionContext *ECtx;
std::string ProjectName; // Name of project clang-doc is documenting.
Expand All @@ -523,6 +523,7 @@ struct ClangDocContext {
std::vector<std::string> UserStylesheets;
// JavaScript files that will be imported in all HTML files.
std::vector<std::string> JsScripts;
StringRef Base;
Index Idx;
};

Expand Down
7 changes: 4 additions & 3 deletions clang-tools-extra/clang-doc/assets/index.js
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,9 +1,10 @@
function genLink(Ref) {
Copy link
Member

@petrhosek petrhosek Mar 25, 2025

Choose a reason for hiding this comment

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

It looks like we always invoke this function with two arguments: Index and CurrentDirectory, but we actually ignore the second argument and don't even specify it in the function signature. Do you know what is CurrentDirectory meant for? Could it perhaps be used instead of Base?

Copy link
Contributor Author

@ilovepi ilovepi Mar 26, 2025

Choose a reason for hiding this comment

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

Looks like the current directory was left around when we moved from relative paths to absolute. I don't think we can use that instead of base, though.

When I log what the CurrentDirectory is on docs.fuchsia.dev/cpp using chrome tools, it ends up empty, so I think we may still need to use Base. i'll take another look at the JS though.

// we treat the file paths different depending on if we're
// serving via a http server or viewing from a local
var Path = window.location.protocol.startsWith("file") ?
`${window.location.protocol}//${RootPath}/${Ref.Path}` :
`${window.location.protocol}//${window.location.host}/${Ref.Path}`;
var Path = window.location.protocol.startsWith("file")
? `${window.location.protocol}//${RootPath}/${Ref.Path}`
: `${window.location.protocol}//${window.location.host}/${
Base}/${Ref.Path}`;
if (Ref.RefType === "namespace") {
Path = `${Path}/index.html`
} else if (Ref.Path === "") {
Expand Down
13 changes: 9 additions & 4 deletions clang-tools-extra/clang-doc/tool/ClangDocMain.cpp
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -67,6 +67,12 @@ static llvm::cl::opt<std::string>
llvm::cl::desc("Directory for outputting generated files."),
llvm::cl::init("docs"), llvm::cl::cat(ClangDocCategory));

static llvm::cl::opt<std::string>
BaseDirectory("base",
llvm::cl::desc(R"(Base Directory for generated documentation.
URLs will be rooted at this directory for HTML links.)"),
llvm::cl::init(""), llvm::cl::cat(ClangDocCategory));

static llvm::cl::opt<bool>
PublicOnly("public", llvm::cl::desc("Document only public declarations."),
llvm::cl::init(false), llvm::cl::cat(ClangDocCategory));
Expand Down Expand Up @@ -141,8 +147,7 @@ llvm::Error getAssetFiles(clang::doc::ClangDocContext &CDCtx) {
using DirIt = llvm::sys::fs::directory_iterator;
std::error_code FileErr;
llvm::SmallString<128> FilePath(UserAssetPath);
for (DirIt DirStart = DirIt(UserAssetPath, FileErr),
DirEnd;
for (DirIt DirStart = DirIt(UserAssetPath, FileErr), DirEnd;
!FileErr && DirStart != DirEnd; DirStart.increment(FileErr)) {
FilePath = DirStart->path();
if (llvm::sys::fs::is_regular_file(FilePath)) {
Expand Down Expand Up @@ -268,8 +273,8 @@ Example usage for a project using a compile commands database:
OutDirectory,
SourceRoot,
RepositoryUrl,
{UserStylesheets.begin(), UserStylesheets.end()}
};
BaseDirectory,
{UserStylesheets.begin(), UserStylesheets.end()}};

if (Format == "html") {
if (auto Err = getHtmlAssetFiles(argv[0], CDCtx)) {
Expand Down
4 changes: 2 additions & 2 deletions clang-tools-extra/test/clang-doc/assets.cpp
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
// RUN: rm -rf %t && mkdir %t
// RUN: clang-doc --format=html --output=%t --asset=%S/Inputs/test-assets --executor=standalone %s
// RUN: clang-doc --format=html --output=%t --asset=%S/Inputs/test-assets --executor=standalone %s --base base_dir
// RUN: FileCheck %s -input-file=%t/index.html -check-prefix=INDEX
// RUN: FileCheck %s -input-file=%t/test.css -check-prefix=CSS
// RUN: FileCheck %s -input-file=%t/test.js -check-prefix=JS
Expand All @@ -19,4 +19,4 @@
// CSS-NEXT: padding: 0;
// CSS-NEXT: }

// JS: console.log("Hello, world!");
// JS: console.log("Hello, world!");
4 changes: 3 additions & 1 deletion clang-tools-extra/test/clang-doc/test-path-abs.cpp
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,7 @@
// RUN: rm -rf %t && mkdir -p %t
// RUN: clang-doc --format=html --executor=standalone %s --output=%t
// RUN: clang-doc --format=html --executor=standalone %s --output=%t --base base_dir
// RUN: FileCheck %s -input-file=%t/index_json.js -check-prefix=JSON-INDEX

// JSON-INDEX: var RootPath = "{{.*}}test-path-abs.cpp.tmp";
// JSON-INDEX-NEXT: var Base = "base_dir";

6 changes: 3 additions & 3 deletions clang-tools-extra/unittests/clang-doc/HTMLGeneratorTest.cpp
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,9 +28,9 @@ std::unique_ptr<Generator> getHTMLGenerator() {

ClangDocContext
getClangDocContext(std::vector<std::string> UserStylesheets = {},
StringRef RepositoryUrl = "") {
ClangDocContext CDCtx{
{}, "test-project", {}, {}, {}, RepositoryUrl, UserStylesheets};
StringRef RepositoryUrl = "", StringRef Base = "") {
ClangDocContext CDCtx{{}, "test-project", {}, {},
{}, RepositoryUrl, Base, UserStylesheets};
CDCtx.UserStylesheets.insert(
CDCtx.UserStylesheets.begin(),
"../share/clang/clang-doc-default-stylesheet.css");
Expand Down