Skip to content

Commit ed3cde8

Browse files
coryancoryan
authored
impl(docfx): initial table of contents file (#10972)
Generate an initial table of contents files, with just the Doxygen `@page` documents for now. This introduces the first YAML output.
1 parent 2984b09 commit ed3cde8

File tree

7 files changed

+140
-1
lines changed

7 files changed

+140
-1
lines changed

‎docfx/CMakeLists.txt‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -33,6 +33,8 @@ add_library(
3333
config.h
3434
doxygen2markdown.cc
3535
doxygen2markdown.h
36+
doxygen2toc.cc
37+
doxygen2toc.h
3638
doxygen_pages.cc
3739
doxygen_pages.h
3840
parse_arguments.cc
@@ -61,7 +63,8 @@ endif ()
6163

6264
set(unit_tests
6365
# cmake-format: sort
64-
doxygen2markdown_test.cc doxygen_pages_test.cc parse_arguments_test.cc)
66+
doxygen2markdown_test.cc doxygen2toc_test.cc doxygen_pages_test.cc
67+
parse_arguments_test.cc)
6568

6669
# Export the list of unit tests to a .bzl file so we do not need to maintain the
6770
# list in two places.

‎docfx/docfx.bzl‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,13 +19,15 @@
1919
docfx_hdrs = [
2020
"config.h",
2121
"doxygen2markdown.h",
22+
"doxygen2toc.h",
2223
"doxygen_pages.h",
2324
"parse_arguments.h",
2425
"toc_entry.h",
2526
]
2627

2728
docfx_srcs = [
2829
"doxygen2markdown.cc",
30+
"doxygen2toc.cc",
2931
"doxygen_pages.cc",
3032
"parse_arguments.cc",
3133
"toc_entry.cc",

‎docfx/doxygen2toc.cc‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
// Copyright 2023 Google LLC
2+
//
3+
// Licensed under the Apache License, Version 2.0 (the "License");
4+
// you may not use this file except in compliance with the License.
5+
// You may obtain a copy of the License at
6+
//
7+
// https://www.apache.org/licenses/LICENSE-2.0
8+
//
9+
// Unless required by applicable law or agreed to in writing, software
10+
// distributed under the License is distributed on an "AS IS" BASIS,
11+
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12+
// See the License for the specific language governing permissions and
13+
// limitations under the License.
14+
15+
#include "docfx/doxygen2toc.h"
16+
#include "docfx/doxygen_pages.h"
17+
#include <yaml-cpp/yaml.h>
18+
#include <sstream>
19+
20+
namespace docfx {
21+
22+
std::string Doxygen2Toc(Config const& config, pugi::xml_document const& doc) {
23+
auto const pages = PagesToc(doc);
24+
auto const uid = std::string{"cloud.google.com/cpp/"} + config.library;
25+
YAML::Emitter out;
26+
out << YAML::BeginSeq << YAML::BeginMap //
27+
<< YAML::Key << "uid" << YAML::Value << uid //
28+
<< YAML::Key << "name" << YAML::Value << uid //
29+
<< YAML::Key << "items" << YAML::Value //
30+
<< YAML::BeginSeq;
31+
for (auto const& [filename, name] : pages) {
32+
out << YAML::BeginMap //
33+
<< YAML::Key << "name" << YAML::Value << name //
34+
<< YAML::Key << "href" << YAML::Value << filename //
35+
<< YAML::EndMap;
36+
}
37+
out << YAML::EndSeq << YAML::EndMap << YAML::EndSeq;
38+
39+
std::ostringstream os;
40+
os << "### YamlMime:TableOfContent\n" << out.c_str() << "\n";
41+
return std::move(os).str();
42+
}
43+
44+
} // namespace docfx

‎docfx/doxygen2toc.h‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
// Copyright 2023 Google LLC
2+
//
3+
// Licensed under the Apache License, Version 2.0 (the "License");
4+
// you may not use this file except in compliance with the License.
5+
// You may obtain a copy of the License at
6+
//
7+
// https://www.apache.org/licenses/LICENSE-2.0
8+
//
9+
// Unless required by applicable law or agreed to in writing, software
10+
// distributed under the License is distributed on an "AS IS" BASIS,
11+
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12+
// See the License for the specific language governing permissions and
13+
// limitations under the License.
14+
15+
#ifndef GOOGLE_CLOUD_CPP_DOCFX_DOXYGEN2TOC_H
16+
#define GOOGLE_CLOUD_CPP_DOCFX_DOXYGEN2TOC_H
17+
18+
#include "docfx/config.h"
19+
#include <pugixml.hpp>
20+
#include <string>
21+
22+
namespace docfx {
23+
24+
/// Generates the YAML table of contents.
25+
std::string Doxygen2Toc(Config const& config, pugi::xml_document const& doc);
26+
27+
} // namespace docfx
28+
29+
#endif // GOOGLE_CLOUD_CPP_DOCFX_DOXYGEN2TOC_H

‎docfx/doxygen2toc_test.cc‎

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
// Copyright 2023 Google LLC
2+
//
3+
// Licensed under the Apache License, Version 2.0 (the "License");
4+
// you may not use this file except in compliance with the License.
5+
// You may obtain a copy of the License at
6+
//
7+
// https://www.apache.org/licenses/LICENSE-2.0
8+
//
9+
// Unless required by applicable law or agreed to in writing, software
10+
// distributed under the License is distributed on an "AS IS" BASIS,
11+
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12+
// See the License for the specific language governing permissions and
13+
// limitations under the License.
14+
15+
#include "docfx/doxygen2toc.h"
16+
#include <gmock/gmock.h>
17+
18+
namespace docfx {
19+
namespace {
20+
21+
TEST(Doxygen2Toc, Simple) {
22+
auto constexpr kXml =
23+
R"xml(<?xml version="1.0" standalone="yes"?><doxygen version="1.9.1" xml:lang="en-US">
24+
<compounddef xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" id="common-error-handling" kind="page">
25+
<compoundname>common-error-handling</compoundname>
26+
<title>Error Handling</title>
27+
<briefdescription><para>An overview of error handling in the Google Cloud C++ client libraries.</para>
28+
</briefdescription>
29+
<detaileddescription><para>More details about error handling.</para></detaileddescription>
30+
</compounddef>
31+
<compounddef xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" id="indexpage" kind="page">
32+
<compoundname>index</compoundname>
33+
<title>The Page Title: unused in this test</title>
34+
<briefdescription><para>Some brief description.</para>
35+
</briefdescription>
36+
<detaileddescription><para>More details about the index.</para></detaileddescription>
37+
</compounddef>
38+
</doxygen>)xml";
39+
40+
auto constexpr kExpected = R"""(### YamlMime:TableOfContent
41+
- uid: cloud.google.com/cpp/common
42+
name: cloud.google.com/cpp/common
43+
items:
44+
- name: common-error-handling
45+
href: common-error-handling.md
46+
- name: README
47+
href: indexpage.md
48+
)""";
49+
50+
pugi::xml_document doc;
51+
ASSERT_TRUE(doc.load_string(kXml));
52+
auto const config = Config{"test-only-no-input-file", "common"};
53+
auto const actual = Doxygen2Toc(config, doc);
54+
55+
EXPECT_EQ(kExpected, actual);
56+
}
57+
58+
} // namespace
59+
} // namespace docfx

‎docfx/doxygen_pages.h‎

Lines changed: 1 addition & 0 deletions
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>

‎docfx/unit_tests.bzl‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,7 @@
1818

1919
unit_tests = [
2020
"doxygen2markdown_test.cc",
21+
"doxygen2toc_test.cc",
2122
"doxygen_pages_test.cc",
2223
"parse_arguments_test.cc",
2324
]

0 commit comments

Comments
 (0)