fix(build): stabilize dokka v2 generation (#477)

Author: wax911

.github/instructions/context.instructions.md

@@ -47,7 +47,7 @@ description: Use when understanding support-arch architecture, module boundaries
 
 ## Documentation Contract
 
-- Dokka is configured centrally in `buildSrc` and the root build script; CI publishes `./gradlew dokkaHtmlMultiModule` output from `dokka-docs` to the `docs` branch.
+- Dokka is configured centrally in `buildSrc` and the root build script; CI publishes `./gradlew dokkaGenerate` output from `dokka-docs` to the `docs` branch.
 - Dokka has `reportUndocumented = true`, so undocumented public APIs are a quality problem, not an optional cleanup task.
 - Packages matching `.internal` are intentionally suppressed from published docs. Do not hide consumer-facing APIs in internal packages.
 - When changing public behavior, update KDoc in the same change. Document what the API does, when to use it, and what a consumer must provide or expect.
@@ -57,4 +57,4 @@ description: Use when understanding support-arch architecture, module boundaries
 - Put abstractions in the lowest module that can own them without depending on higher-level UI code.
 - Preserve the existing legacy paging split unless the task explicitly migrates away from it.
 - Prefer shared build logic changes in `buildSrc` over copy-pasting Gradle configuration into individual modules.
-- When unsure where code belongs, start from the Dokka module page, inspect neighboring package roots, and confirm the dependency direction before editing.
+- When unsure where code belongs, start from the Dokka module page, inspect neighboring package roots, and confirm the dependency direction before editing.

.github/skills/support-arch-build-dependencies/references/build-map.md

@@ -5,7 +5,7 @@ Use this map to choose the right build file before editing.
 | Concern | Primary files | Notes |
 | --- | --- | --- |
 | Module includes | `settings.gradle.kts` | Declares every published module in the repo |
-| Root repositories and multi-module Dokka output | `build.gradle.kts` | `dokkaHtmlMultiModule` writes to `dokka-docs` |
+| Root repositories and multi-module Dokka output | `build.gradle.kts` | Root `dokkaGenerate` writes the aggregate Dokka V2 site to `dokka-docs` |
 | Shared plugin entry point | `buildSrc/.../plugin/CorePlugin.kt` | Applies Android or Kotlin plugin, Dokka, publishing, Spotless, sources, dependencies |
 | Shared plugin application | `buildSrc/.../components/ProjectPlugins.kt` | Most modules use `co.anitrend.arch` |
 | Shared Android defaults | `buildSrc/.../components/AndroidConfiguration.kt` | SDK levels, view binding, tests, compiler options, toolchain 21 |
@@ -36,4 +36,4 @@ Use this map to choose the right build file before editing.
 - Cross-module convention: `buildSrc`.
 - One module only: that module's `build.gradle.kts`.
 - Documentation generation or publish behavior: Dokka config plus workflow file.
-- Annotation surface change: update both `annotation` and `processor` when needed.
+- Annotation surface change: update both `annotation` and `processor` when needed.

.github/workflows/gradle-dokka.yml

@@ -10,6 +10,8 @@ env:
 jobs:
   gradle-dokka:
     runs-on: ubuntu-latest
+    permissions:
+      contents: write
     steps:
       - uses: actions/checkout@v6
       - uses: actions/setup-java@v5
@@ -23,10 +25,10 @@ jobs:
       - name: Grant execute permission for gradlew
         run: chmod +x gradlew
       - name: Generate docs with dokka
-        run: ./gradlew dokkaGenerate
+        run: ./gradlew --no-daemon dokkaGenerate
 
       - name: Deploy 🚀
         uses: JamesIves/github-pages-deploy-action@v4.8.0
         with:
           branch: docs # The branch the action should deploy to.
-          folder: library/build/docs/dokka # The folder the action should deploy.
+          folder: dokka-docs # The root Dokka V2 publication output.

AGENTS.md

@@ -9,7 +9,7 @@
 ## High-Signal Repo Facts
 
 - Public API docs are generated with Dokka and published to `https://anitrend.github.io/support-arch/`.
-- CI publishes docs by running `./gradlew dokkaHtmlMultiModule` on `develop` and deploying `dokka-docs` to the `docs` branch.
+- CI publishes docs by running `./gradlew dokkaGenerate` on `develop` and deploying `dokka-docs` to the `docs` branch.
 - Most modules use the shared `co.anitrend.arch` Gradle plugin from `buildSrc`.
 - Shared Android and Kotlin defaults live in `buildSrc`, not in individual module build files.
 - The pinned Java version is `.java-version = 21.0.8` and the shared toolchain is Java 21.
@@ -69,7 +69,7 @@
 ## Validation
 
 - Formatting: `./gradlew spotlessCheck` or `./gradlew spotlessApply`
-- Docs: `./gradlew dokkaHtmlMultiModule`
+- Docs: `./gradlew dokkaGenerate`
 - Tests: prefer targeted module tests before full-project runs
 - If Gradle or Java alignment is unstable, use the existing `jenv-gradle-low-ram` skill
 

build.gradle.kts

@@ -5,10 +5,32 @@ buildscript {
     }
     dependencies {
         classpath(libs.android.gradle.plugin)
+        classpath(libs.jetbrains.dokka.gradle)
         classpath(libs.jetbrains.kotlin.gradle)
     }
 }
 
+apply(plugin = "org.jetbrains.dokka")
+
+configure<org.jetbrains.dokka.gradle.DokkaExtension> {
+    moduleName.set("support-arch")
+    basePublicationsDirectory.set(layout.projectDirectory.dir("dokka-docs"))
+}
+
+dependencies {
+    add("dokka", project(":analytics"))
+    add("dokka", project(":core"))
+    add("dokka", project(":data"))
+    add("dokka", project(":domain"))
+    add("dokka", project(":extension"))
+    add("dokka", project(":paging-legacy"))
+    add("dokka", project(":recycler"))
+    add("dokka", project(":recycler-paging-legacy"))
+    add("dokka", project(":request"))
+    add("dokka", project(":theme"))
+    add("dokka", project(":ui"))
+}
+
 allprojects {
     repositories {
         google()

buildSrc/src/main/java/co/anitrend/arch/buildSrc/plugin/components/ProjectDokka.kt

@@ -59,6 +59,7 @@ private fun Project.dependenciesOfProject(): List<Modules.Module> {
 
 internal fun Project.configureDokka() = dokkaExtension().run {
     basePublicationsDirectory.set(layout.buildDirectory.dir("docs/dokka"))
+    val androidPublicationVariant = "release"
 
     // Set module name displayed in the final output
     moduleName.set(project.name)
@@ -74,7 +75,8 @@ internal fun Project.configureDokka() = dokkaExtension().run {
             //dependsOn(dependenciesOfProject().map(Modules.Module::path))
 
             // Used to remove a source set from documentation, test source sets are suppressed by default
-            suppress.set(false)
+            // Dokka V2 only supports one Android variant when debug/release share src/main roots.
+            suppress.set(!project.isKotlinLibraryGroup() && name != androidPublicationVariant)
 
             // Do not output deprecated members. Applies globally, can be overridden by packageOptions
             skipDeprecated.set(false)
@@ -156,4 +158,4 @@ internal fun Project.configureDokka() = dokkaExtension().run {
             }
         }
     }
-}
+}