Render PlantUML diagrams for Dokka

Author: object-Object

Common/dokka.md

@@ -0,0 +1 @@
+# Module hexdebug-common

Core/Common/dokka.md

@@ -0,0 +1,9 @@
+# Module hexdebug-core-common
+
+## Debug API sequence diagrams
+
+<img src="../images/plantuml/debug_api/initialization.png" alt="PlantUML sequence diagram for initialization." />
+<img src="../images/plantuml/debug_api/nested.png" alt="PlantUML sequence diagram for nested debugging." />
+<img src="../images/plantuml/debug_api/stepping.png" alt="PlantUML sequence diagram for stepping." />
+<img src="../images/plantuml/debug_api/stopping.png" alt="PlantUML sequence diagram for stopping." />
+<img src="../images/plantuml/debug_api/terminating.png" alt="PlantUML sequence diagram for terminating." />

build.gradle.kts

@@ -1,3 +1,5 @@
+import kotlin.script.experimental.jvm.util.classpathFromClass
+
 plugins {
     id("hexdebug.conventions.kotlin")
     id("hexdebug.conventions.dokka")
@@ -38,3 +40,36 @@ tasks {
         dependsOn(":Fabric:runDatagen")
     }
 }
+
+val copyPlantUml by tasks.registering(Sync::class) {
+    group = "plantuml"
+
+    from("plantuml")
+    into("build/plantuml")
+}
+
+val renderPlantUml by tasks.registering(JavaExec::class) {
+    group = "plantuml"
+
+    val outputDir = copyPlantUml.get().destinationDir
+
+    inputs.files(copyPlantUml)
+    outputs.dir(outputDir)
+
+    classpath = files(classpathFromClass<net.sourceforge.plantuml.Run>())
+    args(
+        "${outputDir}/**/*.puml",
+        "--format", "png",
+        "--define", "PLANTUML_LIMIT_SIZE=8192",
+        "--skinparam", "dpi=300",
+        "--exclude", "**/_*",
+        "--exclude", "${outputDir}/utils/**",
+        "--exclude", "${outputDir}/continuations.puml", // broken?
+    )
+}
+
+dokka {
+    pluginsConfiguration.html {
+        customAssets.from(renderPlantUml)
+    }
+}

gradle/libs.versions.toml

@@ -59,6 +59,7 @@ lsp4j = "0.23.0"
 ktor = "2.3.10"
 
 dokka = "2.1.0"
+plantuml = "1.2025.10"
 
 [bundles]
 asm = ["asm", "asm-analysis", "asm-commons", "asm-tree", "asm-util"]
@@ -154,6 +155,8 @@ dokka-core = { module="org.jetbrains.dokka:dokka-core", version.ref="dokka" }
 
 dokka-kotlinAsJava = { module="org.jetbrains.dokka:kotlin-as-java-plugin", version.ref="dokka" }
 
+plantuml = { module="net.sourceforge.plantuml:plantuml", version.ref="plantuml" }
+
 [plugins]
 kotlin-jvm = { id="org.jetbrains.kotlin.jvm", version.ref="kotlin" }
 

plugins/build.gradle.kts

@@ -27,6 +27,7 @@ dependencies {
 
     // libraries used by script plugins
     implementation(libs.pkpcpbp)
+    implementation(libs.plantuml)
 
     // https://stackoverflow.com/a/70878181
     // https://github.com/gradle/gradle/issues/15383

plugins/src/main/kotlin/hexdebug/conventions/dokka.gradle.kts

@@ -20,7 +20,13 @@ dokka {
     }
     dokkaSourceSets {
         configureEach {
-            documentedVisibilities.set(setOf(VisibilityModifier.Public, VisibilityModifier.Protected))
+            file("dokka.md")
+                .takeIf { it.exists() }
+                ?.let { includes.from(it) }
+            documentedVisibilities.addAll(
+                VisibilityModifier.Public,
+                VisibilityModifier.Protected,
+            )
             perPackageOption {
                 suppress = true
             }