GFM: Use Markdown syntax to render lists (#2098)

* - Add ListBuilder to PageContentBuilder.kt to make testing feasible through the builder DSL
- Switch list representation in CommonmarkRenderer.kt to use Markdown syntax instead of HTML
- Switch to non-deprecated Assert in SimpleElementsTest.kt

* Updating base.api to include new builder class and methods

2 files changed, 213 insertions, 33 deletions

diff --git a/plugins/gfm/src/main/kotlin/org/jetbrains/dokka/gfm/renderer/CommonmarkRenderer.kt b/plugins/gfm/src/main/kotlin/org/jetbrains/dokka/gfm/renderer/CommonmarkRenderer.kt
index c05bd07e..786e410d 100644
--- a/plugins/gfm/src/main/kotlin/org/jetbrains/dokka/gfm/renderer/CommonmarkRenderer.kt
+++ b/plugins/gfm/src/main/kotlin/org/jetbrains/dokka/gfm/renderer/CommonmarkRenderer.kt
@@ -55,31 +55,42 @@ open class CommonmarkRenderer(
         sourceSetRestriction: Set<DisplaySourceSet>?
     ) {
         buildParagraph()
-        buildListLevel(node, pageContext)
+        buildList(node, pageContext)
         buildParagraph()
     }
 
-    private fun StringBuilder.buildListItem(items: List<ContentNode>, pageContext: ContentPage) {
-        items.forEach {
-            if (it is ContentList) {
-                buildList(it, pageContext)
+    private fun StringBuilder.buildList(
+        node: ContentList,
+        pageContext: ContentPage
+    ) {
+        node.children.forEachIndexed { i, it ->
+            if (node.ordered) {
+                // number is irrelevant, but a nice touch
+                // period is more widely compatible
+                append("${i + 1}. ")
             } else {
-                append("<li>")
-                append(buildString { it.build(this, pageContext, it.sourceSets) }.trim())
-                append("</li>")
+                append("- ")
             }
-        }
-    }
 
-    private fun StringBuilder.buildListLevel(node: ContentList, pageContext: ContentPage) {
-        if (node.ordered) {
-            append("<ol>")
-            buildListItem(node.children, pageContext)
-            append("</ol>")
-        } else {
-            append("<ul>")
-            buildListItem(node.children, pageContext)
-            append("</ul>")
+            /*
+            Handle case when list item transitions to another complex node with no preceding text.
+            For example, the equivalent of:
+            <li>
+               <ul><li><ul>Item</ul></li></ul>
+            </li>
+
+            Would be:
+            -
+               - Item
+             */
+            if (it is ContentGroup && it.children.firstOrNull()?.let { it !is ContentText } == true) {
+                append("\n   ")
+            }
+
+            buildString { it.build(this, pageContext, it.sourceSets) }
+                .replace("\n", "\n   ") // apply indent
+                .trim().let { append(it) }
+            buildNewLine()
         }
     }
 
@@ -328,18 +339,18 @@ open class CommonmarkRenderer(
                 is RenderingStrategy.Write -> outputWriter.write(path, strategy.text, "")
                 is RenderingStrategy.Callback -> outputWriter.write(path, strategy.instructions(this, page), ".md")
                 is RenderingStrategy.DriLocationResolvableWrite -> outputWriter.write(
-                        path,
-                        strategy.contentToResolve { dri, sourcesets ->
-                            locationProvider.resolve(dri, sourcesets)
-                        },
-                        ""
+                    path,
+                    strategy.contentToResolve { dri, sourcesets ->
+                        locationProvider.resolve(dri, sourcesets)
+                    },
+                    ""
                 )
                 is RenderingStrategy.PageLocationResolvableWrite -> outputWriter.write(
-                        path,
-                        strategy.contentToResolve { pageToLocate, context ->
-                            locationProvider.resolve(pageToLocate, context)
-                        },
-                        ""
+                    path,
+                    strategy.contentToResolve { pageToLocate, context ->
+                        locationProvider.resolve(pageToLocate, context)
+                    },
+                    ""
                 )
                 RenderingStrategy.DoNothing -> Unit
             }
diff --git a/plugins/gfm/src/test/kotlin/renderers/gfm/SimpleElementsTest.kt b/plugins/gfm/src/test/kotlin/renderers/gfm/SimpleElementsTest.kt
index b4af12b2..e102f52a 100644
--- a/plugins/gfm/src/test/kotlin/renderers/gfm/SimpleElementsTest.kt
+++ b/plugins/gfm/src/test/kotlin/renderers/gfm/SimpleElementsTest.kt
@@ -1,12 +1,15 @@
 package renderers.gfm
 
-import junit.framework.Assert.assertEquals
 import org.jetbrains.dokka.gfm.renderer.CommonmarkRenderer
-import org.junit.jupiter.api.Test
-import renderers.testPage
 import org.jetbrains.dokka.links.DRI
-import org.jetbrains.dokka.pages.*
+import org.jetbrains.dokka.pages.ContentEmbeddedResource
+import org.jetbrains.dokka.pages.ContentKind
+import org.jetbrains.dokka.pages.DCI
+import org.jetbrains.dokka.pages.TextStyle
+import org.junit.Assert.assertEquals
+import org.junit.jupiter.api.Test
 import renderers.RawTestPage
+import renderers.testPage
 
 class SimpleElementsTest : GfmRenderingOnlyTestBase() {
 
@@ -217,4 +220,170 @@ class SimpleElementsTest : GfmRenderingOnlyTestBase() {
         assertEquals(expect, renderedContent)
     }
 
+    @Test
+    fun `unordered list with two items`() {
+        val page = testPage {
+            unorderedList {
+                item { text("Item 1") }
+                item { text("Item 2") }
+            }
+        }
+
+        val expect = """|//[testPage](test-page.md)
+                        |
+                        |- Item 1
+                        |- Item 2""".trimMargin()
+
+        CommonmarkRenderer(context).render(page)
+        assertEquals(expect, renderedContent)
+    }
+
+    @Test
+    fun `unordered list with styled text`() {
+        val page = testPage {
+            unorderedList {
+                item {
+                    text("Nobody", styles = setOf(TextStyle.Italic))
+                    text(" tosses a Dwarf!")
+                }
+            }
+        }
+
+        val expect = "//[testPage](test-page.md)\n\n- *Nobody* tosses a Dwarf!"
+
+        CommonmarkRenderer(context).render(page)
+        assertEquals(expect, renderedContent)
+    }
+
+    @Test
+    fun `ordered list with two items`() {
+        val page = testPage {
+            orderedList {
+                item { text("Item 1") }
+                item { text("Item 2") }
+            }
+        }
+
+        val expect = """|//[testPage](test-page.md)
+                        |
+                        |1. Item 1
+                        |2. Item 2""".trimMargin()
+
+        CommonmarkRenderer(context).render(page)
+        assertEquals(expect, renderedContent)
+    }
+
+    @Test
+    fun `ordered list with nested unordered list`() {
+        val page = testPage {
+            orderedList {
+                item {
+                    text("And another list:")
+                    unorderedList {
+                        item { text("Item 1") }
+                        item { text("Item 2") }
+                    }
+                }
+                item { text("Following item") }
+            }
+        }
+
+        val expect = """|//[testPage](test-page.md)
+                        |
+                        |1. And another list:
+                        |   
+                        |   - Item 1
+                        |   - Item 2
+                        |2. Following item""".trimMargin()
+
+        CommonmarkRenderer(context).render(page)
+        assertEquals(expect, renderedContent)
+    }
+
+    @Test
+    fun `ordered list with nested table`() {
+        val page = testPage {
+            orderedList {
+                item {
+                    text("The following table is nested in a list:")
+                    table {
+                        header {
+                            text("Col1")
+                            text("Col2")
+                        }
+                        row {
+                            text("Text1")
+                            text("Text2")
+                        }
+                    }
+                }
+            }
+        }
+
+        val expect = """|//[testPage](test-page.md)
+                        |
+                        |1. The following table is nested in a list:
+                        |   | Col1 | Col2 |
+                        |   |---|---|
+                        |   | Text1 | Text2 |""".trimMargin()
+
+        CommonmarkRenderer(context).render(page)
+        assertEquals(expect, renderedContent)
+    }
+
+    @Test
+    fun `three levels of list`() {
+        val page = testPage {
+            unorderedList {
+                item {
+                    text("Level 1")
+                    unorderedList {
+                        item {
+                            text("Level 2")
+                            unorderedList {
+                                item {
+                                    text("Level 3")
+                                }
+                            }
+                        }
+                    }
+                }
+            }
+        }
+
+        // Extra newlines are not pretty but do not impact formatting
+        val expect = """|//[testPage](test-page.md)
+                        |
+                        |- Level 1
+                        |   
+                        |   - Level 2
+                        |      
+                        |      - Level 3""".trimMargin()
+
+        CommonmarkRenderer(context).render(page)
+        assertEquals(expect, renderedContent)
+    }
+
+    @Test
+    fun `nested list with no text preceding it`() {
+        val page = testPage {
+            unorderedList {
+                item {
+                    unorderedList {
+                        item {
+                            text("Nested")
+                        }
+                    }
+                }
+            }
+        }
+
+        val expect = """|//[testPage](test-page.md)
+                        |
+                        |- 
+                        |   - Nested""".trimMargin()
+
+        CommonmarkRenderer(context).render(page)
+        assertEquals(expect, renderedContent)
+    }
 }