impl(docfx): support orderedlist elements (#10949)

googleapis · Feb 24, 2023 · a5572b1 · a5572b1
1 parent c7e9ffe
commit a5572b1
Show file tree

Hide file tree

Showing 3 changed files with 76 additions and 5 deletions.
diff --git a/docfx/doxygen2markdown.cc b/docfx/doxygen2markdown.cc
@@ -504,7 +504,7 @@ bool AppendIfDocCmdGroup(std::ostream& os, MarkdownContext const& ctx,
   // Unexpected: hruler, preformatted
   if (AppendIfProgramListing(os, ctx, node)) return true;
   // Unexpected: verbatim, indexentry
-  // Unexpected: orderedlist
+  if (AppendIfOrderedList(os, ctx, node)) return true;
   if (AppendIfItemizedList(os, ctx, node)) return true;
   if (AppendIfSimpleSect(os, ctx, node)) return true;
   // Unexpected: title
@@ -646,11 +646,26 @@ bool AppendIfHighlightRef(std::ostream& os, MarkdownContext const& ctx,
   return true;
 }
 
+/// Handle `orderedlist` elements.
+bool AppendIfOrderedList(std::ostream& os, MarkdownContext const& ctx,
+                         pugi::xml_node const& node) {
+  if (std::string_view{node.name()} != "orderedlist") return false;
+  auto nested = ctx;
+  nested.paragraph_indent = std::string(ctx.paragraph_indent.size(), ' ');
+  nested.item_prefix = "1. ";
+  for (auto const& child : node) {
+    if (AppendIfListItem(os, nested, child)) continue;
+    UnknownChildType(__func__, child);
+  }
+  return true;
+}
+
 bool AppendIfItemizedList(std::ostream& os, MarkdownContext const& ctx,
                           pugi::xml_node const& node) {
   if (std::string_view{node.name()} != "itemizedlist") return false;
   auto nested = ctx;
   nested.paragraph_indent = std::string(ctx.paragraph_indent.size(), ' ');
+  nested.item_prefix = "- ";
   for (auto const& child : node) {
     if (AppendIfListItem(os, nested, child)) continue;
     UnknownChildType(__func__, child);
@@ -662,15 +677,16 @@ bool AppendIfListItem(std::ostream& os, MarkdownContext const& ctx,
                       pugi::xml_node const& node) {
   if (std::string_view{node.name()} != "listitem") return false;
   // The first paragraph is the list item is indented as needed, and starts
-  // with a "- "
+  // with the item prefix (typically "- " or "1. ").
   auto nested = ctx;
   nested.paragraph_start = "\n";
-  nested.paragraph_indent = ctx.paragraph_indent + "- ";
+  nested.paragraph_indent = ctx.paragraph_indent + ctx.item_prefix;
   for (auto const& child : node) {
     if (AppendIfParagraph(os, nested, child)) {
       // Subsequence paragraphs within the same list item require a blank line
       nested.paragraph_start = "\n\n";
-      nested.paragraph_indent = ctx.paragraph_indent + "  ";
+      nested.paragraph_indent =
+          ctx.paragraph_indent + std::string(ctx.item_prefix.size(), ' ');
       continue;
     }
     UnknownChildType(__func__, child);

diff --git a/docfx/doxygen2markdown.h b/docfx/doxygen2markdown.h
@@ -28,7 +28,8 @@
  */
 struct MarkdownContext {
   std::string paragraph_start = "\n\n";
-  std::string paragraph_indent = "";
+  std::string paragraph_indent;
+  std::string item_prefix;
   std::vector<std::string> decorators;
 };
 
@@ -140,6 +141,10 @@ bool AppendIfHighlightRef(std::ostream& os, MarkdownContext const& ctx,
 bool AppendIfItemizedList(std::ostream& os, MarkdownContext const& ctx,
                           pugi::xml_node const& node);
 
+/// Handle `orderedlist` elements.
+bool AppendIfOrderedList(std::ostream& os, MarkdownContext const& ctx,
+                         pugi::xml_node const& node);
+
 /// Handle a single list item.
 bool AppendIfListItem(std::ostream& os, MarkdownContext const& ctx,
                       pugi::xml_node const& node);

diff --git a/docfx/doxygen2markdown_test.cc b/docfx/doxygen2markdown_test.cc
@@ -480,6 +480,35 @@ TEST(Doxygen2Markdown, ParagraphSimpleSect) {
   EXPECT_EQ(kExpected, os.str());
 }
 
+TEST(Doxygen2Markdown, ParagraphOrderedList) {
+  auto constexpr kXml = R"xml(<?xml version="1.0" standalone="yes"?>
+    <doxygen version="1.9.1" xml:lang="en-US">
+        <para id='test-node'>
+          <orderedlist>
+            <listitem><para>First item.</para></listitem>
+            <listitem>
+              <para>Second item.</para><para>With a second paragraph.</para>
+            </listitem>
+          </orderedlist>
+        </para>
+    </doxygen>)xml";
+
+  auto constexpr kExpected = R"md(
+
+
+1. First item.
+1. Second item.
+
+   With a second paragraph.)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, ParagraphItemizedList) {
   auto constexpr kXml = R"xml(<?xml version="1.0" standalone="yes"?>
     <doxygen version="1.9.1" xml:lang="en-US">
@@ -628,6 +657,27 @@ TEST(Doxygen2Markdown, ItemizedListNested) {
   - Sub 3)md");
 }
 
+TEST(Doxygen2Markdown, OrderedListWithParagraphs) {
+  auto constexpr kXml = R"xml(<?xml version="1.0" standalone="yes"?>
+    <doxygen version="1.9.1" xml:lang="en-US">
+        <orderedlist id='test-node'>
+          <listitem><para>Item 1</para><para>More about Item 1</para></listitem>
+          <listitem><para>Item 2: <computeroutput>brrr</computeroutput></para></listitem>
+        </orderedlist>
+    </doxygen>)xml";
+  auto constexpr kExpected = R"md(
+1. Item 1
+
+   More about Item 1
+1. Item 2: `brrr`)md";
+  pugi::xml_document doc;
+  doc.load_string(kXml);
+  auto selected = doc.select_node("//*[@id='test-node']");
+  std::ostringstream os;
+  ASSERT_TRUE(AppendIfOrderedList(os, {}, selected.node()));
+  EXPECT_EQ(kExpected, os.str());
+}
+
 TEST(Doxygen2Markdown, VariableListSimple) {
   auto constexpr kXml = R"xml(<?xml version="1.0" standalone="yes"?>
     <doxygen version="1.9.1" xml:lang="en-US">