Fix MathJax rendering bug (#2342)

* Fix MathJax rendering bug (#2175) Fix a bug where using the `@usesMathJax` custom tag would cause the documentation to fail to render.
Kotlin · Apr 1, 2022 · 3384d34 · 3384d34
1 parent b6d555b
commit 3384d34
Show file tree

Hide file tree

Showing 3 changed files with 39 additions and 11 deletions.
diff --git 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 <init> ()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
@@ -16,6 +16,12 @@ class MathjaxPlugin : DokkaPlugin() {
     val transformer by extending {
         CoreExtensions.pageTransformer with MathjaxTransformer
     }
+
+    val mathjaxTagContentProvider by extending {
+        plugin<DokkaBase>().customTagContentProvider with MathjaxTagContentProvider order {
+            before(plugin<DokkaBase>().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))
+    }
+}
diff --git a/plugins/mathjax/src/test/kotlin/MathjaxPluginTest.kt b/plugins/mathjax/src/test/kotlin/MathjaxPluginTest.kt
@@ -53,15 +53,15 @@ class MathjaxPluginTest : BaseAbstractTest() {
                 }
             }
         }
+        val math = "a^2 = b^2 + c^2"
         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 +71,16 @@ 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"])
+
+                // 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 {
+                    it.text().contains(math)
+                })
             }
         }
     }