From dacef0a1e5440c447a3a28e6ab7afadec6f2bf1c Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Ivan=20=E2=80=9CCLOVIS=E2=80=9D=20Canet?=
 <ivan.canet@gmail.com>
Date: Fri, 23 Aug 2024 21:58:05 +0200
Subject: [PATCH 1/7] feat(renderer): Improve the design of regular text

---
 .../src/main/kotlin/renderer/Decoration.kt    | 108 ++++++++++++++++++
 .../main/kotlin/renderer/MkDocsRenderer2.kt   |  38 +++++-
 2 files changed, 142 insertions(+), 4 deletions(-)
 create mode 100644 renderer/src/main/kotlin/renderer/Decoration.kt

diff --git a/renderer/src/main/kotlin/renderer/Decoration.kt b/renderer/src/main/kotlin/renderer/Decoration.kt
new file mode 100644
index 0000000..d3e9ef1
--- /dev/null
+++ b/renderer/src/main/kotlin/renderer/Decoration.kt
@@ -0,0 +1,108 @@
+package opensavvy.dokka.material.mkdocs.renderer
+
+import org.jetbrains.dokka.pages.Style
+import org.jetbrains.dokka.pages.TextStyle
+import org.jetbrains.dokka.pages.TokenStyle
+
+// region Data structure
+
+fun interface Decoration {
+
+	fun StringBuilder.wrap(content: StringBuilder.() -> Unit)
+
+	companion object {
+		fun ofSpan(className: String) =
+			Decoration { content ->
+				append("<span class=\"$className\">")
+				content()
+				append("</span>")
+			}
+
+		fun ofElement(elementName: String) =
+			Decoration { content ->
+				append("<$elementName>")
+				content()
+				append("</$elementName>")
+			}
+
+		val NoOp = Decoration {content ->
+			content()
+		}
+	}
+}
+
+// endregion
+// region DSL declaration
+
+class Decorations {
+
+	private val groups = ArrayList<Pair<Style, Decoration>>()
+	private val inlines = ArrayList<Pair<Style, Decoration>>()
+
+	constructor(block: Decorations.() -> Unit) {
+		block()
+	}
+
+	fun group(style: Style, block: Decoration) {
+		groups += style to block
+	}
+
+	fun inline(style: Style, block: Decoration) {
+		inlines += style to block
+	}
+
+	fun fromGroupStyles(style: Iterable<Style>) = style
+		.mapNotNull { groups.find { (style, _) -> style == it } }
+		.map { it.second }
+
+	fun fromInlineStyles(style: Iterable<Style>) = style
+		.mapNotNull { inlines.find { (style, _) -> style == it } }
+		.map { it.second }
+}
+
+// endregion
+// region Generate from Dokka data
+
+val decorations = Decorations {
+	inline(TextStyle.Block, Decoration.ofElement("strong"))
+	inline(TextStyle.Italic, Decoration.ofElement("em"))
+
+	group(TextStyle.Paragraph, Decoration.ofElement("p"))
+	group(TextStyle.Monospace) { content ->
+		append("<div class=\"highlight\">")
+		append("<pre>")
+		append("<code class=\"md-code__content\">")
+		append("<span>")
+		content()
+		append("</span>")
+		append("</code>")
+		append("</pre>")
+		append("</div>")
+	}
+
+	inline(TokenStyle.Keyword, Decoration.ofSpan("kd"))
+	inline(TokenStyle.Punctuation, Decoration.ofSpan("p"))
+	inline(TokenStyle.Function, Decoration.ofSpan("nf"))
+	inline(TokenStyle.Operator, Decoration.ofSpan("o"))
+	inline(TokenStyle.Annotation, Decoration.ofSpan("se"))
+	inline(TokenStyle.Number, Decoration.ofSpan("mi"))
+	inline(TokenStyle.String, Decoration.ofSpan("s"))
+	inline(TokenStyle.Boolean, Decoration.ofSpan("kc"))
+	inline(TokenStyle.Constant, Decoration.ofSpan("nb"))
+}
+
+// endregion
+// region Helpers
+
+fun Decoration.wrapIn(builder: StringBuilder, block: StringBuilder.() -> Unit) = with(builder) {
+	wrap(block)
+}
+
+fun Iterator<Decoration>.wrapIn(builder: StringBuilder, block: StringBuilder.() -> Unit) {
+	when {
+		!hasNext() -> block(builder)
+		else -> next().wrapIn(builder) { wrapIn(builder, block) }
+	}
+}
+
+// endregion
diff --git a/renderer/src/main/kotlin/renderer/MkDocsRenderer2.kt b/renderer/src/main/kotlin/renderer/MkDocsRenderer2.kt
index c66604b..26c7e4e 100644
--- a/renderer/src/main/kotlin/renderer/MkDocsRenderer2.kt
+++ b/renderer/src/main/kotlin/renderer/MkDocsRenderer2.kt
@@ -21,8 +21,25 @@ open class MkDocsRenderer2(
 		context.logger.warn("MkDocs renderer has encountered problem. The unmatched node is $node")
 	}
 
+	override fun StringBuilder.wrapGroup(node: ContentGroup, pageContext: ContentPage, childrenCallback: StringBuilder.() -> Unit) {
+		// appendLine("\n\nSTART OF CONTENT GROUP $node\n")
+
+		val styles = decorations.fromGroupStyles(node.style)
+
+		styles.iterator().wrapIn(this) {
+			childrenCallback()
+		}
+
+		appendLine()
+		appendLine()
+	}
+
 	override fun StringBuilder.buildText(textNode: ContentText) {
-		appendLine("TEXT NODE $textNode\n")
+		val styles = decorations.fromInlineStyles(textNode.style)
+
+		styles.iterator().wrapIn(this) {
+			append(textNode.text)
+		}
 	}
 
 	override fun StringBuilder.buildTable(node: ContentTable, pageContext: ContentPage, sourceSetRestriction: Set<DisplaySourceSet>?) {
@@ -65,9 +82,9 @@ open class MkDocsRenderer2(
 		}
 
 	override fun StringBuilder.buildLink(address: String, content: StringBuilder.() -> Unit) {
-		append("<a href=\"$address\">\n")
+		append("<a href=\"$address\">")
 		content()
-		append("\n</a>")
+		append("</a>")
 	}
 
 	override fun StringBuilder.buildDRILink(
@@ -102,7 +119,20 @@ open class MkDocsRenderer2(
 	}
 
 	override fun StringBuilder.buildHeader(level: Int, node: ContentHeader, content: StringBuilder.() -> Unit) {
-		appendLine("HEADER $node\n")
+		val decorator = when (level) {
+			1 -> Decoration.ofElement("h1")
+			2 -> Decoration.ofElement("h2")
+			3 -> Decoration.ofElement("h3")
+			4 -> Decoration.ofElement("h4")
+			5 -> Decoration.ofElement("h5")
+			else -> Decoration.ofElement("h6")
+		}
+
+		decorator.wrapIn(this) {
+			content()
+		}
+
+		appendLine()
 	}
 
 	// region Overall page rendering
-- 
2.51.2


From 170f08e2778444757e50d5e78a330374ac33314d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Ivan=20=E2=80=9CCLOVIS=E2=80=9D=20Canet?=
 <ivan.canet@gmail.com>
Date: Fri, 23 Aug 2024 22:24:27 +0200
Subject: [PATCH 2/7] feat(renderer): Put full node text in HTML comments

---
 .../src/main/kotlin/renderer/MkDocsRenderer2.kt | 17 ++++++++++++-----
 1 file changed, 12 insertions(+), 5 deletions(-)

diff --git a/renderer/src/main/kotlin/renderer/MkDocsRenderer2.kt b/renderer/src/main/kotlin/renderer/MkDocsRenderer2.kt
index 26c7e4e..fbd1dc1 100644
--- a/renderer/src/main/kotlin/renderer/MkDocsRenderer2.kt
+++ b/renderer/src/main/kotlin/renderer/MkDocsRenderer2.kt
@@ -22,11 +22,10 @@ open class MkDocsRenderer2(
 	}
 
 	override fun StringBuilder.wrapGroup(node: ContentGroup, pageContext: ContentPage, childrenCallback: StringBuilder.() -> Unit) {
-		// appendLine("\n\nSTART OF CONTENT GROUP $node\n")
-
 		val styles = decorations.fromGroupStyles(node.style)
 
 		styles.iterator().wrapIn(this) {
+			buildComment { "CONTENT GROUP $node" }
 			childrenCallback()
 		}
 
@@ -38,16 +37,17 @@ open class MkDocsRenderer2(
 		val styles = decorations.fromInlineStyles(textNode.style)
 
 		styles.iterator().wrapIn(this) {
+			buildComment { "TEXT $textNode" }
 			append(textNode.text)
 		}
 	}
 
 	override fun StringBuilder.buildTable(node: ContentTable, pageContext: ContentPage, sourceSetRestriction: Set<DisplaySourceSet>?) {
-		appendLine("TABLE NODE $node\n")
+		buildComment { "TABLE NODE $node" }
 	}
 
 	override fun StringBuilder.buildResource(node: ContentEmbeddedResource, pageContext: ContentPage) {
-		appendLine("RESOURCE NODE $node\n")
+		buildComment { "RESOURCE NODE $node" }
 	}
 
 	override fun StringBuilder.buildNavigation(page: PageNode) {
@@ -71,7 +71,7 @@ open class MkDocsRenderer2(
 	}
 
 	override fun StringBuilder.buildList(node: ContentList, pageContext: ContentPage, sourceSetRestriction: Set<DisplaySourceSet>?) {
-		appendLine("LIST NODES $node\n")
+		buildComment { "LIST NODE $node" }
 	}
 
 	// region Links
@@ -129,6 +129,7 @@ open class MkDocsRenderer2(
 		}
 
 		decorator.wrapIn(this) {
+			buildComment { "HEADER $node" }
 			content()
 		}
 
@@ -216,6 +217,12 @@ open class MkDocsRenderer2(
 		}.trim().replace("\n[\n]+".toRegex(), "\n\n")
 
 	// endregion
+
+	private inline fun StringBuilder.buildComment(content: () -> String) {
+		append("<!-- ")
+		append(content())
+		append(" -->")
+	}
 }
 
 private val PageNode.isNavigable: Boolean
-- 
2.51.2


From 03f702d5498c3a79cdb33e174ef3b67c038c876b Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Ivan=20=E2=80=9CCLOVIS=E2=80=9D=20Canet?=
 <ivan.canet@gmail.com>
Date: Fri, 23 Aug 2024 22:25:12 +0200
Subject: [PATCH 3/7] feat(renderer): Mark groups that are platform-dependent

---
 renderer/src/main/kotlin/renderer/MkDocsRenderer2.kt | 11 +++++++++++
 1 file changed, 11 insertions(+)

diff --git a/renderer/src/main/kotlin/renderer/MkDocsRenderer2.kt b/renderer/src/main/kotlin/renderer/MkDocsRenderer2.kt
index fbd1dc1..a729cde 100644
--- a/renderer/src/main/kotlin/renderer/MkDocsRenderer2.kt
+++ b/renderer/src/main/kotlin/renderer/MkDocsRenderer2.kt
@@ -26,6 +26,11 @@ open class MkDocsRenderer2(
 
 		styles.iterator().wrapIn(this) {
 			buildComment { "CONTENT GROUP $node" }
+
+			if (ContentKind.shouldBePlatformTagged(node.dci.kind)) {
+				buildPlatformMarkers(node.sourceSets)
+			}
+
 			childrenCallback()
 		}
 
@@ -223,6 +228,12 @@ open class MkDocsRenderer2(
 		append(content())
 		append(" -->")
 	}
+
+	fun StringBuilder.buildPlatformMarkers(sourceSets: Iterable<DisplaySourceSet>) {
+		for (sourceSet in sourceSets) {
+			append("<span class=\"md-typeset md-tag\">${sourceSet.name}</span>")
+		}
+	}
 }
 
 private val PageNode.isNavigable: Boolean
-- 
2.51.2


From 8a6f9f10c2cc58bc8b665b7b30ee568d08838b0d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Ivan=20=E2=80=9CCLOVIS=E2=80=9D=20Canet?=
 <ivan.canet@gmail.com>
Date: Fri, 23 Aug 2024 22:27:43 +0200
Subject: [PATCH 4/7] feat(renderer): Render code blocks in inline code

---
 .../main/kotlin/renderer/MkDocsRenderer2.kt   | 26 +++++++++++++++++++
 1 file changed, 26 insertions(+)

diff --git a/renderer/src/main/kotlin/renderer/MkDocsRenderer2.kt b/renderer/src/main/kotlin/renderer/MkDocsRenderer2.kt
index a729cde..93d9b9e 100644
--- a/renderer/src/main/kotlin/renderer/MkDocsRenderer2.kt
+++ b/renderer/src/main/kotlin/renderer/MkDocsRenderer2.kt
@@ -38,6 +38,32 @@ open class MkDocsRenderer2(
 		appendLine()
 	}
 
+	override fun StringBuilder.buildCodeBlock(code: ContentCodeBlock, pageContext: ContentPage) {
+		append("```")
+		append(code.language.ifEmpty { "kotlin" })
+		appendLine()
+		code.children.forEach {
+			if (it is ContentText) {
+				// since this is a code block where text will be rendered as is,
+				// no need to escape text, apply styles, etc. Just need the plain value
+				append(it.text)
+			} else if (it is ContentBreakLine) {
+				// since this is a code block where text will be rendered as is,
+				// there's no need to add tailing slash for line breaks
+				appendLine()
+			}
+		}
+		appendLine()
+		append("```")
+		appendLine()
+	}
+
+	override fun StringBuilder.buildCodeInline(code: ContentCodeInline, pageContext: ContentPage) {
+		append("`")
+		code.children.filterIsInstance<ContentText>().forEach { append(it.text) }
+		append("`")
+	}
+
 	override fun StringBuilder.buildText(textNode: ContentText) {
 		val styles = decorations.fromInlineStyles(textNode.style)
 
-- 
2.51.2


From 0ad4003061b08f9d9dc03aa67c9c1164674bac62 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Ivan=20=E2=80=9CCLOVIS=E2=80=9D=20Canet?=
 <ivan.canet@gmail.com>
Date: Fri, 23 Aug 2024 22:40:14 +0200
Subject: [PATCH 5/7] feat(renderer): Avoid intra-code block newlines

---
 renderer/src/main/kotlin/renderer/MkDocsRenderer2.kt | 5 +----
 1 file changed, 1 insertion(+), 4 deletions(-)

diff --git a/renderer/src/main/kotlin/renderer/MkDocsRenderer2.kt b/renderer/src/main/kotlin/renderer/MkDocsRenderer2.kt
index 93d9b9e..d1a56e1 100644
--- a/renderer/src/main/kotlin/renderer/MkDocsRenderer2.kt
+++ b/renderer/src/main/kotlin/renderer/MkDocsRenderer2.kt
@@ -33,13 +33,10 @@ open class MkDocsRenderer2(
 
 			childrenCallback()
 		}
-
-		appendLine()
-		appendLine()
 	}
 
 	override fun StringBuilder.buildCodeBlock(code: ContentCodeBlock, pageContext: ContentPage) {
-		append("```")
+		append("\n```")
 		append(code.language.ifEmpty { "kotlin" })
 		appendLine()
 		code.children.forEach {
-- 
2.51.2


From 476cb8367cb42e11d9cc6771a2bf36b9a808b5d4 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Ivan=20=E2=80=9CCLOVIS=E2=80=9D=20Canet?=
 <ivan.canet@gmail.com>
Date: Fri, 23 Aug 2024 22:40:51 +0200
Subject: [PATCH 6/7] feat(renderer): Easily disable comment generation

---
 renderer/src/main/kotlin/renderer/MkDocsRenderer2.kt | 10 +++++++---
 1 file changed, 7 insertions(+), 3 deletions(-)

diff --git a/renderer/src/main/kotlin/renderer/MkDocsRenderer2.kt b/renderer/src/main/kotlin/renderer/MkDocsRenderer2.kt
index d1a56e1..1d8f466 100644
--- a/renderer/src/main/kotlin/renderer/MkDocsRenderer2.kt
+++ b/renderer/src/main/kotlin/renderer/MkDocsRenderer2.kt
@@ -246,10 +246,14 @@ open class MkDocsRenderer2(
 
 	// endregion
 
+	private val INSERT_COMMENTS = true
+
 	private inline fun StringBuilder.buildComment(content: () -> String) {
-		append("<!-- ")
-		append(content())
-		append(" -->")
+		if (INSERT_COMMENTS) {
+			append("<!-- ")
+			append(content())
+			append(" -->")
+		}
 	}
 
 	fun StringBuilder.buildPlatformMarkers(sourceSets: Iterable<DisplaySourceSet>) {
-- 
2.51.2


From 7ecafc132f4362fe5fdb135eaf2c053a5ef8eceb Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Ivan=20=E2=80=9CCLOVIS=E2=80=9D=20Canet?=
 <ivan.canet@gmail.com>
Date: Fri, 23 Aug 2024 22:54:52 +0200
Subject: [PATCH 7/7] feat(renderer): Mark overloads with a horizontal rule

---
 renderer/src/main/kotlin/renderer/MkDocsRenderer2.kt | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/renderer/src/main/kotlin/renderer/MkDocsRenderer2.kt b/renderer/src/main/kotlin/renderer/MkDocsRenderer2.kt
index 1d8f466..bbd0970 100644
--- a/renderer/src/main/kotlin/renderer/MkDocsRenderer2.kt
+++ b/renderer/src/main/kotlin/renderer/MkDocsRenderer2.kt
@@ -24,6 +24,10 @@ open class MkDocsRenderer2(
 	override fun StringBuilder.wrapGroup(node: ContentGroup, pageContext: ContentPage, childrenCallback: StringBuilder.() -> Unit) {
 		val styles = decorations.fromGroupStyles(node.style)
 
+		if (node.dci.kind == ContentKind.Main && node.children.firstOrNull()?.dci?.kind == ContentKind.Symbol) {
+			appendLine("***")
+		}
+
 		styles.iterator().wrapIn(this) {
 			buildComment { "CONTENT GROUP $node" }
 
-- 
2.51.2