Skip to content

Commit 81b313d

Browse files
coryancoryan
authored
impl(docfx): only 'cloud' documents google::cloud (#11330)
1 parent 95cb416 commit 81b313d

13 files changed

Lines changed: 48 additions & 21 deletions

‎docfx/doxygen2docfx.cc‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -35,7 +35,7 @@ int main(int argc, char* argv[]) try {
3535

3636
for (auto const& i : doc.select_nodes("//compounddef")) {
3737
auto const& node = i.node();
38-
if (!docfx::IncludeInPublicDocuments(node)) continue;
38+
if (!docfx::IncludeInPublicDocuments(config, node)) continue;
3939
auto const kind = std::string_view{node.attribute("kind").as_string()};
4040
auto const id = std::string{node.attribute("id").as_string()};
4141
if (kind == "page") {
@@ -47,7 +47,7 @@ int main(int argc, char* argv[]) try {
4747
std::ofstream(id + ".yml") << docfx::Group2Yaml(node);
4848
continue;
4949
}
50-
std::ofstream(id + ".yml") << docfx::Compound2Yaml(node);
50+
std::ofstream(id + ".yml") << docfx::Compound2Yaml(config, node);
5151
}
5252

5353
return 0;

‎docfx/doxygen2toc.cc‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -28,7 +28,7 @@ std::string Doxygen2Toc(Config const& config, pugi::xml_document const& doc) {
2828
<< YAML::Key << "name" << YAML::Value << config.library //
2929
<< YAML::Key << "items" << YAML::Value //
3030
<< YAML::BeginSeq;
31-
auto pages = PagesToc(doc);
31+
auto pages = PagesToc(config, doc);
3232
if (!pages.empty()) {
3333
auto const& e = pages.front();
3434
out << YAML::BeginMap //
@@ -37,7 +37,7 @@ std::string Doxygen2Toc(Config const& config, pugi::xml_document const& doc) {
3737
<< YAML::EndMap;
3838
pages.erase(pages.begin());
3939
}
40-
for (auto const& e : CompoundToc(doc)) {
40+
for (auto const& e : CompoundToc(config, doc)) {
4141
out << YAML::BeginMap //
4242
<< YAML::Key << "uid" << YAML::Value << e.uid //
4343
<< YAML::Key << "name" << YAML::Value << e.name //

‎docfx/doxygen2toc_test.cc‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -52,7 +52,7 @@ TEST(Doxygen2Toc, Simple) {
5252
</doxygen>)xml";
5353

5454
auto constexpr kExpected = R"""(### YamlMime:TableOfContent
55-
name: common
55+
name: cloud
5656
items:
5757
- name: The Page Title
5858
href: index.md
@@ -68,7 +68,7 @@ name: common
6868

6969
pugi::xml_document doc;
7070
ASSERT_TRUE(doc.load_string(kXml));
71-
auto const config = Config{"test-only-no-input-file", "common", "4.2"};
71+
auto const config = Config{"test-only-no-input-file", "cloud", "4.2"};
7272
auto const actual = Doxygen2Toc(config, doc);
7373

7474
EXPECT_EQ(kExpected, actual);

‎docfx/doxygen2yaml.cc‎

Lines changed: 6 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -63,7 +63,7 @@ bool IgnoreForRecurse(pugi::xml_node const& node) {
6363
void CompoundRecurse(YAML::Emitter& yaml, YamlContext const& ctx,
6464
pugi::xml_node const& node) {
6565
for (auto const& child : node) {
66-
if (!IncludeInPublicDocuments(child)) continue;
66+
if (!IncludeInPublicDocuments(ctx.config, child)) continue;
6767
if (IgnoreForRecurse(child)) continue;
6868
if (AppendIfSectionDef(yaml, ctx, child)) continue;
6969
if (AppendIfNamespace(yaml, ctx, child)) continue;
@@ -108,14 +108,15 @@ std::string Summary(pugi::xml_node const& node) {
108108

109109
} // namespace
110110

111-
std::vector<TocEntry> CompoundToc(pugi::xml_document const& doc) {
111+
std::vector<TocEntry> CompoundToc(Config const& cfg,
112+
pugi::xml_document const& doc) {
112113
std::vector<TocEntry> result;
113114
// Insert only namespaces in the TOC. Other entities (functions, typedefs,
114115
// classes, structs) are always part of a namespace and will appear in the
115116
// references from them.
116117
for (auto const& i : doc.select_nodes("//compounddef[@kind='namespace']")) {
117118
auto const& node = i.node();
118-
if (!IncludeInPublicDocuments(node)) continue;
119+
if (!IncludeInPublicDocuments(cfg, node)) continue;
119120
auto const id = std::string{node.attribute("id").as_string()};
120121
auto const name =
121122
std::string_view{node.child("compoundname").child_value()};
@@ -126,10 +127,11 @@ std::vector<TocEntry> CompoundToc(pugi::xml_document const& doc) {
126127
return result;
127128
}
128129

129-
std::string Compound2Yaml(pugi::xml_node const& node) {
130+
std::string Compound2Yaml(Config const& cfg, pugi::xml_node const& node) {
130131
YAML::Emitter yaml;
131132
StartDocFxYaml(yaml);
132133
YamlContext ctx;
134+
ctx.config = cfg;
133135
(void)AppendIfEnum(yaml, ctx, node);
134136
(void)AppendIfTypedef(yaml, ctx, node);
135137
(void)AppendIfFriend(yaml, ctx, node);

‎docfx/doxygen2yaml.h‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -24,11 +24,12 @@
2424
namespace docfx {
2525

2626
// Get the table of contents for `<compounddef>` nodes representing C++ types.
27-
std::vector<TocEntry> CompoundToc(pugi::xml_document const& doc);
27+
std::vector<TocEntry> CompoundToc(Config const& cfg,
28+
pugi::xml_document const& doc);
2829

2930
// Generate the YAML file contents for `<compounddef>` nodes representing C++
3031
// types.
31-
std::string Compound2Yaml(pugi::xml_node const& node);
32+
std::string Compound2Yaml(Config const& cfg, pugi::xml_node const& node);
3233

3334
// Initialize a YAML Emitter with the preamble elements required by DocFx.
3435
void StartDocFxYaml(YAML::Emitter& yaml);

‎docfx/doxygen2yaml_test.cc‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -463,7 +463,7 @@ TEST(Doxygen2Yaml, CompoundToc) {
463463

464464
pugi::xml_document doc;
465465
ASSERT_TRUE(doc.load_string(kDocXml));
466-
auto const actual = CompoundToc(doc);
466+
auto const actual = CompoundToc(Config{"unused", "cloud", ""}, doc);
467467

468468
EXPECT_THAT(
469469
actual,

‎docfx/doxygen_pages.cc‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -117,13 +117,14 @@ std::string Page2Markdown(pugi::xml_node const& node) {
117117
return std::move(os).str();
118118
}
119119

120-
std::vector<TocEntry> PagesToc(pugi::xml_document const& doc) {
120+
std::vector<TocEntry> PagesToc(Config const& cfg,
121+
pugi::xml_document const& doc) {
121122
auto nodes = doc.select_nodes("//*[@kind='page']");
122123
std::vector<TocEntry> result;
123124
result.reserve(nodes.size());
124125
for (auto const& i : nodes) {
125126
auto const& page = i.node();
126-
if (!IncludeInPublicDocuments(page)) continue;
127+
if (!IncludeInPublicDocuments(cfg, page)) continue;
127128
auto const id = std::string_view{page.attribute("id").as_string()};
128129
std::ostringstream title;
129130
AppendTitle(title, MarkdownContext{}, page);

‎docfx/doxygen_pages.h‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,7 @@
1515
#ifndef GOOGLE_CLOUD_CPP_DOCFX_DOXYGEN_PAGES_H
1616
#define GOOGLE_CLOUD_CPP_DOCFX_DOXYGEN_PAGES_H
1717

18+
#include "docfx/config.h"
1819
#include "docfx/toc_entry.h"
1920
#include <pugixml.hpp>
2021
#include <string>
@@ -30,7 +31,8 @@ namespace docfx {
3031
std::string Page2Markdown(pugi::xml_node const& node);
3132

3233
// Get the table of contents for pages.
33-
std::vector<TocEntry> PagesToc(pugi::xml_document const& doc);
34+
std::vector<TocEntry> PagesToc(Config const& cfg,
35+
pugi::xml_document const& doc);
3436

3537
} // namespace docfx
3638

‎docfx/doxygen_pages_test.cc‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -128,7 +128,7 @@ TEST(DoxygenPages, PagesToc) {
128128

129129
pugi::xml_document doc;
130130
ASSERT_TRUE(doc.load_string(kXml));
131-
auto const actual = PagesToc(doc);
131+
auto const actual = PagesToc(Config{"unused", "cloud", "unused"}, doc);
132132

133133
// The order matters, we want `indexpage` to be the first page.
134134
EXPECT_THAT(actual,

‎docfx/public_docs.cc‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -23,7 +23,7 @@ auto kind(pugi::xml_node const& node) {
2323

2424
} // namespace
2525

26-
bool IncludeInPublicDocuments(pugi::xml_node const& node) {
26+
bool IncludeInPublicDocuments(Config const& cfg, pugi::xml_node const& node) {
2727
// We do not generate documents for files and directories.
2828
if (kind(node) == "file" || kind(node) == "dir") return false;
2929
// Doxygen groups private attributes / functions in <sectiondef> elements of
@@ -40,6 +40,12 @@ bool IncludeInPublicDocuments(pugi::xml_node const& node) {
4040
// to add enough value (each symbol already says if it is deprecated), and
4141
// we need more work to render this correctly in the DocFX format.
4242
if (kind(node) == "page" && id == "deprecated") return false;
43+
// Unless this is the 'cloud' library, we do not generate the `google::` or
44+
// `google::cloud::` namespaces.
45+
if (cfg.library != "cloud" &&
46+
(id == "namespacegoogle" || id == "namespacegoogle_1_1cloud")) {
47+
return false;
48+
}
4349
// We do not generate documentation for private members or sections.
4450
auto const prot = std::string_view{node.attribute("prot").as_string()};
4551
return prot != "private";

0 commit comments

Comments
 (0)