From e490b036bee511e55f220d4b77a66d616736c987 Mon Sep 17 00:00:00 2001
From: James Rich <2199651+jamesarich@users.noreply.github.com>
Date: Mon, 8 Sep 2025 18:31:53 -0500
Subject: [PATCH] ci: add Dokka for kdoc documentation generation and
 deployment (#3024)

Signed-off-by: James Rich <2199651+jamesarich@users.noreply.github.com>
---
 .github/workflows/docs.yml | 63 ++++++++++++++++++++++++++++++++++++++
 README.md                  | 17 ++++++++++
 app/build.gradle.kts       |  6 ++++
 build.gradle.kts           |  1 +
 gradle/libs.versions.toml  |  2 ++
 network/build.gradle.kts   |  1 +
 6 files changed, 90 insertions(+)
 create mode 100644 .github/workflows/docs.yml

diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
new file mode 100644
index 000000000..22a0998d2
--- /dev/null
+++ b/.github/workflows/docs.yml
@@ -0,0 +1,63 @@
+# This workflow builds and deploys the Dokka documentation to GitHub Pages.
+
+name: Deploy Documentation
+
+on:
+  # Runs on pushes targeting the default branch
+  push:
+    branches: ["main"]
+
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
+# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  build-docs:
+    if: github.repository == 'meshtastic/Meshtastic-Android'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v5
+        with:
+          fetch-depth: 0
+          submodules: 'recursive'
+
+      - name: Set up JDK 21
+        uses: actions/setup-java@v5
+        with:
+          java-version: '21'
+          distribution: 'jetbrains'
+
+      - name: Setup Gradle
+        uses: gradle/actions/setup-gradle@v4
+
+      - name: Build Dokka HTML documentation
+        run: ./gradlew :app:dokkaHtml
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: app/build/dokka
+
+  deploy:
+    if: github.repository == 'meshtastic/Meshtastic-Android'
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build-docs
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4
diff --git a/README.md b/README.md
index 6c774608f..dfeb79a23 100644
--- a/README.md
+++ b/README.md
@@ -38,6 +38,23 @@ width="24%">](https://play.google.com/store/apps/details?id=com.geeksville.mesh&
 The play store is the last to update of these options, but if you want to join the Play Store testing program go to [this URL](https://play.google.com/apps/testing/com.geeksville.mesh) and opt-in to become a tester.
 If you encounter any problems or have questions, [ask us on the discord](https://discord.gg/meshtastic), [create an issue](https://github.com/meshtastic/Meshtastic-Android/issues), or [post in the forum](https://github.com/orgs/meshtastic/discussions) and we'll help as we can.
 
+## Documentation
+
+The project's documentation is generated with [Dokka](https://kotlinlang.org/docs/dokka-introduction.html) and hosted on GitHub Pages. It is automatically updated on every push to the `main` branch.
+
+[**View Documentation**](https://meshtastic.github.io/Meshtastic-Android/)
+
+### Generating Locally
+
+You can generate the documentation locally to preview your changes.
+
+1.  **Run the Dokka task:**
+    ```bash
+    ./gradlew :app:dokkaHtml
+    ```
+2.  **View the output:**
+    The generated HTML files will be located in the `app/build/dokka/html` directory. You can open the `index.html` file in your browser to view the documentation.
+
 ## Translations
 
 You can help translate the app into your native language using [Crowdin](https://crowdin.meshtastic.org/android).
diff --git a/app/build.gradle.kts b/app/build.gradle.kts
index e8faff6df..e1ecee811 100644
--- a/app/build.gradle.kts
+++ b/app/build.gradle.kts
@@ -32,6 +32,7 @@ plugins {
     alias(libs.plugins.datadog)
     alias(libs.plugins.secrets)
     alias(libs.plugins.spotless)
+    alias(libs.plugins.dokka)
 }
 
 val keystorePropertiesFile = rootProject.file("keystore.properties")
@@ -348,3 +349,8 @@ spotless {
         ktlint("1.7.1").setEditorConfigPath("../config/spotless/.editorconfig")
     }
 }
+
+tasks.withType<org.jetbrains.dokka.gradle.DokkaTask>().configureEach {
+    moduleName.set("Meshtastic App")
+    outputDirectory.set(file("build/dokka"))
+}
diff --git a/build.gradle.kts b/build.gradle.kts
index 2906bd24e..8ba691d94 100644
--- a/build.gradle.kts
+++ b/build.gradle.kts
@@ -30,6 +30,7 @@ plugins {
     alias(libs.plugins.kotlin.serialization) apply false
     alias(libs.plugins.protobuf) apply false
     alias(libs.plugins.secrets) apply false
+    alias(libs.plugins.dokka) apply false
 }
 
 tasks.register<Delete>("clean") {
diff --git a/gradle/libs.versions.toml b/gradle/libs.versions.toml
index 9f93b1da6..5575fbf96 100644
--- a/gradle/libs.versions.toml
+++ b/gradle/libs.versions.toml
@@ -55,6 +55,7 @@ work-runtime-ktx = "2.10.3"
 zxing-android-embedded = "4.3.0"
 zxing-core = "3.5.3"
 spotless = "7.2.1"
+dokka = "2.0.0"
 
 [libraries]
 accompanist-permissions = { module = "com.google.accompanist:accompanist-permissions", version.ref = "accompanistPermissions" }
@@ -217,6 +218,7 @@ android-library = { id = "com.android.library", version.ref = "agp" }
 compose = { id = "org.jetbrains.kotlin.plugin.compose", version.ref = "kotlin" }
 datadog = { id = "com.datadoghq.dd-sdk-android-gradle-plugin", version.ref = "dd-sdk-android-gradle-plugin" }
 detekt = { id = "io.gitlab.arturbosch.detekt", version.ref = "detekt" }
+dokka = { id = "org.jetbrains.dokka", version.ref = "dokka" }
 devtools-ksp = { id = "com.google.devtools.ksp", version.ref = "devtools-ksp" }
 firebase-crashlytics = { id = "com.google.firebase.crashlytics" , version.ref = "crashlytics" }
 google-services = { id = "com.google.gms.google-services", version.ref = "google-services" }
diff --git a/network/build.gradle.kts b/network/build.gradle.kts
index d35cae064..392b3420a 100644
--- a/network/build.gradle.kts
+++ b/network/build.gradle.kts
@@ -24,6 +24,7 @@ plugins {
     alias(libs.plugins.devtools.ksp)
     alias(libs.plugins.detekt)
     id("kotlinx-serialization")
+    alias(libs.plugins.dokka)
 }
 
 android {