Set up Dokka

object-Object · object-Object · commit 82c77bcdd4db · 2025-10-23T23:33:14.000-04:00
diff --git a/Common/build.gradle.kts b/Common/build.gradle.kts
@@ -1,5 +1,6 @@
 plugins {
     id("hexdebug.conventions.architectury")
+    id("hexdebug.conventions.dokka")
 }
 
 architectury {
diff --git a/Core/Common/build.gradle.kts b/Core/Common/build.gradle.kts
@@ -3,6 +3,7 @@
 
 plugins {
     id("hexdebug.conventions.architectury")
+    id("hexdebug.conventions.dokka")
 }
 
 architectury {
diff --git a/DokkaPlugin/build.gradle.kts b/DokkaPlugin/build.gradle.kts
@@ -0,0 +1,19 @@
+import org.jetbrains.kotlin.gradle.dsl.JvmTarget
+import org.jetbrains.kotlin.gradle.tasks.KotlinCompile
+
+plugins {
+    kotlin("jvm")
+}
+
+repositories {
+    mavenCentral()
+}
+
+dependencies {
+    compileOnly(libs.dokka.core)
+    implementation(libs.dokka.base)
+}
+
+tasks.withType<KotlinCompile>().configureEach {
+    compilerOptions.jvmTarget.set(JvmTarget.fromTarget(libs.versions.java.get()))
+}
diff --git a/DokkaPlugin/src/main/kotlin/gay/object/hexdebug/dokka/HexDebugDokkaPlugin.kt b/DokkaPlugin/src/main/kotlin/gay/object/hexdebug/dokka/HexDebugDokkaPlugin.kt
@@ -0,0 +1,39 @@
+package gay.`object`.hexdebug.dokka
+
+import org.jetbrains.dokka.base.DokkaBase
+import org.jetbrains.dokka.base.transformers.documentables.SuppressedByConditionDocumentableFilterTransformer
+import org.jetbrains.dokka.links.DRI
+import org.jetbrains.dokka.model.Annotations
+import org.jetbrains.dokka.model.Documentable
+import org.jetbrains.dokka.model.properties.WithExtraProperties
+import org.jetbrains.dokka.plugability.DokkaContext
+import org.jetbrains.dokka.plugability.DokkaPlugin
+import org.jetbrains.dokka.plugability.DokkaPluginApiPreview
+import org.jetbrains.dokka.plugability.PluginApiPreviewAcknowledgement
+
+// https://kotlin.github.io/dokka/2.0.0/developer_guide/plugin-development/sample-plugin-tutorial/
+
+class HexDebugDokkaPlugin : DokkaPlugin() {
+    @Suppress("unused")
+    val filterExtension by extending {
+        plugin<DokkaBase>().preMergeDocumentableTransformer providing ::HideInternalApiTransformer
+    }
+
+    @DokkaPluginApiPreview
+    override fun pluginApiPreviewAcknowledgement() = PluginApiPreviewAcknowledgement
+}
+
+class HideInternalApiTransformer(context: DokkaContext) :
+    SuppressedByConditionDocumentableFilterTransformer(context)
+{
+    override fun shouldBeSuppressed(d: Documentable): Boolean {
+        if (d !is WithExtraProperties<*>) return false
+        return d.extra
+            .allOfType<Annotations>()
+            .flatMap { it.directAnnotations.values.flatten() }
+            .any { isInternalAnnotation(it.dri) }
+    }
+
+    private fun isInternalAnnotation(dri: DRI) =
+        dri.packageName == "org.jetbrains.annotations" && dri.classNames == "ApiStatus.Internal"
+}
diff --git a/DokkaPlugin/src/main/resources/META-INF/services/org.jetbrains.dokka.plugability.DokkaPlugin b/DokkaPlugin/src/main/resources/META-INF/services/org.jetbrains.dokka.plugability.DokkaPlugin
@@ -0,0 +1 @@
+gay.object.hexdebug.dokka.HexDebugDokkaPlugin
diff --git a/Fabric/src/generated/resources/data/hexcasting/tags/action/requires_enlightenment.json b/Fabric/src/generated/resources/data/hexcasting/tags/action/requires_enlightenment.json
diff --git a/Fabric/src/generated/resources/data/hexcasting/tags/items/staves.json b/Fabric/src/generated/resources/data/hexcasting/tags/items/staves.json
diff --git a/Fabric/src/generated/resources/data/hexdebug/tags/items/focus_holder/blacklist.json b/Fabric/src/generated/resources/data/hexdebug/tags/items/focus_holder/blacklist.json
diff --git a/Fabric/src/generated/resources/data/minecraft/tags/blocks/mineable/pickaxe.json b/Fabric/src/generated/resources/data/minecraft/tags/blocks/mineable/pickaxe.json
diff --git a/build.gradle.kts b/build.gradle.kts
@@ -1,5 +1,6 @@
 plugins {
     id("hexdebug.conventions.kotlin")
+    id("hexdebug.conventions.dokka")
     alias(libs.plugins.dotenv)
 }
 
@@ -16,6 +17,12 @@ architectury {
     minecraft = minecraftVersion
 }
 
+// remember to add the other subprojects here if we add per-platform APIs in the future
+dependencies {
+    dokka(project(":Common"))
+    dokka(project(":hexdebug-core-common"))
+}
+
 tasks {
     register("viewLatestChangelog") {
         group = "documentation"
diff --git a/doc/hexdoc.toml b/doc/hexdoc.toml
@@ -39,6 +39,12 @@ mod_name = "HexDebug"
 author = "object-Object"
 show_landing_text = false
 
+[template.args.navbar]
+center = [
+    { text="API Docs", href="../api" },
+    { text="GitHub", href.variable="source_url" },
+]
+
 [extra.hexcasting]
 _pattern_regex = { "!Raw"='(?P<is_per_world>make|makePerWorld)\("(?P<name>[^"]+)",\s*HexDir\.(?P<startdir>\w+),\s*"(?P<signature>[qweasd]+)"' }
 _per_world_value = "makePerWorld"
diff --git a/doc/src/hexdoc_hexdebug/_hooks.py b/doc/src/hexdoc_hexdebug/_hooks.py
@@ -1,5 +1,10 @@
+import logging
+import shutil
 from importlib.resources import Package
+from pathlib import Path
 
+from hexdoc.cli.app import LoadedBookInfo
+from hexdoc.core import Properties
 from hexdoc.plugin import (
     HookReturn,
     LoadTaggedUnionsImpl,
@@ -8,14 +13,17 @@
     ModPluginWithBook,
     hookimpl,
 )
+from jinja2.sandbox import SandboxedEnvironment
 from typing_extensions import override
 
 import hexdoc_hexdebug
 
 from . import recipes
-from .__gradle_version__ import FULL_VERSION, MINECRAFT_VERSION, MOD_VERSION
+from .__gradle_version__ import FULL_VERSION, MINECRAFT_VERSION, MOD_ID, MOD_VERSION
 from .__version__ import PY_VERSION
 
+logger = logging.getLogger(__name__)
+
 
 class HexDebugPlugin(LoadTaggedUnionsImpl, ModPluginImpl):
     @staticmethod
@@ -33,7 +41,7 @@ class HexDebugModPlugin(ModPluginWithBook):
     @property
     @override
     def modid(self) -> str:
-        return "hexdebug"
+        return MOD_ID
 
     @property
     @override
@@ -62,3 +70,17 @@ def resource_dirs(self) -> HookReturn[Package]:
     @override
     def jinja_template_root(self) -> tuple[Package, str]:
         return hexdoc_hexdebug, "_templates"
+
+    @override
+    def pre_render_site(
+        self,
+        props: Properties,
+        books: list[LoadedBookInfo],
+        env: SandboxedEnvironment,
+        output_dir: Path,
+    ) -> None:
+        if props.modid == self.modid:
+            src = Path("build/dokka/html").resolve()
+            dst = output_dir / "api"
+            logger.info(f"Copying Dokka site from {src} to {dst}.")
+            shutil.copytree(src, dst, dirs_exist_ok=True)
diff --git a/dokka/styles/logo-styles.css b/dokka/styles/logo-styles.css
@@ -0,0 +1,5 @@
+:root {
+    --dokka-logo-image-url: url('../images/icon.png');
+    --dokka-logo-height: 28px;
+    --dokka-logo-width: 28px;
+}
diff --git a/dokka/templates/includes/page_metadata.ftl b/dokka/templates/includes/page_metadata.ftl
@@ -0,0 +1,6 @@
+<#macro display>
+    <title>${pageName} | HexDebug API</title>
+    <@template_cmd name="pathToRoot">
+    <link href="${pathToRoot}images/icon.png" rel="icon" type="image/png">
+    </@template_cmd>
+</#macro>
diff --git a/gradle/libs.versions.toml b/gradle/libs.versions.toml
@@ -58,6 +58,8 @@ pkpcpbp = "0.1.0-pre-87"
 lsp4j = "0.23.0"
 ktor = "2.3.10"
 
+dokka = "2.1.0"
+
 [bundles]
 asm = ["asm", "asm-analysis", "asm-commons", "asm-tree", "asm-util"]
 # must contain all transitive deps so they can be included in the production jar
@@ -147,9 +149,16 @@ ktor-io-jvm = { module="io.ktor:ktor-io-jvm", version.ref="ktor" }
 
 pkpcpbp = { module="at.petra-k.pkpcpbp:PKPCPBP", version.ref="pkpcpbp" }
 
+dokka-base = { module="org.jetbrains.dokka:dokka-base", version.ref="dokka" }
+dokka-core = { module="org.jetbrains.dokka:dokka-core", version.ref="dokka" }
+
+dokka-kotlinAsJava = { module="org.jetbrains.dokka:kotlin-as-java-plugin", version.ref="dokka" }
+
 [plugins]
 kotlin-jvm = { id="org.jetbrains.kotlin.jvm", version.ref="kotlin" }
 
+dokka = { id="org.jetbrains.dokka", version.ref="dokka" }
+
 architectury      = { id="architectury-plugin", version.ref="architectury-plugin" }
 architectury-loom = { id="dev.architectury.loom", version.ref="architectury-loom" }
 
diff --git a/plugins/build.gradle.kts b/plugins/build.gradle.kts
@@ -19,6 +19,7 @@ dependencies {
     // plugins
     // https://github.com/gradle/gradle/issues/15383#issuecomment-1855984127
     implementation(libs.plugins.kotlin.jvm.toLibrary())
+    implementation(libs.plugins.dokka.toLibrary())
     implementation(libs.plugins.architectury.toLibrary())
     implementation(libs.plugins.architectury.loom.toLibrary())
     implementation(libs.plugins.shadow.toLibrary())
diff --git a/plugins/src/main/kotlin/hexdebug/conventions/dokka.gradle.kts b/plugins/src/main/kotlin/hexdebug/conventions/dokka.gradle.kts
@@ -0,0 +1,50 @@
+package hexdebug.conventions
+
+import hexdebug.libs
+import org.jetbrains.dokka.gradle.engine.parameters.VisibilityModifier
+
+plugins {
+    base
+    id("org.jetbrains.dokka")
+}
+
+dependencies {
+    dokkaPlugin(project(":DokkaPlugin"))
+    dokkaPlugin(libs.dokka.kotlinAsJava)
+}
+
+dokka {
+    moduleName = base.archivesName
+    dokkaPublications.html {
+        failOnWarning = true
+    }
+    dokkaSourceSets {
+        configureEach {
+            documentedVisibilities.set(setOf(VisibilityModifier.Public, VisibilityModifier.Protected))
+            perPackageOption {
+                suppress = true
+            }
+            perPackageOption {
+                matchingRegex = """.*?\.api(\..+|$)"""
+                suppress = false
+            }
+            sourceLink {
+                val githubRepository = System.getenv("GITHUB_REPOSITORY") ?: "object-Object/HexDebug"
+                val githubRef = System.getenv("GITHUB_SHA") ?: "main"
+                val projectPath = projectDir
+                    .relativeTo(rootProject.projectDir)
+                    .toPath()
+                    .joinToString("/")
+                remoteUrl = uri("https://github.com/$githubRepository/tree/$githubRef/$projectPath")
+                remoteLineSuffix = "#L"
+            }
+        }
+    }
+    pluginsConfiguration.html {
+        templatesDir = rootProject.file("dokka/templates")
+        customStyleSheets = rootProject.fileTree("dokka/styles").matching { include("**/*.css") }
+        customAssets.from(
+            project(":Common").file("src/main/resources/icon.png"),
+        )
+    }
+}
diff --git a/plugins/src/main/kotlin/hexdebug/conventions/platform.gradle.kts b/plugins/src/main/kotlin/hexdebug/conventions/platform.gradle.kts
@@ -1,7 +1,5 @@
 package hexdebug.conventions
 
-import gradle.kotlin.dsl.accessors._a774b807f82c23abb447cf166178410f.architectury
-import gradle.kotlin.dsl.accessors._a774b807f82c23abb447cf166178410f.processIncludeJars
 import hexdebug.hexdebugProperties
 
 plugins {
diff --git a/pyproject.toml b/pyproject.toml
@@ -33,7 +33,7 @@ gradle-version-regex = { regex='^(.+?)(-.+)?$', repl='\1.{minecraftVersion}\2' }
 
 [tool.hatch.metadata.hooks.version-catalog]
 dependencies = [
-    "hexdoc>=1!0.1.0a16",
+    "hexdoc>=1!0.1.0a34",
     { package="hexdoc-hexcasting", op="~=", py-version="1.0", key="hexcasting" },
     { package="hexdoc-ioticblocks", op=">=", py-version="1.0", key="ioticblocks" },
 ]
diff --git a/settings.gradle.kts b/settings.gradle.kts
@@ -14,6 +14,7 @@ pluginManagement {
 rootProject.name = "HexDebug"
 
 include(
+    "DokkaPlugin",
     "Common",
     "Common:Mojmap",
     "Fabric",

Original file line number	Diff line number	Diff line change
`@@ -1,5 +1,6 @@`
`1`	`1`	`plugins {`
`2`	`2`	`id("hexdebug.conventions.architectury")`
	`3`	`+ id("hexdebug.conventions.dokka")`
`3`	`4`	`}`
`4`	`5`
`5`	`6`	`architectury {`
Original file line number	Diff line number	Diff line change
`@@ -3,6 +3,7 @@`
`3`	`3`
`4`	`4`	`plugins {`
`5`	`5`	`id("hexdebug.conventions.architectury")`
	`6`	`+ id("hexdebug.conventions.dokka")`
`6`	`7`	`}`
`7`	`8`
`8`	`9`	`architectury {`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	`+gay.object.hexdebug.dokka.HexDebugDokkaPlugin`