Skip to content

[clang-doc] Make --repository change the HTML output #122566

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

Merged
merged 1 commit into from
Feb 6, 2025
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
17 changes: 15 additions & 2 deletions clang-tools-extra/clang-doc/HTMLGenerator.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -494,18 +494,31 @@ genReferencesBlock(const std::vector<Reference> &References,
static std::unique_ptr<TagNode>
writeFileDefinition(const Location &L,
std::optional<StringRef> RepositoryUrl = std::nullopt) {
if (!L.IsFileInRootDir || !RepositoryUrl)
if (!L.IsFileInRootDir && !RepositoryUrl)
return std::make_unique<TagNode>(
HTMLTag::TAG_P, "Defined at line " + std::to_string(L.LineNumber) +
" of file " + L.Filename);
SmallString<128> FileURL(*RepositoryUrl);
llvm::sys::path::append(FileURL, llvm::sys::path::Style::posix, L.Filename);
llvm::sys::path::append(
FileURL, llvm::sys::path::Style::posix,
// If we're on Windows, the file name will be in the wrong format, and
// append won't convert the full path being appended to the correct
// format, so we need to do that here.
llvm::sys::path::convert_to_slash(
L.Filename,
// The style here is the current style of the path, not the one we're
// targeting. If the string is already in the posix style, it will do
// nothing.
llvm::sys::path::Style::windows));
auto Node = std::make_unique<TagNode>(HTMLTag::TAG_P);
Node->Children.emplace_back(std::make_unique<TextNode>("Defined at line "));
auto LocNumberNode =
std::make_unique<TagNode>(HTMLTag::TAG_A, std::to_string(L.LineNumber));
// The links to a specific line in the source code use the github /
// googlesource notation so it won't work for all hosting pages.
// FIXME: we probably should have a configuration setting for line number
// rendering in the HTML. For example, GitHub uses #L22, while googlesource
// uses #22 for line numbers.
LocNumberNode->Attributes.emplace_back(
"href", (FileURL + "#" + std::to_string(L.LineNumber)).str());
Node->Children.emplace_back(std::move(LocNumberNode));
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -8,4 +8,5 @@ double Circle::area() const {

double Circle::perimeter() const {
return 3.141 * radius_;
}
}

295 changes: 174 additions & 121 deletions clang-tools-extra/test/clang-doc/basic-project.test
Original file line number Diff line number Diff line change
Expand Up @@ -54,130 +54,183 @@
// JSON-INDEX-NEXT: };
// JSON-INDEX-NEXT: }

// HTML-SHAPE: <h1>class Shape</h1>
// HTML-SHAPE: <p>Defined at line 8 of file {{.*}}Shape.h</p>
// HTML-SHAPE: <div>brief</div>
// HTML-SHAPE: <p> Abstract base class for shapes.</p>
// HTML-SHAPE: <p> Provides a common interface for different types of shapes.</p>
// HTML-SHAPE: <h2 id="Functions">Functions</h2>
// HTML-SHAPE: <h3 id="{{([0-9A-F]{40})}}">area</h3>
// HTML-SHAPE: <p>public double area()</p>
// HTML-SHAPE: <div>brief</div>
// HTML-SHAPE: <p> Calculates the area of the shape.</p>
// HTML-SHAPE: <h3 id="{{([0-9A-F]{40})}}">perimeter</h3>
// HTML-SHAPE: <p>public double perimeter()</p>
// HTML-SHAPE: <div>brief</div>
// HTML-SHAPE: <p> Calculates the perimeter of the shape.</p>
// HTML-SHAPE: <div>return</div>
// HTML-SHAPE: <p> double The perimeter of the shape.</p>
// HTML-SHAPE: <h3 id="{{([0-9A-F]{40})}}">~Shape</h3>
// HTML-SHAPE: <p>public void ~Shape()</p>
// HTML-SHAPE: <p>Defined at line 13 of file {{.*}}Shape.h</p>
// HTML-SHAPE: <div>brief</div>
// HTML-SHAPE: <p> Virtual destructor.</p>
// HTML-SHAPE: <h1>class Shape</h1>
// HTML-SHAPE-NEXT: <p>
// HTML-SHAPE-NEXT: Defined at line
// HTML-SHAPE-NEXT: <a href="https://repository.com/./include/Shape.h#8">8</a>
// HTML-SHAPE-NEXT: of file
// HTML-SHAPE-NEXT: <a href="https://repository.com/./include/Shape.h">Shape.h</a>
// HTML-SHAPE-NEXT: </p>
// HTML-SHAPE: <div>brief</div>
// HTML-SHAPE: <p> Abstract base class for shapes.</p>
// HTML-SHAPE: <p> Provides a common interface for different types of shapes.</p>
// HTML-SHAPE: <h2 id="Functions">Functions</h2>
// HTML-SHAPE: <h3 id="{{([0-9A-F]{40})}}">area</h3>
// HTML-SHAPE: <p>public double area()</p>
// HTML-SHAPE: <div>brief</div>
// HTML-SHAPE: <p> Calculates the area of the shape.</p>
// HTML-SHAPE: <h3 id="{{([0-9A-F]{40})}}">perimeter</h3>
// HTML-SHAPE: <p>public double perimeter()</p>
// HTML-SHAPE: <div>brief</div>
// HTML-SHAPE: <p> Calculates the perimeter of the shape.</p>
// HTML-SHAPE: <div>return</div>
// HTML-SHAPE: <p> double The perimeter of the shape.</p>
// HTML-SHAPE: <h3 id="{{([0-9A-F]{40})}}">~Shape</h3>
// HTML-SHAPE: <p>public void ~Shape()</p>
// HTML-SHAPE: Defined at line
// HTML-SHAPE-NEXT: <a href="https://repository.com/./include/Shape.h#13">13</a>
// HTML-SHAPE-NEXT: of file
// HTML-SHAPE-NEXT: <a href="https://repository.com/./include/Shape.h">Shape.h</a>
// HTML-SHAPE: <div>brief</div>
// HTML-SHAPE: <p> Virtual destructor.</p>

// HTML-CALC: <h1>class Calculator</h1>
// HTML-CALC: <p>Defined at line 8 of file {{.*}}Calculator.h</p>
// HTML-CALC: <div>brief</div>
// HTML-CALC: <p> A simple calculator class.</p>
// HTML-CALC: <p> Provides basic arithmetic operations.</p>
// HTML-CALC: <h2 id="Functions">Functions</h2>
// HTML-CALC: <h3 id="{{([0-9A-F]{40})}}">add</h3>
// HTML-CALC: <p>public int add(int a, int b)</p>
// HTML-CALC: <p>Defined at line 3 of file {{.*}}Calculator.cpp</p>
// HTML-CALC: <div>brief</div>
// HTML-CALC: <p> Adds two integers.</p>
// HTML-CALC: <div>return</div>
// HTML-CALC: <p> int The sum of a and b.</p>
// HTML-CALC: <h3 id="{{([0-9A-F]{40})}}">subtract</h3>
// HTML-CALC: <p>public int subtract(int a, int b)</p>
// HTML-CALC: <p>Defined at line 7 of file {{.*}}Calculator.cpp</p>
// HTML-CALC: <div>brief</div>
// HTML-CALC: <p> Subtracts the second integer from the first.</p>
// HTML-CALC: <div>return</div>
// HTML-CALC: <p> int The result of a - b.</p>
// HTML-CALC: <h3 id="{{([0-9A-F]{40})}}">multiply</h3>
// HTML-CALC: <p>public int multiply(int a, int b)</p>
// HTML-CALC: <p>Defined at line 11 of file {{.*}}Calculator.cpp</p>
// HTML-CALC: <div>brief</div>
// HTML-CALC: <p> Multiplies two integers.</p>
// HTML-CALC: <div>return</div>
// HTML-CALC: <p> int The product of a and b.</p>
// HTML-CALC: <h3 id="{{([0-9A-F]{40})}}">divide</h3>
// HTML-CALC: <p>public double divide(int a, int b)</p>
// HTML-CALC: <p>Defined at line 15 of file {{.*}}Calculator.cpp</p>
// HTML-CALC: <div>brief</div>
// HTML-CALC: <p> Divides the first integer by the second.</p>
// HTML-CALC: <div>return</div>
// HTML-CALC: <p> double The result of a / b.</p>
// HTML-CALC: <div>throw</div>
// HTML-CALC: <p>if b is zero.</p>
// HTML-CALC: <h1>class Calculator</h1>
// HTML-CALC-NEXT: <p>
// HTML-CALC-NEXT: Defined at line
// HTML-CALC-NEXT: <a href="https://repository.com/./include/Calculator.h#8">8</a>
// HTML-CALC-NEXT: of file
// HTML-CALC-NEXT: <a href="https://repository.com/./include/Calculator.h">Calculator.h</a>
// HTML-CALC-NEXT: </p>
// HTML-CALC: <div>brief</div>
// HTML-CALC: <p> A simple calculator class.</p>
// HTML-CALC: <p> Provides basic arithmetic operations.</p>
// HTML-CALC: <h2 id="Functions">Functions</h2>
// HTML-CALC: <h3 id="{{([0-9A-F]{40})}}">add</h3>
// HTML-CALC: <p>public int add(int a, int b)</p>
// HTML-CALC: Defined at line
// HTML-CALC-NEXT: <a href="https://repository.com/./src/Calculator.cpp#3">3</a>
// HTML-CALC-NEXT: of file
// HTML-CALC-NEXT: <a href="https://repository.com/./src/Calculator.cpp">Calculator.cpp</a>
// HTML-CALC: <div>brief</div>
// HTML-CALC: <p> Adds two integers.</p>
// HTML-CALC: <div>return</div>
// HTML-CALC: <p> int The sum of a and b.</p>
// HTML-CALC: <h3 id="{{([0-9A-F]{40})}}">subtract</h3>
// HTML-CALC: <p>public int subtract(int a, int b)</p>
// HTML-CALC: Defined at line
// HTML-CALC-NEXT: <a href="https://repository.com/./src/Calculator.cpp#7">7</a>
// HTML-CALC-NEXT: of file
// HTML-CALC-NEXT: <a href="https://repository.com/./src/Calculator.cpp">Calculator.cpp</a>
// HTML-CALC: <div>brief</div>
// HTML-CALC: <p> Subtracts the second integer from the first.</p>
// HTML-CALC: <div>return</div>
// HTML-CALC: <p> int The result of a - b.</p>
// HTML-CALC: <h3 id="{{([0-9A-F]{40})}}">multiply</h3>
// HTML-CALC: <p>public int multiply(int a, int b)</p>
// HTML-CALC: Defined at line
// HTML-CALC-NEXT: <a href="https://repository.com/./src/Calculator.cpp#11">11</a>
// HTML-CALC-NEXT: of file
// HTML-CALC-NEXT: <a href="https://repository.com/./src/Calculator.cpp">Calculator.cpp</a>
// HTML-CALC: <div>brief</div>
// HTML-CALC: <p> Multiplies two integers.</p>
// HTML-CALC: <div>return</div>
// HTML-CALC: <p> int The product of a and b.</p>
// HTML-CALC: <h3 id="{{([0-9A-F]{40})}}">divide</h3>
// HTML-CALC: <p>public double divide(int a, int b)</p>
// HTML-CALC: Defined at line
// HTML-CALC-NEXT: <a href="https://repository.com/./src/Calculator.cpp#15">15</a>
// HTML-CALC-NEXT: of file
// HTML-CALC-NEXT: <a href="https://repository.com/./src/Calculator.cpp">Calculator.cpp</a>
// HTML-CALC: <div>brief</div>
// HTML-CALC: <p> Divides the first integer by the second.</p>
// HTML-CALC: <div>return</div>
// HTML-CALC: <p> double The result of a / b.</p>
// HTML-CALC: <div>throw</div>
// HTML-CALC: <p>if b is zero.</p>

// HTML-RECTANGLE: <h1>class Rectangle</h1>
// HTML-RECTANGLE: <p>Defined at line 10 of file {{.*}}Rectangle.h</p>
// HTML-RECTANGLE: <p> Represents a rectangle with a given width and height.</p
// HTML-RECTANGLE: <p>
// HTML-RECTANGLE: Inherits from
// HTML-RECTANGLE: <a href="Shape.html">Shape</a>
// HTML-RECTANGLE: </p>
// HTML-RECTANGLE: <h2 id="Members">Members</h2>
// HTML-RECTANGLE: <p> Width of the rectangle.</p>
// HTML-RECTANGLE: <div>private double width_</div>
// HTML-RECTANGLE: <p> Height of the rectangle.</p>
// HTML-RECTANGLE: <div>private double height_</div>
// HTML-RECTANGLE: <h2 id="Functions">Functions</h2>
// HTML-RECTANGLE: <h3 id="{{([0-9A-F]{40})}}">Rectangle</h3>
// HTML-RECTANGLE: <p>public void Rectangle(double width, double height)</p>
// HTML-RECTANGLE: <p>Defined at line 3 of file {{.*}}Rectangle.cpp</p>
// HTML-RECTANGLE: <div>brief</div>
// HTML-RECTANGLE: <p> Constructs a new Rectangle object.</p>
// HTML-RECTANGLE: <h3 id="{{([0-9A-F]{40})}}">area</h3>
// HTML-RECTANGLE: <p>public double area()</p>
// HTML-RECTANGLE: <p>Defined at line 6 of file {{.*}}Rectangle.cpp</p>
// HTML-RECTANGLE: <div>brief</div>
// HTML-RECTANGLE: <p> Calculates the area of the rectangle.</p>
// HTML-RECTANGLE: <div>return</div>
// HTML-RECTANGLE: <p> double The area of the rectangle.</p>
// HTML-RECTANGLE: <h3 id="{{([0-9A-F]{40})}}">perimeter</h3>
// HTML-RECTANGLE: <p>public double perimeter()</p>
// HTML-RECTANGLE: <p>Defined at line 10 of file {{.*}}Rectangle.cpp</p>
// HTML-RECTANGLE: <div>brief</div>
// HTML-RECTANGLE: <p> Calculates the perimeter of the rectangle.</p>
// HTML-RECTANGLE: <div>return</div>
// HTML-RECTANGLE: <p> double The perimeter of the rectangle.</p>
// HTML-RECTANGLE: <h1>class Rectangle</h1>
// HTML-RECTANGLE-NEXT: <p>
// HTML-RECTANGLE-NEXT: Defined at line
// HTML-RECTANGLE-NEXT: <a href="https://repository.com/./include/Rectangle.h#10">10</a>
// HTML-RECTANGLE-NEXT: of file
// HTML-RECTANGLE-NEXT: <a href="https://repository.com/./include/Rectangle.h">Rectangle.h</a>
// HTML-RECTANGLE-NEXT: </p>
// HTML-RECTANGLE: <p> Represents a rectangle with a given width and height.</p>
// HTML-RECTANGLE: <p>
// HTML-RECTANGLE: Inherits from
// HTML-RECTANGLE: <a href="Shape.html">Shape</a>
// HTML-RECTANGLE: </p>
// HTML-RECTANGLE: <h2 id="Members">Members</h2>
// HTML-RECTANGLE: <p> Width of the rectangle.</p>
// HTML-RECTANGLE: <div>private double width_</div>
// HTML-RECTANGLE: <p> Height of the rectangle.</p>
// HTML-RECTANGLE: <div>private double height_</div>
// HTML-RECTANGLE: <h2 id="Functions">Functions</h2>
// HTML-RECTANGLE: <h3 id="{{([0-9A-F]{40})}}">Rectangle</h3>
// HTML-RECTANGLE: <p>public void Rectangle(double width, double height)</p>
// HTML-RECTANGLE: Defined at line
// HTML-RECTANGLE-NEXT: <a href="https://repository.com/./src/Rectangle.cpp#3">3</a>
// HTML-RECTANGLE-NEXT: of file
// HTML-RECTANGLE-NEXT: <a href="https://repository.com/./src/Rectangle.cpp">Rectangle.cpp</a>
// HTML-RECTANGLE: <div>brief</div>
// HTML-RECTANGLE: <p> Constructs a new Rectangle object.</p>
// HTML-RECTANGLE: <h3 id="{{([0-9A-F]{40})}}">area</h3>
// HTML-RECTANGLE: <p>public double area()</p>
// HTML-RECTANGLE: Defined at line
// HTML-RECTANGLE-NEXT: <a href="https://repository.com/./src/Rectangle.cpp#6">6</a>
// HTML-RECTANGLE-NEXT: of file
// HTML-RECTANGLE-NEXT: <a href="https://repository.com/./src/Rectangle.cpp">Rectangle.cpp</a>
// HTML-RECTANGLE: <div>brief</div>
// HTML-RECTANGLE: <p> Calculates the area of the rectangle.</p>
// HTML-RECTANGLE: <div>return</div>
// HTML-RECTANGLE: <p> double The area of the rectangle.</p>
// HTML-RECTANGLE: <h3 id="{{([0-9A-F]{40})}}">perimeter</h3>
// HTML-RECTANGLE: <p>public double perimeter()</p>
// HTML-RECTANGLE: Defined at line
// HTML-RECTANGLE-NEXT: <a href="https://repository.com/./src/Rectangle.cpp#10">10</a>
// HTML-RECTANGLE-NEXT: of file
// HTML-RECTANGLE-NEXT: <a href="https://repository.com/./src/Rectangle.cpp">Rectangle.cpp</a>
// HTML-RECTANGLE: <div>brief</div>
// HTML-RECTANGLE: <p> Calculates the perimeter of the rectangle.</p>
// HTML-RECTANGLE: <div>return</div>
// HTML-RECTANGLE: <p> double The perimeter of the rectangle.</p>

// HTML-CIRCLE: <h1>class Circle</h1>
// HTML-CIRCLE: <p>Defined at line 10 of file {{.*}}Circle.h</p>
// HTML-CIRCLE: <div>brief</div>
// HTML-CIRCLE: <p> Circle class derived from Shape.</p>
// HTML-CIRCLE: <p> Represents a circle with a given radius.</p>
// HTML-CIRCLE: <p>
// HTML-CIRCLE: Inherits from
// HTML-CIRCLE: <a href="Shape.html">Shape</a>
// HTML-CIRCLE: </p>
// HTML-CIRCLE: <h2 id="Members">Members</h2>
// HTML-CIRCLE: <p> Radius of the circle.</p>
// HTML-CIRCLE: <div>private double radius_</div>
// HTML-CIRCLE: <h2 id="Functions">Functions</h2>
// HTML-CIRCLE: <h3 id="{{([0-9A-F]{40})}}">Circle</h3>
// HTML-CIRCLE: <p>public void Circle(double radius)</p>
// HTML-CIRCLE: <p>Defined at line 3 of file {{.*}}Circle.cpp</p>
// HTML-CIRCLE: <div>brief</div>
// HTML-CIRCLE: <p> Constructs a new Circle object.</p>
// HTML-CIRCLE: <h3 id="{{([0-9A-F]{40})}}">area</h3>
// HTML-CIRCLE: <p>public double area()</p>
// HTML-CIRCLE: <p>Defined at line 5 of file {{.*}}Circle.cpp</p>
// HTML-CIRCLE: <div>brief</div>
// HTML-CIRCLE: <p> Calculates the area of the circle.</p>
// HTML-CIRCLE: <div>return</div>
// HTML-CIRCLE: <p> double The area of the circle.</p>
// HTML-CIRCLE: <h3 id="{{([0-9A-F]{40})}}">perimeter</h3>
// HTML-CIRCLE: <p>public double perimeter()</p>
// HTML-CIRCLE: <p>Defined at line 9 of file {{.*}}Circle.cpp</p>
// HTML-CIRCLE: <div>brief</div>
// HTML-CIRCLE: <p> Calculates the perimeter of the circle.</p>
// HTML-CIRCLE: <div>return</div>
// HTML-CIRCLE: <p> double The perimeter of the circle.</p>
// HTML-CIRCLE: <h1>class Circle</h1>
// HTML-CIRCLE-NEXT: <p>
// HTML-CIRCLE-NEXT: Defined at line
// HTML-CIRCLE-NEXT: <a href="https://repository.com/./include/Circle.h#10">10</a>
// HTML-CIRCLE-NEXT: of file
// HTML-CIRCLE-NEXT: <a href="https://repository.com/./include/Circle.h">Circle.h</a>
// HTML-CIRCLE-NEXT: </p>
// HTML-CIRCLE: <div>brief</div>
// HTML-CIRCLE: <p> Circle class derived from Shape.</p>
// HTML-CIRCLE: <p> Represents a circle with a given radius.</p>
// HTML-CIRCLE: <p>
// HTML-CIRCLE: Inherits from
// HTML-CIRCLE: <a href="Shape.html">Shape</a>
// HTML-CIRCLE: </p>
// HTML-CIRCLE: <h2 id="Members">Members</h2>
// HTML-CIRCLE: <p> Radius of the circle.</p>
// HTML-CIRCLE: <div>private double radius_</div>
// HTML-CIRCLE: <h2 id="Functions">Functions</h2>
// HTML-CIRCLE: <h3 id="{{([0-9A-F]{40})}}">Circle</h3>
// HTML-CIRCLE: <p>public void Circle(double radius)</p>
// HTML-CIRCLE: Defined at line
// HTML-CIRCLE-NEXT: <a href="https://repository.com/./src/Circle.cpp#3">3</a>
// HTML-CIRCLE-NEXT: of file
// HTML-CIRCLE-NEXT: <a href="https://repository.com/./src/Circle.cpp">Circle.cpp</a>
// HTML-CIRCLE: <div>brief</div>
// HTML-CIRCLE: <p> Constructs a new Circle object.</p>
// HTML-CIRCLE: <h3 id="{{([0-9A-F]{40})}}">area</h3>
// HTML-CIRCLE: <p>public double area()</p>
// HTML-CIRCLE: Defined at line
// HTML-CIRCLE-NEXT: <a href="https://repository.com/./src/Circle.cpp#5">5</a>
// HTML-CIRCLE-NEXT: of file
// HTML-CIRCLE-NEXT: <a href="https://repository.com/./src/Circle.cpp">Circle.cpp</a>
// HTML-CIRCLE: <div>brief</div>
// HTML-CIRCLE: <p> Calculates the area of the circle.</p>
// HTML-CIRCLE: <div>return</div>
// HTML-CIRCLE: <p> double The area of the circle.</p>
// HTML-CIRCLE: <h3 id="{{([0-9A-F]{40})}}">perimeter</h3>
// HTML-CIRCLE: <p>public double perimeter()</p>
// HTML-CIRCLE: Defined at line
// HTML-CIRCLE-NEXT: <a href="https://repository.com/./src/Circle.cpp#9">9</a>
// HTML-CIRCLE-NEXT: of file
// HTML-CIRCLE-NEXT: <a href="https://repository.com/./src/Circle.cpp">Circle.cpp</a>
// HTML-CIRCLE: <div>brief</div>
// HTML-CIRCLE: <p> Calculates the perimeter of the circle.</p>
// HTML-CIRCLE: <div>return</div>
// HTML-CIRCLE: <p> double The perimeter of the circle.</p>

// MD-CALC: # class Calculator
// MD-CALC: *Defined at .{{[\/]}}include{{[\/]}}Calculator.h#8*
Expand Down
7 changes: 6 additions & 1 deletion clang-tools-extra/unittests/clang-doc/HTMLGeneratorTest.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -319,7 +319,12 @@ TEST(HTMLGeneratorTest, emitFunctionHTML) {
<a href="path/to/int.html">int</a>
P)
</p>
<p>Defined at line 10 of file dir/test.cpp</p>
<p>
Defined at line
<a href="https://www.repository.com/dir/test.cpp#10">10</a>
of file
<a href="https://www.repository.com/dir/test.cpp">test.cpp</a>
</p>
</div>
<div id="sidebar-right" class="col-xs-6 col-sm-6 col-md-2 sidebar sidebar-offcanvas-right"></div>
</main>
Expand Down