From e6ec2abd77784e0446129b4bb138f214d9e5de00 Mon Sep 17 00:00:00 2001 From: Spencer Gilson Date: Fri, 29 Oct 2021 06:01:02 -0700 Subject: 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 --- .../dokka/gfm/renderer/CommonmarkRenderer.kt | 69 ++++---- .../kotlin/renderers/gfm/SimpleElementsTest.kt | 177 ++++++++++++++++++++- 2 files changed, 213 insertions(+), 33 deletions(-) (limited to 'plugins/gfm/src') 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? ) { buildParagraph() - buildListLevel(node, pageContext) + buildList(node, pageContext) buildParagraph() } - private fun StringBuilder.buildListItem(items: List, 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("
  • ") - append(buildString { it.build(this, pageContext, it.sourceSets) }.trim()) - append("
    • ") + append("- ") } - } - } - private fun StringBuilder.buildListLevel(node: ContentList, pageContext: ContentPage) { - if (node.ordered) { - append("
      ") - buildListItem(node.children, pageContext) - append("
    ") - } else { - append("
      ") - buildListItem(node.children, pageContext) - append("
    ") + /* + Handle case when list item transitions to another complex node with no preceding text. + For example, the equivalent of: +
  • +
      • Item
    +
    • + + 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) + } } -- cgit