impl(docfx): support <verbatim> elements (googleapis#11294)

coryan · web-flow · commit ef8101bd4283 · 2023-04-17T09:01:38.000-04:00
diff --git a/docfx/doxygen2markdown.cc b/docfx/doxygen2markdown.cc
@@ -448,7 +448,8 @@ bool AppendIfDocCmdGroup(std::ostream& os, MarkdownContext const& ctx,
   if (AppendIfDocTitleCmdGroup(os, ctx, node)) return true;
   // Unexpected: hruler, preformatted
   if (AppendIfProgramListing(os, ctx, node)) return true;
-  // Unexpected: verbatim, indexentry
+  // Unexpected: indexentry
+  if (AppendIfVerbatim(os, ctx, node)) return true;
   if (AppendIfOrderedList(os, ctx, node)) return true;
   if (AppendIfItemizedList(os, ctx, node)) return true;
   if (AppendIfSimpleSect(os, ctx, node)) return true;
@@ -508,6 +509,16 @@ bool AppendIfProgramListing(std::ostream& os, MarkdownContext const& ctx,
   return true;
 }
 
+// The type for `verbatim` is a simple string.
+bool AppendIfVerbatim(std::ostream& os, MarkdownContext const& ctx,
+                      pugi::xml_node const& node) {
+  if (std::string_view{node.name()} != "verbatim") return false;
+  os << ctx.paragraph_start << ctx.paragraph_indent << "```\n"
+     << ctx.paragraph_indent << node.child_value() << "\n"
+     << ctx.paragraph_indent << "```";
+  return true;
+}
+
 // The type for `codeline` is basically a sequence of highlights (think "syntax
 // highlighting", not "important things"). We will discard this information and
 // rely in the target markdown to generate the right coloring.
diff --git a/docfx/doxygen2markdown.h b/docfx/doxygen2markdown.h
@@ -133,6 +133,10 @@ bool AppendIfParagraph(std::ostream& os, MarkdownContext const& ctx,
 bool AppendIfProgramListing(std::ostream& os, MarkdownContext const& ctx,
                             pugi::xml_node const& node);
 
+/// Handle `verbatim` elements.
+bool AppendIfVerbatim(std::ostream& os, MarkdownContext const& ctx,
+                      pugi::xml_node const& node);
+
 /// Handle `codeline` elements.
 bool AppendIfCodeline(std::ostream& os, MarkdownContext const& ctx,
                       pugi::xml_node const& node);
diff --git a/docfx/doxygen2markdown_test.cc b/docfx/doxygen2markdown_test.cc
@@ -633,6 +633,32 @@ for (StatusOr<int> const& v : sr) {
   EXPECT_EQ(kExpected, os.str());
 }
 
+TEST(Doxygen2Markdown, ParagraphVerbatim) {
+  auto constexpr kXml = R"xml(<?xml version="1.0" standalone="yes"?>
+    <doxygen version="1.9.1" xml:lang="en-US">
+        <para id='test-node'>
+          <verbatim>https://cloud.google.com/storage/docs/transcoding
+</verbatim>
+        </para>
+    </doxygen>)xml";
+
+  auto constexpr kExpected = R"md(
+
+
+
+```
+https://cloud.google.com/storage/docs/transcoding
+
+```)md";
+
+  pugi::xml_document doc;
+  doc.load_string(kXml);
+  auto selected = doc.select_node("//*[@id='test-node']");
+  std::ostringstream os;
+  ASSERT_TRUE(AppendIfParagraph(os, {}, selected.node()));
+  EXPECT_EQ(kExpected, os.str());
+}
+
 TEST(Doxygen2Markdown, ParagraphXrefSect) {
   auto constexpr kXml = R"xml(<?xml version="1.0" standalone="yes"?>
     <doxygen version="1.9.1" xml:lang="en-US">
