From 010d4064d85a5b622fff1f65087d1271781d7ad5 Mon Sep 17 00:00:00 2001 From: Jacob Wysko Date: Wed, 2 Feb 2022 22:22:27 -0500 Subject: [PATCH 1/4] Fix MathJax rendering bug (#2175) Fix a bug where using the `@usesMathJax` custom tag would cause the documentation to fail to render. I fixed this by making all custom tags render to the screen, which were being ignored. Along with this, I updated the existing test case to check for the presence of content in the output. Fixes #2175 --- .../documentables/DefaultPageCreator.kt | 15 +++++++++++ .../src/test/kotlin/MathjaxPluginTest.kt | 27 +++++++++++-------- 2 files changed, 31 insertions(+), 11 deletions(-) diff --git a/plugins/base/src/main/kotlin/translators/documentables/DefaultPageCreator.kt b/plugins/base/src/main/kotlin/translators/documentables/DefaultPageCreator.kt index c16996a056..b9b6d41e1b 100644 --- a/plugins/base/src/main/kotlin/translators/documentables/DefaultPageCreator.kt +++ b/plugins/base/src/main/kotlin/translators/documentables/DefaultPageCreator.kt @@ -340,6 +340,18 @@ open class DefaultPageCreator( } } } + val customTags = d.customTags + if (customTags.isNotEmpty()) { + group(styles = setOf(TextStyle.Block)) { + customTags.forEach { + group(styles = setOf(TextStyle.Block)) { + it.value.values.forEach { + comment(it.root) + } + } + } + } + } val unnamedTags = tags.filterNot { (k, _) -> k.isSubclassOf(NamedTagWrapper::class) || k in specialTags } .values.flatten().groupBy { it.first }.mapValues { it.value.map { it.second } } @@ -706,6 +718,9 @@ open class DefaultPageCreator( private val Documentable.descriptions: SourceSetDependent get() = groupedTags.withTypeUnnamed() + private val Documentable.customTags: Map> + get() = groupedTags.withTypeNamed() + private val Documentable.hasSeparatePage: Boolean get() = this !is DTypeAlias diff --git a/plugins/mathjax/src/test/kotlin/MathjaxPluginTest.kt b/plugins/mathjax/src/test/kotlin/MathjaxPluginTest.kt index da1660839d..b6302cd22e 100644 --- a/plugins/mathjax/src/test/kotlin/MathjaxPluginTest.kt +++ b/plugins/mathjax/src/test/kotlin/MathjaxPluginTest.kt @@ -53,15 +53,17 @@ class MathjaxPluginTest : BaseAbstractTest() { } } } + val math = """ + a^2 = b^2 + c^2 + """.trimIndent() val source = """ |/src/main/kotlin/test/Test.kt |package example | /** | * @usesMathJax - | * - | * \(\alpha_{out} = \alpha_{dst}\) - | * \(C_{out} = C_{dst}\) + | * + | * \($math\) | */ | fun test(): String = "" """.trimIndent() @@ -71,14 +73,17 @@ class MathjaxPluginTest : BaseAbstractTest() { configuration, pluginOverrides = listOf(writerPlugin, MathjaxPlugin()) ) { - renderingStage = { - _, _ -> Jsoup - .parse(writerPlugin.writer.contents["root/example/test.html"]) - .head() - .select("link, script") - .let { - assert(it.`is`("[href=$LIB_PATH], [src=$LIB_PATH]")) - } + renderingStage = { _, _ -> + val parsed = Jsoup.parse(writerPlugin.writer.contents["root/example/test.html"].also { println(it) }) + + // Ensure the MathJax CDN is loaded + assert(parsed.select("link, script").`is`("[href=$LIB_PATH], [src=$LIB_PATH]")) + + // Ensure the contents are displayed + assert(parsed.select("p").any { + println(it.text()) + it.text().contains(math) + }) } } } From 347533dcdaa105b12969eeb538f1d8db0c3bf352 Mon Sep 17 00:00:00 2001 From: Jacob Wysko Date: Sun, 20 Feb 2022 15:52:31 -0500 Subject: [PATCH 2/4] Remove print statements from MathJax test --- plugins/mathjax/src/test/kotlin/MathjaxPluginTest.kt | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/plugins/mathjax/src/test/kotlin/MathjaxPluginTest.kt b/plugins/mathjax/src/test/kotlin/MathjaxPluginTest.kt index b6302cd22e..54def470a5 100644 --- a/plugins/mathjax/src/test/kotlin/MathjaxPluginTest.kt +++ b/plugins/mathjax/src/test/kotlin/MathjaxPluginTest.kt @@ -53,9 +53,7 @@ class MathjaxPluginTest : BaseAbstractTest() { } } } - val math = """ - a^2 = b^2 + c^2 - """.trimIndent() + val math = "a^2 = b^2 + c^2" val source = """ |/src/main/kotlin/test/Test.kt @@ -81,7 +79,6 @@ class MathjaxPluginTest : BaseAbstractTest() { // Ensure the contents are displayed assert(parsed.select("p").any { - println(it.text()) it.text().contains(math) }) } From ae49d18e984e6096cb20e8077f811206423183d4 Mon Sep 17 00:00:00 2001 From: Jacob Wysko Date: Sun, 20 Feb 2022 15:59:04 -0500 Subject: [PATCH 3/4] fixup! Remove print statements from MathJax test --- plugins/mathjax/src/test/kotlin/MathjaxPluginTest.kt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/plugins/mathjax/src/test/kotlin/MathjaxPluginTest.kt b/plugins/mathjax/src/test/kotlin/MathjaxPluginTest.kt index 54def470a5..a354365bad 100644 --- a/plugins/mathjax/src/test/kotlin/MathjaxPluginTest.kt +++ b/plugins/mathjax/src/test/kotlin/MathjaxPluginTest.kt @@ -72,7 +72,7 @@ class MathjaxPluginTest : BaseAbstractTest() { pluginOverrides = listOf(writerPlugin, MathjaxPlugin()) ) { renderingStage = { _, _ -> - val parsed = Jsoup.parse(writerPlugin.writer.contents["root/example/test.html"].also { println(it) }) + val parsed = Jsoup.parse(writerPlugin.writer.contents["root/example/test.html"]) // Ensure the MathJax CDN is loaded assert(parsed.select("link, script").`is`("[href=$LIB_PATH], [src=$LIB_PATH]")) From cc5b10e366a84764e09d47c56e703f129468116a Mon Sep 17 00:00:00 2001 From: Jacob Wysko Date: Sun, 20 Feb 2022 16:29:19 -0500 Subject: [PATCH 4/4] Add changes from 0ef0fb63 --- .../documentables/DefaultPageCreator.kt | 12 ------------ plugins/mathjax/api/mathjax.api | 8 ++++++++ .../mathjax/src/main/kotlin/MathjaxPlugin.kt | 18 ++++++++++++++++++ 3 files changed, 26 insertions(+), 12 deletions(-) diff --git a/plugins/base/src/main/kotlin/translators/documentables/DefaultPageCreator.kt b/plugins/base/src/main/kotlin/translators/documentables/DefaultPageCreator.kt index a99b459b35..946d6416ce 100644 --- a/plugins/base/src/main/kotlin/translators/documentables/DefaultPageCreator.kt +++ b/plugins/base/src/main/kotlin/translators/documentables/DefaultPageCreator.kt @@ -342,18 +342,6 @@ open class DefaultPageCreator( } } } - val customTags = d.customTags - if (customTags.isNotEmpty()) { - group(styles = setOf(TextStyle.Block)) { - customTags.forEach { - group(styles = setOf(TextStyle.Block)) { - it.value.values.forEach { - comment(it.root) - } - } - } - } - } val customTags = d.customTags if (customTags.isNotEmpty()) { diff --git a/plugins/mathjax/api/mathjax.api b/plugins/mathjax/api/mathjax.api index 47612ecb78..da5caeb213 100644 --- a/plugins/mathjax/api/mathjax.api +++ b/plugins/mathjax/api/mathjax.api @@ -1,8 +1,16 @@ public final class org/jetbrains/dokka/mathjax/MathjaxPlugin : org/jetbrains/dokka/plugability/DokkaPlugin { public fun ()V + public final fun getMathjaxTagContentProvider ()Lorg/jetbrains/dokka/plugability/Extension; public final fun getTransformer ()Lorg/jetbrains/dokka/plugability/Extension; } +public final class org/jetbrains/dokka/mathjax/MathjaxTagContentProvider : org/jetbrains/dokka/base/transformers/pages/tags/CustomTagContentProvider { + public static final field INSTANCE Lorg/jetbrains/dokka/mathjax/MathjaxTagContentProvider; + public fun contentForBrief (Lorg/jetbrains/dokka/base/translators/documentables/PageContentBuilder$DocumentableContentBuilder;Lorg/jetbrains/dokka/DokkaConfiguration$DokkaSourceSet;Lorg/jetbrains/dokka/model/doc/CustomTagWrapper;)V + public fun contentForDescription (Lorg/jetbrains/dokka/base/translators/documentables/PageContentBuilder$DocumentableContentBuilder;Lorg/jetbrains/dokka/DokkaConfiguration$DokkaSourceSet;Lorg/jetbrains/dokka/model/doc/CustomTagWrapper;)V + public fun isApplicable (Lorg/jetbrains/dokka/model/doc/CustomTagWrapper;)Z +} + public final class org/jetbrains/dokka/mathjax/MathjaxTransformer : org/jetbrains/dokka/transformers/pages/PageTransformer { public static final field INSTANCE Lorg/jetbrains/dokka/mathjax/MathjaxTransformer; public fun invoke (Lorg/jetbrains/dokka/pages/RootPageNode;)Lorg/jetbrains/dokka/pages/RootPageNode; diff --git a/plugins/mathjax/src/main/kotlin/MathjaxPlugin.kt b/plugins/mathjax/src/main/kotlin/MathjaxPlugin.kt index 6a00a3daa3..89c13202a8 100644 --- a/plugins/mathjax/src/main/kotlin/MathjaxPlugin.kt +++ b/plugins/mathjax/src/main/kotlin/MathjaxPlugin.kt @@ -16,6 +16,12 @@ class MathjaxPlugin : DokkaPlugin() { val transformer by extending { CoreExtensions.pageTransformer with MathjaxTransformer } + + val mathjaxTagContentProvider by extending { + plugin().customTagContentProvider with MathjaxTagContentProvider order { + before(plugin().sinceKotlinTagContentProvider) + } + } } private const val ANNOTATION = "usesMathJax" @@ -34,3 +40,15 @@ object MathjaxTransformer : PageTransformer { .orEmpty() .any { (it as? CustomTagWrapper)?.name == ANNOTATION } } + +object MathjaxTagContentProvider : CustomTagContentProvider { + + override fun isApplicable(customTag: CustomTagWrapper) = customTag.name == ANNOTATION + + override fun DocumentableContentBuilder.contentForDescription( + sourceSet: DokkaConfiguration.DokkaSourceSet, + customTag: CustomTagWrapper + ) { + comment(customTag.root, sourceSets = setOf(sourceSet)) + } +} \ No newline at end of file