feat(docfx): support Doxygen 1.9.7 output (#13852)

coryan · web-flow · commit 28fc4ad0e1b4 · 2024-03-26T17:20:35.000Z
diff --git a/docfx/README.md b/docfx/README.md
@@ -38,11 +38,12 @@ git clone https://github.com/microsoft/vcpkg.git $HOME/vcpkg
 
 ```
 cd google-cloud-cpp
-cmake -S . -B .build -DCMAKE_TOOLCHAIN_FILE=$HOME/vcpkg/scripts/buildsystems/vcpkg.cmake
-PUBLISH=$PWD/build-out/fedora-latest-cmake-publish-docs/cmake-out/google/cloud
-cmake --build .build/ --target docfx/all \
+cmake -GNinja -S . -B build-out/.docfx -DGOOGLE_CLOUD_CPP_INTERNAL_DOCFX=ON \
+    --toolchain $HOME/vcpkg/scripts/buildsystems/vcpkg.cmake
+PUBLISH=$PWD/build-out/fedora-latest-publish-docs/publish-docs/__default__/cmake-out/google/cloud
+cmake --build build-out/.docfx --target docfx/all \
   && rm -f $HOME/doc-pipeline/testdata/cpp/* \
-  && env -C $HOME/doc-pipeline/testdata/cpp $PWD/.build/docfx/doxygen2docfx $PUBLISH/xml/cloud.doxygen.xml cloud 2.9.0
+  && env -C $HOME/doc-pipeline/testdata/cpp $PWD/build-out/.docfx/docfx/doxygen2docfx $PUBLISH/xml/cloud.doxygen.xml cloud 2.9.0
 ```
 
 ### Run the DocFX pipeline over the generated files
@@ -85,3 +86,14 @@ env -C $HOME/doc-pipeline \
     TRAMPOLINE_IMAGE=gcr.io/cloud-devrel-kokoro-resources/docfx \
     TRAMPOLINE_DOCKERFILE=docfx/Dockerfile ci/trampoline_v2.sh
 ```
+
+## Detecting Doxygen schema changes
+
+From time to time we update Doxygen and that may result in schema changes.
+Detecting these changes may be useful to design the corresponding changes to the
+`doxygen2docfx` tool.
+
+The schema definition can be found in the [Doxygen GitHub Repository]. Look for
+[xml/compound.xsd](https://github.com/doxygen/doxygen/blob/master/templates/xml/compound.xsd)
+
+[doxygen github repository]: https://github.com/doxygen/doxygen
diff --git a/docfx/doxygen2yaml.cc b/docfx/doxygen2yaml.cc
@@ -59,6 +59,11 @@ bool IgnoreForRecurse(pugi::xml_node node) {
         //   This is a title for a sectionref (a "group" of member functions),
         //   maybe we can add this to break down each compound ToC.
         "header",
+        // Starting with Doxygen 1.9.7 any namespace members that are defined
+        // in a group appear as `member` children in the namespace, with just a
+        // `refid` pointing to its location. We need to skip these. They lack
+        // enough information to create a valid YAML element describing them.
+        "member",
     };
   }();
   auto const name = std::string{node.name()};
diff --git a/docfx/doxygen2yaml_test.cc b/docfx/doxygen2yaml_test.cc
@@ -1079,6 +1079,45 @@ TEST(Doxygen2Yaml, NamespaceDeprecated) {
   EXPECT_EQ(actual, kExpected);
 }
 
+TEST(Doxygen2Yaml, NamespaceMemberRefid) {
+  auto constexpr kXml =
+      R"xml(<?xml version='1.0' encoding='UTF-8' standalone='no'?>
+    <doxygen xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="compound.xsd" version="1.9.7" xml:lang="en-US">
+      <compounddef id="namespacegoogle_1_1cloud" kind="namespace" language="C++">
+      <compoundname>google::cloud</compoundname>
+        <member refid="group__terminate_1gacc215b41a0bf17a7ea762fd5bb205348" kind="typedef"><name>TerminateHandler</name></member>
+      </compounddef>
+    </doxygen>)xml";
+
+  auto constexpr kExpected = R"yml(### YamlMime:UniversalReference
+items:
+  - uid: namespacegoogle_1_1cloud
+    name: "google::cloud"
+    id: namespacegoogle_1_1cloud
+    parent: test-only-parent-id
+    type: namespace
+    langs:
+      - cpp
+    syntax:
+      contents: |
+        namespace google::cloud { ... };
+)yml";
+
+  pugi::xml_document doc;
+  doc.load_string(kXml);
+  auto selected = doc.select_node("//*[@id='namespacegoogle_1_1cloud']");
+  ASSERT_TRUE(selected);
+  YAML::Emitter yaml;
+  TestPre(yaml);
+  YamlContext ctx;
+  ctx.parent_id = "test-only-parent-id";
+  ctx.library_root = "google/cloud";
+  ASSERT_TRUE(AppendIfNamespace(yaml, ctx, selected.node()));
+  TestPost(yaml);
+  auto const actual = EndDocFxYaml(yaml);
+  EXPECT_EQ(actual, kExpected);
+}
+
 TEST(Doxygen2Yaml, Class) {
   auto constexpr kExpected = R"yml(### YamlMime:UniversalReference
 items:
