Skip to content

[clang-doc] add tags to Mustache namespace template #142045

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 4 commits into from
Jun 4, 2025
Merged

[clang-doc] add tags to Mustache namespace template #142045

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
7d94cff
[clang-doc] add tags to Mustache namespace template
evelez7 May 29, 2025
82f7cd8
fix windows path problem, fix indentation
evelez7 May 30, 2025
e113007
exclude typedefs from sidebar
evelez7 May 30, 2025
d0a11f7
add whitespace between section tags
evelez7 May 30, 2025
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
79 changes: 69 additions & 10 deletions clang-tools-extra/clang-doc/assets/namespace-template.mustache
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,23 +23,82 @@
</head>
<body>
<nav class="navbar">
Navbar
<div class="navbar__container">
{{#ProjectName}}
<div class="navbar__logo">
{{ProjectName}}
</div>
{{/ProjectName}}
<div class="navbar__menu">
<ul class="navbar__links">
<li class="navbar__item">
<a href="/" class="navbar__link">Namespace</a>
</li>
<li class="navbar__item">
<a href="/" class="navbar__link">Class</a>
</li>
</ul>
</div>
</div>
</nav>
<main>
<div class="container">
<div class="sidebar">
Lorem ipsum dolor sit amet, consectetur adipiscing elit,
sed do eiusmod tempor incididunt ut labore et dolore magna
aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco
laboris nisi ut aliquip ex ea commodo consequat.
Duis aute irure dolor in reprehenderit in voluptate velit esse
cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat
cupidatat non proident, sunt in culpa qui officia deserunt mollit
anim id est laborum
<h2>{{RecordType}} {{Name}}</h2>
<ul>
{{#Enums}}
<li class="sidebar-section">
<a class="sidebar-item" href="#Enums">Enums</a>
</li>
<ul>
{{#Obj}}
<li class="sidebar-item-container">
<a class="sidebar-item" href="#{{ID}}">{{EnumName}}</a>
</li>
{{/Obj}}
</ul>
{{/Enums}}
{{#Typedef}}
<li class="sidebar-section">Typedef</li>
{{/Typedef}}
{{#Record}}
<li class="sidebar-section">
<a class="sidebar-item" href="#Classes">Inner Classes</a>
</li>
<ul>
{{#Links}}
<li class="sidebar-item-container">
<a class="sidebar-item" href="#{{ID}}">{{Name}}</a>
</li>
{{/Links}}
</ul>
{{/Record}}
</ul>
</div>
<div class="resizer" id="resizer"></div>
<div class="content">
Content
{{#Enums}}
<section id="Enums" class="section-container">
<h2>Enumerations</h2>
<div>
{{#Obj}}
{{>EnumPartial}}
{{/Obj}}
</div>
</section>
{{/Enums}}
{{#Record}}
<section id="Classes" class="section-container">
<h2>Inner Classes</h2>
<ul class="class-container">
{{#Links}}
<li id="{{ID}}" style="max-height: 40px;">
<a href="{{Link}}"><pre><code class="language-cpp code-clang-doc" >class {{Name}}</code></pre></a>
</li>
{{/Links}}
</ul>
</section>
{{/Record}}
</div>
</div>
</main>
Expand Down
74 changes: 74 additions & 0 deletions clang-tools-extra/test/clang-doc/mustache-index.cpp
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,74 @@
// RUN: rm -rf %t && mkdir -p %t
// RUN: clang-doc --format=mustache --output=%t --executor=standalone %s
// RUN: FileCheck %s < %t/GlobalNamespace/index.html

enum Color {
RED,
BLUE,
GREEN
};

class Foo;

// CHECK: <li class="sidebar-section">
// CHECK-NEXT: <a class="sidebar-item" href="#Enums">Enums</a>
// CHECK-NEXT: </li>
// CHECK-NEXT: <ul>
// CHECK-NEXT: <li class="sidebar-item-container">
// CHECK-NEXT: <a class="sidebar-item" href="#{{[0-9A-F]*}}">enum Color</a>
// CHECK-NEXT: </li>
// CHECK-NEXT: </ul>
// CHECK: <li class="sidebar-section">
// CHECK-NEXT: <a class="sidebar-item" href="#Classes">Inner Classes</a>
// CHECK-NEXT: </li>
// CHECK-NEXT: <ul>
// CHECK-NEXT: <li class="sidebar-item-container">
// CHECK-NEXT: <a class="sidebar-item" href="#{{[0-9A-F]*}}">Foo</a>
// CHECK-NEXT: </li>
// CHECK-NEXT: </ul>

// CHECK: <section id="Enums" class="section-container">
// CHECK-NEXT: <h2>Enumerations</h2>
// CHECK-NEXT: <div>
// CHECK-NEXT: <div id="{{[0-9A-F]*}}" class="delimiter-container">
// CHECK-NEXT: <div>
// CHECK-NEXT: <pre>
// CHECK-NEXT: <code class="language-cpp code-clang-doc">
// CHECK-NEXT: enum Color
// CHECK-NEXT: </code>
// CHECK-NEXT: </pre>
// CHECK-NEXT: </div>
// CHECK-NEXT: <table class="table-wrapper">
// CHECK-NEXT: <tbody>
// CHECK-NEXT: <tr>
// CHECK-NEXT: <th>Name</th>
// CHECK-NEXT: <th>Value</th>
// CHECK: </tr>
Copy link
Contributor

Choose a reason for hiding this comment

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

Does the tag not line up becacuse you deleted -NEXT or do we emit it with really strange indentation?

Copy link
Member Author

Choose a reason for hiding this comment

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

Yeah I forgot to adjust the spacing after deleting -NEXT.

We do emit a lot of strange indentation though. I turned these into CHECKS because the RUN commands are emitted as comments for every enum value. The div and table tags for those comments are a bit jumbled. The enum Color above on line 37 is also my own indentation, it's way further back in source.

// CHECK-NEXT: <tr>
// CHECK-NEXT: <td>RED</td>
// CHECK-NEXT: <td>0</td>
// CHECK: </tr>
// CHECK-NEXT: <tr>
// CHECK-NEXT: <td>BLUE</td>
// CHECK-NEXT: <td>1</td>
// CHECK: </tr>
// CHECK-NEXT: <tr>
// CHECK-NEXT: <td>GREEN</td>
// CHECK-NEXT: <td>2</td>
// CHECK: </tr>
// CHECK-NEXT: </tbody>
// CHECK-NEXT: </table>
// CHECK-NEXT: <div>
// CHECK-NEXT: Defined at line 5 of file {{.*}}/mustache-index.cpp
// CHECK-NEXT: </div>
// CHECK-NEXT: </div>
// CHECK-NEXT: </div>
// CHECK-NEXT: </section>
// CHECK: <section id="Classes" class="section-container">
// CHECK-NEXT: <h2>Inner Classes</h2>
// CHECK-NEXT: <ul class="class-container">
// CHECK-NEXT: <li id="{{[0-9A-F]*}}" style="max-height: 40px;">
// CHECK-NEXT: <a href="Foo.html"><pre><code class="language-cpp code-clang-doc" >class Foo</code></pre></a>
// CHECK-NEXT: </li>
// CHECK-NEXT: </ul>
// CHECK-NEXT: </section>
13 changes: 13 additions & 0 deletions clang-tools-extra/test/clang-doc/mustache-separate-namespace.cpp
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
// RUN: rm -rf %t && mkdir -p %t
// RUN: clang-doc --format=mustache --output=%t --executor=standalone %s
// RUN: FileCheck %s < %t/MyNamespace/index.html

namespace MyNamespace {
class Foo;
}

// CHECK: <ul class="class-container">
// CHECK-NEXT: <li id="{{[0-9A-F]*}}" style="max-height: 40px;">
// CHECK-NEXT: <a href="Foo.html"><pre><code class="language-cpp code-clang-doc" >class Foo</code></pre></a>
// CHECK-NEXT: </li>
// CHECK-NEXT: </ul>
67 changes: 0 additions & 67 deletions clang-tools-extra/unittests/clang-doc/HTMLMustacheGeneratorTest.cpp
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -87,29 +87,6 @@ TEST(HTMLMustacheGeneratorTest, createResources) {
}
}

TEST(HTMLMustacheGeneratorTest, generateDocs) {
auto G = getHTMLMustacheGenerator();
assert(G && "Could not find HTMLMustacheGenerator");
ClangDocContext CDCtx = getClangDocContext();

unittest::TempDir RootTestDirectory("generateDocsTest", /*Unique=*/true);
CDCtx.OutDirectory = RootTestDirectory.path();

#if ENABLE_LOCAL_TEST
// FIXME: We can't read files during unit tests. Migrate to lit once
// tool support lands.
getMustacheHtmlFiles(CLANG_DOC_TEST_ASSET_DIR, CDCtx);

EXPECT_THAT_ERROR(G->generateDocs(RootTestDirectory.path(), {}, CDCtx),
Succeeded())
<< "Failed to generate docs.";
#else
EXPECT_THAT_ERROR(G->generateDocs(RootTestDirectory.path(), {}, CDCtx),
Failed())
<< "Failed to generate docs.";
#endif
}

TEST(HTMLGeneratorTest, emitFunctionHTML) {
#if ENABLE_LOCAL_TEST
auto G = getHTMLMustacheGenerator();
Expand Down Expand Up @@ -160,50 +137,6 @@ TEST(HTMLGeneratorTest, emitFunctionHTML) {
#endif
}

TEST(HTMLMustacheGeneratorTest, emitEnumHTML) {
#if ENABLE_LOCAL_TEST
auto G = getHTMLMustacheGenerator();
assert(G && "Could not find HTMLMustacheGenerator");
ClangDocContext CDCtx = getClangDocContext();
std::string Buffer;
llvm::raw_string_ostream Actual(Buffer);

unittest::TempDir RootTestDirectory("emitEnumHTML",
/*Unique=*/true);
CDCtx.OutDirectory = RootTestDirectory.path();

getMustacheHtmlFiles(CLANG_DOC_TEST_ASSET_DIR, CDCtx);

// FIXME: This is a terrible hack, since we can't initialize the templates
// directly. We'll need to update the interfaces so that we can call
// SetupTemplateFiles() from outsize of HTMLMustacheGenerator.cpp
EXPECT_THAT_ERROR(G->generateDocs(RootTestDirectory.path(), {}, CDCtx),
Succeeded())
<< "Failed to generate docs.";

CDCtx.RepositoryUrl = "http://www.repository.com";

EnumInfo I;
I.Name = "e";
I.Namespace.emplace_back(EmptySID, "A", InfoType::IT_namespace);

I.DefLoc = Location(10, 10, "test.cpp", true);
I.Loc.emplace_back(12, 12, "test.cpp");

I.Members.emplace_back("X");
I.Scoped = true;

auto Err = G->generateDocForInfo(&I, Actual, CDCtx);
assert(!Err);

std::string Expected = R"raw(IT_enum
)raw";

// FIXME: Enums are not handled yet.
EXPECT_EQ(Expected, Actual.str());
#endif
}

TEST(HTMLMustacheGeneratorTest, emitCommentHTML) {
#if ENABLE_LOCAL_TEST
auto G = getHTMLMustacheGenerator();
Expand Down
Loading