From 3fb60bc74a4ed4e4c795f2f14fa112321a3c94cc Mon Sep 17 00:00:00 2001
From: Don Cross <cosinekitty@users.noreply.github.com>
Date: Wed, 4 May 2022 12:33:21 -0400
Subject: Support code blocks and inline code for GFM format (#2485)

Fixes #2477.

Inline code, text that is nested within a pair of backquotes,
is now converted into GitHub Flavored Markdown (gfm) without
stripping out the backquotes. For example:

    The parameter `sum` must be a non-negative real number.

Code blocks, which are any number of lines of literal text
between triple-backquotes, and an optional programming language
name, are now preserved. If absent, the programming language
is assumed to be "kotlin". This follows the behavior of the
html renderer. For example:

    Here is an example of calling the function:
    ```kotlin
    val sum = addThemUp(left, right)
    ```
---
 plugins/gfm/api/gfm.api                            |  4 ++
 .../dokka/gfm/renderer/CommonmarkRenderer.kt       | 16 ++++++++
 .../test/kotlin/renderers/gfm/CodeWrappingTest.kt  | 48 ++++++++++++++++++++++
 3 files changed, 68 insertions(+)
 create mode 100644 plugins/gfm/src/test/kotlin/renderers/gfm/CodeWrappingTest.kt

(limited to 'plugins/gfm')

diff --git a/plugins/gfm/api/gfm.api b/plugins/gfm/api/gfm.api
index ba189898..b6970211 100644
--- a/plugins/gfm/api/gfm.api
+++ b/plugins/gfm/api/gfm.api
@@ -41,6 +41,10 @@ public final class org/jetbrains/dokka/gfm/renderer/BriefCommentPreprocessor : o
 
 public class org/jetbrains/dokka/gfm/renderer/CommonmarkRenderer : org/jetbrains/dokka/base/renderers/DefaultRenderer {
 	public fun <init> (Lorg/jetbrains/dokka/plugability/DokkaContext;)V
+	public synthetic fun buildCodeBlock (Ljava/lang/Object;Lorg/jetbrains/dokka/pages/ContentCodeBlock;Lorg/jetbrains/dokka/pages/ContentPage;)V
+	public fun buildCodeBlock (Ljava/lang/StringBuilder;Lorg/jetbrains/dokka/pages/ContentCodeBlock;Lorg/jetbrains/dokka/pages/ContentPage;)V
+	public synthetic fun buildCodeInline (Ljava/lang/Object;Lorg/jetbrains/dokka/pages/ContentCodeInline;Lorg/jetbrains/dokka/pages/ContentPage;)V
+	public fun buildCodeInline (Ljava/lang/StringBuilder;Lorg/jetbrains/dokka/pages/ContentCodeInline;Lorg/jetbrains/dokka/pages/ContentPage;)V
 	public synthetic fun buildDRILink (Ljava/lang/Object;Lorg/jetbrains/dokka/pages/ContentDRILink;Lorg/jetbrains/dokka/pages/ContentPage;Ljava/util/Set;)V
 	public fun buildDRILink (Ljava/lang/StringBuilder;Lorg/jetbrains/dokka/pages/ContentDRILink;Lorg/jetbrains/dokka/pages/ContentPage;Ljava/util/Set;)V
 	public synthetic fun buildDivergent (Ljava/lang/Object;Lorg/jetbrains/dokka/pages/ContentDivergentGroup;Lorg/jetbrains/dokka/pages/ContentPage;)V
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 13322944..d192b9a6 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
@@ -311,6 +311,22 @@ open class CommonmarkRenderer(
         }
     }
 
+    override fun StringBuilder.buildCodeBlock(code: ContentCodeBlock, pageContext: ContentPage) {
+        append("```")
+        append(code.language.ifEmpty { "kotlin" })
+        buildNewLine()
+        code.children.forEach { it.build(this, pageContext) }
+        buildNewLine()
+        append("```")
+        buildNewLine()
+    }
+
+    override fun StringBuilder.buildCodeInline(code: ContentCodeInline, pageContext: ContentPage) {
+        append("`")
+        code.children.forEach { it.build(this, pageContext) }
+        append("`")
+    }
+
     private fun decorators(styles: Set<Style>) = buildString {
         styles.forEach {
             when (it) {
diff --git a/plugins/gfm/src/test/kotlin/renderers/gfm/CodeWrappingTest.kt b/plugins/gfm/src/test/kotlin/renderers/gfm/CodeWrappingTest.kt
new file mode 100644
index 00000000..ce0c3d0c
--- /dev/null
+++ b/plugins/gfm/src/test/kotlin/renderers/gfm/CodeWrappingTest.kt
@@ -0,0 +1,48 @@
+package renderers.gfm
+
+import org.jetbrains.dokka.gfm.renderer.CommonmarkRenderer
+import org.jetbrains.dokka.pages.TextStyle
+import org.junit.jupiter.api.Test
+import kotlin.test.assertEquals
+import renderers.*
+
+class CodeWrappingTest : GfmRenderingOnlyTestBase() {
+    @Test
+    fun wrappedCodeBlock() {
+        val page = testPage {
+            codeBlock {
+                text("fun myCode(): String")
+            }
+        }
+        val expect = """|//[testPage](test-page.md)
+                        |
+                        |```kotlin
+                        |fun myCode(): String
+                        |```""".trimMargin()
+
+        CommonmarkRenderer(context).render(page)
+        assertEquals(expect, renderedContent)
+    }
+
+    @Test
+    fun wrappedInlineCode() {
+        val page = testPage {
+            text("This function adds the values of ")
+            codeInline("") { 
+                text("left") 
+            }
+            text(" and ")
+            codeInline("") {
+                text("right")
+            }
+            text(".\nBoth numbers must be finite, or an exception occurs.\n")
+        }
+        val expect = """|//[testPage](test-page.md)
+                        |
+                        |This function adds the values of `left` and `right`.
+                        |Both numbers must be finite, or an exception occurs.""".trimMargin()
+
+        CommonmarkRenderer(context).render(page)
+        assertEquals(expect, renderedContent)
+    }
+}
-- 
cgit