[clang-tools-extra] [clang-doc] switched from using relative to absolute paths (PR #93281)
via cfe-commits
cfe-commits at lists.llvm.org
Sun Jun 30 00:23:05 PDT 2024
https://github.com/PeterChou1 updated https://github.com/llvm/llvm-project/pull/93281
>From f5872e7c82d097ae3c141765d3f1d7e3d0b25b82 Mon Sep 17 00:00:00 2001
From: PeterChou1 <peter.chou at mail.utoronto.ca>
Date: Fri, 24 May 2024 04:28:08 -0400
Subject: [PATCH 1/6] clang-doc switched from using relative to absolute paths
---
clang-tools-extra/clang-doc/assets/index.js | 72 ++++++++++-----------
1 file changed, 35 insertions(+), 37 deletions(-)
diff --git a/clang-tools-extra/clang-doc/assets/index.js b/clang-tools-extra/clang-doc/assets/index.js
index a5ac90f2e06e7..fe35e706cc98d 100644
--- a/clang-tools-extra/clang-doc/assets/index.js
+++ b/clang-tools-extra/clang-doc/assets/index.js
@@ -1,48 +1,46 @@
-// Append using posix-style a file name or directory to Base
-function append(Base, New) {
- if (!New)
- return Base;
- if (Base)
- Base += "/";
- Base += New;
- return Base;
-}
-
-// Get relative path to access FilePath from CurrentDirectory
-function computeRelativePath(FilePath, CurrentDirectory) {
- var Path = FilePath;
- while (Path) {
- if (CurrentDirectory == Path)
- return FilePath.substring(Path.length + 1);
- Path = Path.substring(0, Path.lastIndexOf("/"));
- }
-
- var Dir = CurrentDirectory;
- var Result = "";
- while (Dir) {
- if (Dir == FilePath)
- break;
- Dir = Dir.substring(0, Dir.lastIndexOf("/"));
- Result = append(Result, "..")
+function genLink(Ref) {
+ var Path = `${window.location.protocol}//${window.location.host}/${Ref.Path}`;
+ if (Ref.RefType !== "namespace") {
+ if (Ref.Path === "") {
+ Path = `${Path}${Ref.Name}.html`;
+ }
+ else {
+ Path = `${Path}/${Ref.Name}.html`;
+ }
}
- Result = append(Result, FilePath.substring(Dir.length))
- return Result;
-}
-
-function genLink(Ref, CurrentDirectory) {
- var Path = computeRelativePath(Ref.Path, CurrentDirectory);
- if (Ref.RefType == "namespace")
- Path = append(Path, "index.html");
- else
- Path = append(Path, Ref.Name + ".html")
- ANode = document.createElement("a");
+ ANode = document.createElement("a");
ANode.setAttribute("href", Path);
var TextNode = document.createTextNode(Ref.Name);
ANode.appendChild(TextNode);
return ANode;
}
+function genHTMLOfIndex(Index, CurrentDirectory, IsOutermostList) {
+ // Out will store the HTML elements that Index requires to be generated
+ var Out = [];
+ if (Index.Name) {
+ var SpanNode = document.createElement("span");
+ var TextNode = document.createTextNode(Index.Name);
+ SpanNode.appendChild(genLink(Index));
+ Out.push(SpanNode);
+ }
+ if (Index.Children.length == 0)
+ return Out;
+ // Only the outermost list should use ol, the others should use ul
+ var ListNodeName = IsOutermostList ? "ol" : "ul";
+ var ListNode = document.createElement(ListNodeName);
+ for (Child of Index.Children) {
+ var LiNode = document.createElement("li");
+ ChildNodes = genHTMLOfIndex(Child, CurrentDirectory, false);
+ for (Node of ChildNodes)
+ LiNode.appendChild(Node);
+ ListNode.appendChild(LiNode);
+ }
+ Out.push(ListNode);
+ return Out;
+}
+
function genHTMLOfIndex(Index, CurrentDirectory, IsOutermostList) {
// Out will store the HTML elements that Index requires to be generated
var Out = [];
>From a22609f75064194604e476a12bc8154676dacfb9 Mon Sep 17 00:00:00 2001
From: PeterChou1 <peter.chou at mail.utoronto.ca>
Date: Fri, 24 May 2024 05:10:03 -0400
Subject: [PATCH 2/6] remove duplicate function
---
clang-tools-extra/clang-doc/assets/index.js | 24 ---------------------
1 file changed, 24 deletions(-)
diff --git a/clang-tools-extra/clang-doc/assets/index.js b/clang-tools-extra/clang-doc/assets/index.js
index fe35e706cc98d..b013418c82093 100644
--- a/clang-tools-extra/clang-doc/assets/index.js
+++ b/clang-tools-extra/clang-doc/assets/index.js
@@ -16,30 +16,6 @@ function genLink(Ref) {
return ANode;
}
-function genHTMLOfIndex(Index, CurrentDirectory, IsOutermostList) {
- // Out will store the HTML elements that Index requires to be generated
- var Out = [];
- if (Index.Name) {
- var SpanNode = document.createElement("span");
- var TextNode = document.createTextNode(Index.Name);
- SpanNode.appendChild(genLink(Index));
- Out.push(SpanNode);
- }
- if (Index.Children.length == 0)
- return Out;
- // Only the outermost list should use ol, the others should use ul
- var ListNodeName = IsOutermostList ? "ol" : "ul";
- var ListNode = document.createElement(ListNodeName);
- for (Child of Index.Children) {
- var LiNode = document.createElement("li");
- ChildNodes = genHTMLOfIndex(Child, CurrentDirectory, false);
- for (Node of ChildNodes)
- LiNode.appendChild(Node);
- ListNode.appendChild(LiNode);
- }
- Out.push(ListNode);
- return Out;
-}
function genHTMLOfIndex(Index, CurrentDirectory, IsOutermostList) {
// Out will store the HTML elements that Index requires to be generated
>From be0fb1acdd97a07e665b61fbba44d32dd40e1b94 Mon Sep 17 00:00:00 2001
From: PeterChou1 <peter.chou at mail.utoronto.ca>
Date: Sat, 29 Jun 2024 05:16:41 -0400
Subject: [PATCH 3/6] [clang-doc] modify paths for anchors in js file
---
clang-tools-extra/clang-doc/HTMLGenerator.cpp | 12 ++++++++++++
clang-tools-extra/clang-doc/assets/index.js | 12 +++++++++---
clang-tools-extra/test/clang-doc/basic-project.test | 1 +
3 files changed, 22 insertions(+), 3 deletions(-)
diff --git a/clang-tools-extra/clang-doc/HTMLGenerator.cpp b/clang-tools-extra/clang-doc/HTMLGenerator.cpp
index 4c72b329507d3..1a99c0c063cfb 100644
--- a/clang-tools-extra/clang-doc/HTMLGenerator.cpp
+++ b/clang-tools-extra/clang-doc/HTMLGenerator.cpp
@@ -16,6 +16,7 @@
#include "llvm/Support/JSON.h"
#include "llvm/Support/Path.h"
#include "llvm/Support/raw_ostream.h"
+#include <algorithm>
#include <optional>
#include <string>
@@ -979,6 +980,17 @@ static llvm::Error serializeIndex(ClangDocContext &CDCtx) {
"error creating index file: " +
FileErr.message());
}
+ llvm::SmallString<128> RootPath(CDCtx.OutDirectory);
+ if (llvm::sys::path::is_relative(RootPath)) {
+ llvm::sys::fs::make_absolute(RootPath);
+ }
+ // replace escape character with forward slash it shouldn't matter
+ // when viewing from the browser this helps with preventing javascript
+ // from escaping unwanted characters leading to bad paths
+ std::string RootPathEscaped = RootPath.str().str();
+ std::replace(RootPathEscaped.begin(), RootPathEscaped.end(), '\\', '/');
+ OS << "var RootPath = \"" << RootPathEscaped << "\";\n";
+
CDCtx.Idx.sort();
llvm::json::OStream J(OS, 2);
std::function<void(Index)> IndexToJSON = [&](const Index &I) {
diff --git a/clang-tools-extra/clang-doc/assets/index.js b/clang-tools-extra/clang-doc/assets/index.js
index b013418c82093..eecac22b06e68 100644
--- a/clang-tools-extra/clang-doc/assets/index.js
+++ b/clang-tools-extra/clang-doc/assets/index.js
@@ -1,12 +1,19 @@
function genLink(Ref) {
var Path = `${window.location.protocol}//${window.location.host}/${Ref.Path}`;
+ var isFileProtocol = window.location.protocol.startsWith("file");
+ // we treat the file paths different depending on if we're
+ // serving via a http server or viewing from a local
+ if (isFileProtocol) {
+ Path = `${window.location.protocol}//${RootPath}/${Ref.Path}`;
+ }
if (Ref.RefType !== "namespace") {
if (Ref.Path === "") {
Path = `${Path}${Ref.Name}.html`;
- }
- else {
+ } else {
Path = `${Path}/${Ref.Name}.html`;
}
+ } else {
+ Path = `${Path}/index.html`
}
ANode = document.createElement("a");
@@ -16,7 +23,6 @@ function genLink(Ref) {
return ANode;
}
-
function genHTMLOfIndex(Index, CurrentDirectory, IsOutermostList) {
// Out will store the HTML elements that Index requires to be generated
var Out = [];
diff --git a/clang-tools-extra/test/clang-doc/basic-project.test b/clang-tools-extra/test/clang-doc/basic-project.test
index 3118c20495987..455fb28da0fb8 100644
--- a/clang-tools-extra/test/clang-doc/basic-project.test
+++ b/clang-tools-extra/test/clang-doc/basic-project.test
@@ -7,6 +7,7 @@
// RUN: FileCheck %s -input-file=%t/docs/GlobalNamespace/Rectangle.html -check-prefix=HTML-RECTANGLE
// RUN: FileCheck %s -input-file=%t/docs/GlobalNamespace/Circle.html -check-prefix=HTML-CIRCLE
+// JSON-INDEX: var RootPath = "{{.*}}";
// JSON-INDEX: var JsonIndex = `
// JSON-INDEX-NEXT: {
// JSON-INDEX-NEXT: "USR": "{{([0-9A-F]{40})}}",
>From 6415717b6eed67a427dde1c053a298755738e98c Mon Sep 17 00:00:00 2001
From: PeterChou1 <peter.chou at mail.utoronto.ca>
Date: Sun, 30 Jun 2024 02:56:43 -0400
Subject: [PATCH 4/6] [clang-doc] add test for asset paths
---
clang-tools-extra/clang-doc/HTMLGenerator.cpp | 7 ++++---
clang-tools-extra/clang-doc/assets/index.js | 19 +++++++------------
.../test/clang-doc/basic-project.test | 2 +-
.../test/clang-doc/test-path-abs.cpp | 7 +++++++
.../test/clang-doc/test-path-relative.cpp | 8 ++++++++
5 files changed, 27 insertions(+), 16 deletions(-)
create mode 100644 clang-tools-extra/test/clang-doc/test-path-abs.cpp
create mode 100644 clang-tools-extra/test/clang-doc/test-path-relative.cpp
diff --git a/clang-tools-extra/clang-doc/HTMLGenerator.cpp b/clang-tools-extra/clang-doc/HTMLGenerator.cpp
index 1a99c0c063cfb..a30614ed5df1e 100644
--- a/clang-tools-extra/clang-doc/HTMLGenerator.cpp
+++ b/clang-tools-extra/clang-doc/HTMLGenerator.cpp
@@ -984,9 +984,10 @@ static llvm::Error serializeIndex(ClangDocContext &CDCtx) {
if (llvm::sys::path::is_relative(RootPath)) {
llvm::sys::fs::make_absolute(RootPath);
}
- // replace escape character with forward slash it shouldn't matter
- // when viewing from the browser this helps with preventing javascript
- // from escaping unwanted characters leading to bad paths
+ // Replace the escaped characters with a forward slash. It shouldn't matter
+ // when rendering the webpage in a web browser. This helps to prevent the
+ // JavaScript from escaping characters incorrectly, and introducing bad paths
+ // in the URLs.
std::string RootPathEscaped = RootPath.str().str();
std::replace(RootPathEscaped.begin(), RootPathEscaped.end(), '\\', '/');
OS << "var RootPath = \"" << RootPathEscaped << "\";\n";
diff --git a/clang-tools-extra/clang-doc/assets/index.js b/clang-tools-extra/clang-doc/assets/index.js
index eecac22b06e68..00ab9dd6ff04b 100644
--- a/clang-tools-extra/clang-doc/assets/index.js
+++ b/clang-tools-extra/clang-doc/assets/index.js
@@ -1,21 +1,16 @@
function genLink(Ref) {
- var Path = `${window.location.protocol}//${window.location.host}/${Ref.Path}`;
- var isFileProtocol = window.location.protocol.startsWith("file");
// we treat the file paths different depending on if we're
// serving via a http server or viewing from a local
- if (isFileProtocol) {
- Path = `${window.location.protocol}//${RootPath}/${Ref.Path}`;
- }
- if (Ref.RefType !== "namespace") {
- if (Ref.Path === "") {
+ var Path = window.location.protocol.startsWith("file") ?
+ `${window.location.protocol}//${window.location.host}/${Ref.Path}` :
+ `${window.location.protocol}//${RootPath}/${Ref.Path}`;
+ if (Ref.RefType === "namespace") {
+ Path = `${Path}/index.html`
+ } else if (Ref.Path === "") {
Path = `${Path}${Ref.Name}.html`;
- } else {
- Path = `${Path}/${Ref.Name}.html`;
- }
} else {
- Path = `${Path}/index.html`
+ Path = `${Path}/${Ref.Name}.html`;
}
-
ANode = document.createElement("a");
ANode.setAttribute("href", Path);
var TextNode = document.createTextNode(Ref.Name);
diff --git a/clang-tools-extra/test/clang-doc/basic-project.test b/clang-tools-extra/test/clang-doc/basic-project.test
index 455fb28da0fb8..8df06ee42aa59 100644
--- a/clang-tools-extra/test/clang-doc/basic-project.test
+++ b/clang-tools-extra/test/clang-doc/basic-project.test
@@ -7,7 +7,7 @@
// RUN: FileCheck %s -input-file=%t/docs/GlobalNamespace/Rectangle.html -check-prefix=HTML-RECTANGLE
// RUN: FileCheck %s -input-file=%t/docs/GlobalNamespace/Circle.html -check-prefix=HTML-CIRCLE
-// JSON-INDEX: var RootPath = "{{.*}}";
+// JSON-INDEX: var RootPath = "{{.*}}/docs";
// JSON-INDEX: var JsonIndex = `
// JSON-INDEX-NEXT: {
// JSON-INDEX-NEXT: "USR": "{{([0-9A-F]{40})}}",
diff --git a/clang-tools-extra/test/clang-doc/test-path-abs.cpp b/clang-tools-extra/test/clang-doc/test-path-abs.cpp
new file mode 100644
index 0000000000000..d7320cb024b39
--- /dev/null
+++ b/clang-tools-extra/test/clang-doc/test-path-abs.cpp
@@ -0,0 +1,7 @@
+// RUN: rm -rf %t
+// RUN: mkdir %t
+// RUN: echo "CHECK: var RootPath = \"%t\";" > %t/check.txt
+// RUN: cp "%s" "%t/test.cpp"
+// RUN: clang-doc --doxygen --executor=standalone -p %t %t/test.cpp -output=%t/docs
+// RUN: FileCheck %t/check.txt -input-file=%t/docs/index_json.js
+// RUN: rm -rf %t
\ No newline at end of file
diff --git a/clang-tools-extra/test/clang-doc/test-path-relative.cpp b/clang-tools-extra/test/clang-doc/test-path-relative.cpp
new file mode 100644
index 0000000000000..c62c0078a071d
--- /dev/null
+++ b/clang-tools-extra/test/clang-doc/test-path-relative.cpp
@@ -0,0 +1,8 @@
+// RUN: rm -rf %t
+// RUN: mkdir %t
+// RUN: cp "%s" "%t/test.cpp"
+// RUN: clang-doc --doxygen --executor=standalone -p %t %t/test.cpp -output=../docs
+// RUN: FileCheck %s -input-file=%t/docs/index_json.js
+// RUN: rm -rf %t
+
+// CHECK: var RootPath = "{{.*}}../docs";
\ No newline at end of file
>From 9877ea8240c44901db172de36661af20512d7ec8 Mon Sep 17 00:00:00 2001
From: PeterChou1 <peter.chou at mail.utoronto.ca>
Date: Sun, 30 Jun 2024 03:16:20 -0400
Subject: [PATCH 5/6] [clang-doc] fix tests
---
clang-tools-extra/test/clang-doc/test-path-abs.cpp | 2 +-
clang-tools-extra/test/clang-doc/test-path-relative.cpp | 9 ++++-----
2 files changed, 5 insertions(+), 6 deletions(-)
diff --git a/clang-tools-extra/test/clang-doc/test-path-abs.cpp b/clang-tools-extra/test/clang-doc/test-path-abs.cpp
index d7320cb024b39..cf84e241be83f 100644
--- a/clang-tools-extra/test/clang-doc/test-path-abs.cpp
+++ b/clang-tools-extra/test/clang-doc/test-path-abs.cpp
@@ -2,6 +2,6 @@
// RUN: mkdir %t
// RUN: echo "CHECK: var RootPath = \"%t\";" > %t/check.txt
// RUN: cp "%s" "%t/test.cpp"
-// RUN: clang-doc --doxygen --executor=standalone -p %t %t/test.cpp -output=%t/docs
+// RUN: clang-doc --format=html --executor=standalone -p %t %t/test.cpp -output=%t/docs
// RUN: FileCheck %t/check.txt -input-file=%t/docs/index_json.js
// RUN: rm -rf %t
\ No newline at end of file
diff --git a/clang-tools-extra/test/clang-doc/test-path-relative.cpp b/clang-tools-extra/test/clang-doc/test-path-relative.cpp
index c62c0078a071d..c6d8769f238f6 100644
--- a/clang-tools-extra/test/clang-doc/test-path-relative.cpp
+++ b/clang-tools-extra/test/clang-doc/test-path-relative.cpp
@@ -1,8 +1,7 @@
// RUN: rm -rf %t
// RUN: mkdir %t
// RUN: cp "%s" "%t/test.cpp"
-// RUN: clang-doc --doxygen --executor=standalone -p %t %t/test.cpp -output=../docs
-// RUN: FileCheck %s -input-file=%t/docs/index_json.js
-// RUN: rm -rf %t
-
-// CHECK: var RootPath = "{{.*}}../docs";
\ No newline at end of file
+// RUN: echo "CHECK: var RootPath = \"%t/../docs\";" > %t/check.txt
+// RUN: clang-doc --format=html --executor=standalone -p %t %t/test.cpp -output=../docs
+// RUN: FileCheck %t/check.txt -input-file=%t/../docs/index_json.js
+// RUN: rm -rf %t
\ No newline at end of file
>From 1dbed1dafaba5217abd9358d19e1519ab9f745e6 Mon Sep 17 00:00:00 2001
From: PeterChou1 <peter.chou at mail.utoronto.ca>
Date: Sun, 30 Jun 2024 03:22:50 -0400
Subject: [PATCH 6/6] [clang-doc] fix missing - in output
---
clang-tools-extra/test/clang-doc/test-path-abs.cpp | 2 +-
clang-tools-extra/test/clang-doc/test-path-relative.cpp | 2 +-
2 files changed, 2 insertions(+), 2 deletions(-)
diff --git a/clang-tools-extra/test/clang-doc/test-path-abs.cpp b/clang-tools-extra/test/clang-doc/test-path-abs.cpp
index cf84e241be83f..2a8d06bd7be8f 100644
--- a/clang-tools-extra/test/clang-doc/test-path-abs.cpp
+++ b/clang-tools-extra/test/clang-doc/test-path-abs.cpp
@@ -2,6 +2,6 @@
// RUN: mkdir %t
// RUN: echo "CHECK: var RootPath = \"%t\";" > %t/check.txt
// RUN: cp "%s" "%t/test.cpp"
-// RUN: clang-doc --format=html --executor=standalone -p %t %t/test.cpp -output=%t/docs
+// RUN: clang-doc --format=html --executor=standalone -p %t %t/test.cpp --output=%t/docs
// RUN: FileCheck %t/check.txt -input-file=%t/docs/index_json.js
// RUN: rm -rf %t
\ No newline at end of file
diff --git a/clang-tools-extra/test/clang-doc/test-path-relative.cpp b/clang-tools-extra/test/clang-doc/test-path-relative.cpp
index c6d8769f238f6..7f8d71278f133 100644
--- a/clang-tools-extra/test/clang-doc/test-path-relative.cpp
+++ b/clang-tools-extra/test/clang-doc/test-path-relative.cpp
@@ -2,6 +2,6 @@
// RUN: mkdir %t
// RUN: cp "%s" "%t/test.cpp"
// RUN: echo "CHECK: var RootPath = \"%t/../docs\";" > %t/check.txt
-// RUN: clang-doc --format=html --executor=standalone -p %t %t/test.cpp -output=../docs
+// RUN: clang-doc --format=html --executor=standalone -p %t %t/test.cpp --output=../docs
// RUN: FileCheck %t/check.txt -input-file=%t/../docs/index_json.js
// RUN: rm -rf %t
\ No newline at end of file
More information about the cfe-commits
mailing list