Migrate to Dokka2 (#1783)

Author: geoff-powell

.github/workflows/build.yml

@@ -13,6 +13,42 @@ env:
   GRADLE_OPTS: "-Dorg.gradle.jvmargs=-Xmx4g -Dorg.gradle.daemon=false -Dkotlin.incremental=false"
 
 jobs:
+  generate-docs:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Configure JDK
+        uses: actions/setup-java@v4
+        with:
+          distribution: 'zulu'
+          java-version: 17
+
+      - name: Setup Gradle
+        uses: gradle/actions/setup-gradle@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: 3.12
+
+      - name: Prep mkdocs
+        run: .github/workflows/prepare_mkdocs.sh
+
+      - name: Build mkdocs
+        run: |
+          pip3 install -r .github/workflows/requirements.in
+          mkdocs build
+
+      - name: Upload Html Docs
+        uses: actions/upload-artifact@v4
+        with:
+          name: mkdocs-${{ github.sha }}
+          path: |
+            **/docs/
+
   build:
     strategy:
       fail-fast: false
@@ -90,7 +126,7 @@ jobs:
 
       - name: Build mkdocs
         run: |
-          pip3 install -r .github/workflows/requirements.txt
+          pip3 install -r .github/workflows/requirements.in
           mkdocs build
 
       - name: Deploy docs to website

.github/workflows/prepare_mkdocs.sh

@@ -9,7 +9,7 @@
 set -ex
 
 # Generate the API docs
-./gradlew dokkaHtml
+./gradlew dokkaGenerate
 
 # Copy in special files that GitHub wants in the project root.
 cat README.md | grep -v 'project website' > docs/index.md

.github/workflows/release.yml

@@ -54,7 +54,7 @@ jobs:
 
       - name: Build mkdocs
         run: |
-          pip3 install -r .github/workflows/requirements.txt
+          pip3 install -r .github/workflows/requirements.in
           mkdocs build
 
       - name: Deploy docs to website

.gitignore

@@ -18,6 +18,7 @@ generated
 
 # Mkdocs files
 docs/1.x
+docs/2.x
 docs/changelog.md
 docs/index.md
 site/

gradle.properties

@@ -29,4 +29,5 @@ android.suppressUnsupportedCompileSdk=UpsideDownCakePrivacySandbox
 # Signals to our own plugin that we are building within the repo.
 app.cash.paparazzi.internal=true
 
-kotlin.mpp.androidGradlePluginCompatibility.nowarn=true
+# Dokka
+org.jetbrains.dokka.experimental.gradle.pluginMode=V2Enabled

mkdocs.yml

@@ -54,6 +54,7 @@ markdown_extensions:
 nav:
   - 'Overview': index.md
   - '1.x API': 1.x/paparazzi/app.cash.paparazzi/index.html
+  - '2.x API': 2.x/paparazzi/app.cash.paparazzi/index.html
   - 'Accessibility Snapshots': accessibility.md
   - 'Change Log': changelog.md
   - 'Code of Conduct': code_of_conduct.md

paparazzi/build.gradle

@@ -1,4 +1,6 @@
 import com.android.build.gradle.internal.publishing.AndroidArtifacts
+import org.jetbrains.dokka.gradle.engine.parameters.KotlinPlatform
+import org.jetbrains.dokka.gradle.engine.parameters.VisibilityModifier
 
 apply plugin: 'org.jetbrains.kotlin.jvm'
 apply plugin: 'org.jetbrains.kotlin.plugin.compose'
@@ -74,32 +76,32 @@ dependencies {
   testImplementation libs.truth
 }
 
-tasks.named("dokkaHtml").configure {
-  outputDirectory = rootProject.file("docs/1.x")
-
-  dokkaSourceSets.named("main") {
-    configureEach {
-      reportUndocumented = false
-      skipDeprecated = true
-      jdkVersion = 8
-      includeNonPublic = false
-      skipEmptyPackages = true
-      platform = "jvm"
-
-      externalDocumentationLink {
-        url.set(java.net.URL("https://developer.android.com/reference/"))
-      }
-
-      sourceLink {
-        localDirectory.set(file("src/main/java"))
-        remoteUrl.set(java.net.URL("https://github.com/cashapp/paparazzi/tree/master/paparazzi/src/main/java"))
-        remoteLineSuffix.set("#L")
-      }
-
-      perPackageOption {
-        prefix = "app.cash.paparazzi.internal"
-        suppress = true
-      }
+dokka {
+  dokkaPublications.html {
+    outputDirectory.set(rootProject.file("docs/2.x"))
+  }
+
+  dokkaSourceSets.named("main").configure {
+    reportUndocumented = false
+    skipDeprecated = true
+    jdkVersion = libs.versions.javaTarget.get() as int
+    documentedVisibilities(VisibilityModifier.Public)
+    skipEmptyPackages = true
+    analysisPlatform = KotlinPlatform.JVM
+
+    externalDocumentationLinks.register("docs") {
+      url("https://developer.android.com/reference/")
+    }
+
+    sourceLink {
+      localDirectory.set(file("src/main/java"))
+      remoteUrl("https://github.com/cashapp/paparazzi/tree/master/paparazzi/src/main/java")
+      remoteLineSuffix.set("#L")
+    }
+
+    perPackageOption {
+      matchingRegex = /app\.cash\.paparazzi\.internal(\..*)?/
+      suppress = true
     }
   }
 }

renovate.json5

@@ -7,11 +7,11 @@
     "python": "==3.12"
   },
   "ignorePaths": [
-    ".github/workflows/requirements.txt",
+    ".github/workflows/requirements.in",
   ],
   "pip-compile": {
     "fileMatch": [
-      ".github/workflows/requirements.txt"
+      ".github/workflows/requirements.in"
     ]
   },
   packageRules: [