Skip to content

Commit 1dbc4bf

Browse files
alandefreitasalandefreitas
committed
show-namespaces option
#feat
1 parent b4fec4f commit 1dbc4bf

22 files changed

+231
-200
lines changed

‎docs/mrdocs.schema.json

+10
Original file line numberDiff line numberDiff line change
@@ -297,6 +297,16 @@
297297
"title": "Detect and reduce SFINAE expressions",
298298
"type": "boolean"
299299
},
300+
"show-namespaces": {
301+
"default": true,
302+
"description": "When set to true, MrDocs creates a page for each namespace in the documentation.",
303+
"enum": [
304+
true,
305+
false
306+
],
307+
"title": "Show namespace pages in the documentation",
308+
"type": "boolean"
309+
},
300310
"sort-members": {
301311
"default": true,
302312
"description": "When set to `true`, sort the members of a record or namespace by name and parameters. When set to `false`, the members are included in the declaration order they are extracted.",

‎src/lib/Gen/hbs/HandlebarsCorpus.cpp

+2-1
Original file line numberDiff line numberDiff line change
@@ -120,7 +120,7 @@ HandlebarsCorpus::
120120
construct(Info const& I) const
121121
{
122122
dom::Object obj = this->DomCorpus::construct(I);
123-
if (shouldGenerate(I))
123+
if (shouldGenerate(I, getCorpus().config))
124124
{
125125
obj.set("url", getURL(I));
126126
obj.set("anchor", names_.getQualified(I.id, '-'));
@@ -132,6 +132,7 @@ construct(Info const& I) const
132132
// for the primary template if it's part of the corpus.
133133
if (Info const* primaryInfo = findAlternativeURLInfo(getCorpus(), I))
134134
{
135+
MRDOCS_ASSERT(shouldGenerate(*primaryInfo, getCorpus().config));
135136
obj.set("url", getURL(*primaryInfo));
136137
obj.set("anchor", names_.getQualified(primaryInfo->id, '-'));
137138
}

‎src/lib/Gen/hbs/MultiPageVisitor.cpp

+35-35
Original file line numberDiff line numberDiff line change
@@ -21,47 +21,47 @@ void
2121
MultiPageVisitor::
2222
operator()(T const& I)
2323
{
24-
MRDOCS_CHECK_OR(shouldGenerate(I));
25-
26-
// Increment the count
27-
count_.fetch_add(1, std::memory_order_relaxed);
28-
2924
ex_.async([this, &I](Builder& builder)
3025
{
31-
// ===================================
32-
// Open the output file
33-
// ===================================
34-
std::string const path = files::appendPath(outputPath_, builder.domCorpus.getURL(I));
35-
std::string const dir = files::getParentDir(path);
36-
if (auto exp = files::createDirectory(dir); !exp)
26+
if (shouldGenerate(I, corpus_.config))
3727
{
38-
exp.error().Throw();
39-
}
40-
std::ofstream os;
41-
try
42-
{
43-
os.open(path,
44-
std::ios_base::binary |
45-
std::ios_base::out |
46-
std::ios_base::trunc // | std::ios_base::noreplace
47-
);
48-
if (!os.is_open()) {
49-
formatError(R"(std::ofstream("{}") failed)", path)
28+
// ===================================
29+
// Open the output file
30+
// ===================================
31+
std::string const path = files::appendPath(outputPath_, builder.domCorpus.getURL(I));
32+
std::string const dir = files::getParentDir(path);
33+
if (auto exp = files::createDirectory(dir); !exp)
34+
{
35+
exp.error().Throw();
36+
}
37+
std::ofstream os;
38+
try
39+
{
40+
os.open(path,
41+
std::ios_base::binary |
42+
std::ios_base::out |
43+
std::ios_base::trunc // | std::ios_base::noreplace
44+
);
45+
if (!os.is_open()) {
46+
formatError(R"(std::ofstream("{}") failed)", path)
47+
.Throw();
48+
}
49+
}
50+
catch (std::exception const& ex)
51+
{
52+
formatError(R"(std::ofstream("{}") threw "{}")", path, ex.what())
5053
.Throw();
5154
}
52-
}
53-
catch (std::exception const& ex)
54-
{
55-
formatError(R"(std::ofstream("{}") threw "{}")", path, ex.what())
56-
.Throw();
57-
}
5855

59-
// ===================================
60-
// Generate the output
61-
// ===================================
62-
if (auto exp = builder(os, I); !exp)
63-
{
64-
exp.error().Throw();
56+
// ===================================
57+
// Generate the output
58+
// ===================================
59+
if (auto exp = builder(os, I); !exp)
60+
{
61+
exp.error().Throw();
62+
}
63+
64+
count_.fetch_add(1, std::memory_order_relaxed);
6565
}
6666

6767
// ===================================

‎src/lib/Gen/hbs/SinglePageVisitor.cpp

+16-13
Original file line numberDiff line numberDiff line change
@@ -21,21 +21,24 @@ void
2121
SinglePageVisitor::
2222
operator()(T const& I)
2323
{
24-
MRDOCS_CHECK_OR(shouldGenerate(I));
25-
ex_.async([this, &I, symbolIdx = numSymbols_++](Builder& builder)
24+
if (shouldGenerate(I, corpus_.config))
2625
{
27-
// Output to an independent string first (async), then write to
28-
// the shared stream (sync)
29-
std::stringstream ss;
30-
if(auto r = builder(ss, I))
26+
ex_.async([this, &I, symbolIdx = numSymbols_++](Builder& builder)
3127
{
32-
writePage(ss.str(), symbolIdx);
33-
}
34-
else
35-
{
36-
r.error().Throw();
37-
}
38-
});
28+
29+
// Output to an independent string first (async), then write to
30+
// the shared stream (sync)
31+
std::stringstream ss;
32+
if(auto r = builder(ss, I))
33+
{
34+
writePage(ss.str(), symbolIdx);
35+
}
36+
else
37+
{
38+
r.error().Throw();
39+
}
40+
});
41+
}
3942
Corpus::TraverseOptions opts = {.skipInherited = std::same_as<T, RecordInfo>};
4043
corpus_.traverse(opts, I, *this);
4144
}

‎src/lib/Gen/hbs/VisitorHelpers.cpp

+9-5
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,7 @@
1717
namespace clang::mrdocs::hbs {
1818

1919
bool
20-
shouldGenerate(Info const& I)
20+
shouldGenerate(Info const& I, Config const& config)
2121
{
2222
if (I.isSpecialization())
2323
{
@@ -38,6 +38,10 @@ shouldGenerate(Info const& I)
3838
// See the requirements in ConfigOptions.json.
3939
return false;
4040
}
41+
if (!config->showNamespaces && I.isNamespace())
42+
{
43+
return false;
44+
}
4145
return true;
4246
}
4347

@@ -91,7 +95,7 @@ findPrimarySiblingWithUrl(Corpus const& c, Info const& I, Info const& parent)
9195
for (Info const* sibling: sameNameSiblings)
9296
{
9397
if (!sibling ||
94-
!shouldGenerate(*sibling))
98+
!shouldGenerate(*sibling, c.config))
9599
{
96100
continue;
97101
}
@@ -135,7 +139,7 @@ findDirectPrimarySiblingWithUrl(Corpus const& c, Info const& I)
135139
// in the parent scope for which we want to generate the URL
136140
Info const* parent = c.find(I.Parent);
137141
MRDOCS_CHECK_OR(parent, nullptr);
138-
if (!shouldGenerate(*parent))
142+
if (!shouldGenerate(*parent, c.config))
139143
{
140144
parent = findPrimarySiblingWithUrl(c, *parent);
141145
MRDOCS_CHECK_OR(parent, nullptr);
@@ -198,7 +202,7 @@ findResolvedPrimarySiblingWithUrl(Corpus const& c, Info const& I)
198202
// a dependency for which there's no URL, we attempt to
199203
// find the primary sibling for the parent so we take
200204
// the URL from it.
201-
if (!shouldGenerate(*parent))
205+
if (!shouldGenerate(*parent, c.config))
202206
{
203207
parent = findPrimarySiblingWithUrl(c, *parent);
204208
MRDOCS_CHECK_OR(parent, nullptr);
@@ -236,7 +240,7 @@ findParentWithUrl(Corpus const& c, Info const& I)
236240
Info const* parent = c.find(I.Parent);
237241
MRDOCS_CHECK_OR(parent, nullptr);
238242
MRDOCS_CHECK_OR(!parent->isNamespace(), nullptr);
239-
if (shouldGenerate(*parent))
243+
if (shouldGenerate(*parent, c.config))
240244
{
241245
return parent;
242246
}

‎src/lib/Gen/hbs/VisitorHelpers.hpp

+2-1
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,7 @@
1212
#define MRDOCS_LIB_GEN_HBS_VISITORHELPERS_HPP
1313

1414
#include <mrdocs/Metadata/Info.hpp>
15+
#include <mrdocs/Config.hpp>
1516

1617
namespace clang::mrdocs::hbs {
1718

@@ -22,7 +23,7 @@ namespace clang::mrdocs::hbs {
2223
*/
2324
MRDOCS_DECL
2425
bool
25-
shouldGenerate(Info const& I);
26+
shouldGenerate(Info const& I, Config const& config);
2627

2728
/** Find an Info type whose URL we can use for the specified Info
2829

‎src/lib/Lib/ConfigOptions.json

+7
Original file line numberDiff line numberDiff line change
@@ -318,6 +318,13 @@
318318
"details": "Output an embeddable document, which excludes the header, the footer, and everything outside the body of the document. This option is useful for producing documents that can be inserted into an external template.",
319319
"type": "bool",
320320
"default": false
321+
},
322+
{
323+
"name": "show-namespaces",
324+
"brief": "Show namespace pages in the documentation",
325+
"details": "When set to true, MrDocs creates a page for each namespace in the documentation.",
326+
"type": "bool",
327+
"default": true
321328
}
322329
]
323330
},

‎src/lib/Lib/TagfileWriter.cpp

+7-9
Original file line numberDiff line numberDiff line change
@@ -19,8 +19,7 @@
1919

2020
#include <mrdocs/Support/Path.hpp>
2121

22-
namespace clang {
23-
namespace mrdocs {
22+
namespace clang::mrdocs {
2423

2524
//------------------------------------------------
2625
//
@@ -82,7 +81,7 @@ operator()(T const& I)
8281
{
8382
if constexpr (std::derived_from<T, Info>)
8483
{
85-
if (!hbs::shouldGenerate(I))
84+
if (!hbs::shouldGenerate(I, corpus_.getCorpus().config))
8685
{
8786
return;
8887
}
@@ -113,14 +112,14 @@ writeNamespace(
113112
{
114113
// Check if this namespace contains only other namespaces
115114
bool onlyNamespaces = true;
116-
corpus_->traverse(I, [&](Info const& I)
115+
corpus_->traverse(I, [&](Info const& U)
117116
{
118-
if (!hbs::shouldGenerate(I))
117+
if (!hbs::shouldGenerate(U, corpus_.getCorpus().config))
119118
{
120119
return;
121120
}
122121

123-
if (I.Kind != InfoKind::Namespace)
122+
if (U.Kind != InfoKind::Namespace)
124123
{
125124
onlyNamespaces = false;
126125
}
@@ -139,7 +138,7 @@ writeNamespace(
139138
// Write the class-like members of this namespace
140139
corpus_->traverse(I, [this]<typename U>(U const& J)
141140
{
142-
if (!hbs::shouldGenerate(J))
141+
if (!hbs::shouldGenerate(J, corpus_.getCorpus().config))
143142
{
144143
return;
145144
}
@@ -281,5 +280,4 @@ generateFileAndAnchor(T const& I)
281280
return {url.substr(0, pos), url.substr(pos + 1)};
282281
}
283282

284-
} // mrdocs
285-
} // clang
283+
} // clang::mrdocs

‎test-files/golden-tests/config/show-namespaces/show-namespaces.adoc

+51
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
= Reference
2+
:mrdocs:
3+
4+
[#A-B-c]
5+
== A::B::c
6+
7+
8+
=== Synopsis
9+
10+
11+
Declared in `&lt;show&hyphen;namespaces&period;cpp&gt;`
12+
13+
[source,cpp,subs="verbatim,replacements,macros,-callouts"]
14+
----
15+
void
16+
c();
17+
----
18+
19+
[#A-b]
20+
== A::b
21+
22+
23+
=== Synopsis
24+
25+
26+
Declared in `&lt;show&hyphen;namespaces&period;cpp&gt;`
27+
28+
[source,cpp,subs="verbatim,replacements,macros,-callouts"]
29+
----
30+
void
31+
b();
32+
----
33+
34+
[#a]
35+
== a
36+
37+
38+
=== Synopsis
39+
40+
41+
Declared in `&lt;show&hyphen;namespaces&period;cpp&gt;`
42+
43+
[source,cpp,subs="verbatim,replacements,macros,-callouts"]
44+
----
45+
void
46+
a();
47+
----
48+
49+
50+
51+
[.small]#Created with https://www.mrdocs.com[MrDocs]#

‎test-files/golden-tests/config/show-namespaces/show-namespaces.cpp

+9
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
void a();
2+
3+
namespace A {
4+
void b();
5+
namespace B {
6+
void c();
7+
}
8+
}
9+

0 commit comments

Comments
 (0)