ci: unify GitHub Pages deployment (Dokka + docs site) (#5523)

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

.github/workflows/docs-deploy.yml

@@ -1,30 +1,38 @@
-name: Docs Deploy (Beta)
+name: Deploy Documentation
 
 on:
   push:
     branches: [main]
     paths:
+      # Dokka sources (KDoc in source files)
+      - 'androidApp/src/**'
+      - 'core/**/src/**'
+      - 'feature/**/src/**'
+      - 'desktopApp/src/**'
+      # Docs site sources
       - 'docs/**'
       - 'feature/docs/**'
-      - 'build-logic/convention/src/main/kotlin/org/meshtastic/buildlogic/DocsTasks.kt'
+      # Build infrastructure
+      - 'build-logic/**'
+      - 'build.gradle.kts'
+      - 'settings.gradle.kts'
       - '.github/workflows/docs-deploy.yml'
 
+  workflow_dispatch:
+
 permissions:
   contents: read
   pages: write
   id-token: write
 
 concurrency:
-  group: docs-deploy
+  group: pages
   cancel-in-progress: true
 
 jobs:
-  build-and-deploy:
+  build:
+    if: github.repository == 'meshtastic/Meshtastic-Android'
     runs-on: ubuntu-24.04
-    environment:
-      name: github-pages
-      url: ${{ steps.deployment.outputs.page_url }}
-
     steps:
       - name: Checkout
         uses: actions/checkout@v6
@@ -32,31 +40,35 @@ jobs:
           submodules: true
           fetch-depth: 0
 
-      - name: Set up JDK 21
-        uses: actions/setup-java@v5
+      - name: Gradle Setup
+        uses: ./.github/actions/gradle-setup
         with:
-          java-version: '21'
-          distribution: 'temurin'
+          gradle_encryption_key: ${{ secrets.GRADLE_ENCRYPTION_KEY }}
 
-      - name: Setup Gradle
-        uses: gradle/actions/setup-gradle@v6
-        with:
-          cache-read-only: false
+      - name: Build Dokka HTML documentation
+        run: ./gradlew dokkaGeneratePublicationHtml --no-configuration-cache
 
-      - name: Generate Docs Bundle
-        run: ./gradlew generateDocsBundle -Pdocs.channel=beta -Pci=true
+      - name: Generate Docs Site
+        run: ./gradlew generateDocsBundle validateDocsBundle publishDocsSite -Pdocs.channel=root -Pci=true
 
-      - name: Validate Docs Bundle
-        run: ./gradlew validateDocsBundle -Pdocs.channel=beta -Pci=true
-
-      - name: Generate Site Artifact
-        run: ./gradlew publishDocsSite -Pdocs.channel=beta -Pci=true
+      - name: Assemble Pages artifact
+        run: |
+          # Copy Dokka output into _site/api/
+          cp -r build/dokka/html build/_site/api
 
       - name: Upload Pages Artifact
         uses: actions/upload-pages-artifact@v5
         with:
           path: build/_site/
 
+  deploy:
+    if: github.repository == 'meshtastic/Meshtastic-Android'
+    needs: build
+    runs-on: ubuntu-24.04-arm
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
       - name: Deploy to GitHub Pages
         id: deployment
         uses: actions/deploy-pages@v5

.github/workflows/docs-release.yml

@@ -7,21 +7,18 @@ on:
       - '!v*-*'
 
 permissions:
-  contents: write
+  contents: read
   pages: write
   id-token: write
 
 concurrency:
-  group: docs-release
+  group: pages
   cancel-in-progress: false
 
 jobs:
-  release-docs:
+  build:
+    if: github.repository == 'meshtastic/Meshtastic-Android'
     runs-on: ubuntu-24.04
-    environment:
-      name: github-pages
-      url: ${{ steps.deployment.outputs.page_url }}
-
     steps:
       - name: Checkout
         uses: actions/checkout@v6
@@ -36,47 +33,43 @@ jobs:
           echo "version=$TAG" >> $GITHUB_OUTPUT
           echo "Deploying docs for version: $TAG"
 
-      - name: Set up JDK 21
-        uses: actions/setup-java@v5
+      - name: Gradle Setup
+        uses: ./.github/actions/gradle-setup
         with:
-          java-version: '21'
-          distribution: 'temurin'
+          gradle_encryption_key: ${{ secrets.GRADLE_ENCRYPTION_KEY }}
 
-      - name: Setup Gradle
-        uses: gradle/actions/setup-gradle@v6
-        with:
-          cache-read-only: true
+      # Build root docs site (/ on Pages)
+      - name: Build Root Docs Site
+        run: ./gradlew generateDocsBundle publishDocsSite -Pdocs.channel=root -Pci=true
 
-      - name: Generate Docs Bundle
-        run: ./gradlew generateDocsBundle -Pdocs.channel=release -Pdocs.version=${{ steps.version.outputs.version }} -Pci=true
+      # Build versioned docs (/vX.Y.Z/ on Pages)
+      - name: Build Versioned Docs
+        run: ./gradlew generateDocsBundle publishDocsSite -Pdocs.channel=release -Pdocs.version=${{ steps.version.outputs.version }} -Pci=true
 
-      - name: Validate Docs Bundle
-        run: ./gradlew validateDocsBundle -Pdocs.version=${{ steps.version.outputs.version }} -Pci=true
+      # Build Dokka API reference (/api/ on Pages)
+      - name: Build Dokka HTML documentation
+        run: ./gradlew dokkaGeneratePublicationHtml --no-configuration-cache
 
-      - name: Generate Site Artifact
-        run: ./gradlew publishDocsSite -Pdocs.channel=release -Pdocs.version=${{ steps.version.outputs.version }} -Pci=true
-
-      - name: Update Versions Manifest
+      - name: Assemble Pages artifact
         run: |
-          VERSION=${{ steps.version.outputs.version }}
-          # Prepend new version entry to versions.yml
-          cat <<EOF > /tmp/new_version.yml
-          - name: "$VERSION"
-            url: /v$VERSION/
-            prerelease: false
-            current: true
-          EOF
-          # Mark existing entries as not current
-          sed -i 's/current: true/current: false/' docs/_data/versions.yml
-          # Prepend new entry
-          cat /tmp/new_version.yml docs/_data/versions.yml > /tmp/versions_merged.yml
-          mv /tmp/versions_merged.yml docs/_data/versions.yml
+          # Root site is already at build/_site/ from the root channel build.
+          # Versioned docs are at build/_site/v{version}/ from the release channel build.
+          # Add Dokka at /api/
+          cp -r build/dokka/html build/_site/api
 
       - name: Upload Pages Artifact
         uses: actions/upload-pages-artifact@v5
         with:
           path: build/_site/
 
+  deploy:
+    if: github.repository == 'meshtastic/Meshtastic-Android'
+    needs: build
+    runs-on: ubuntu-24.04-arm
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
       - name: Deploy to GitHub Pages
         id: deployment
         uses: actions/deploy-pages@v5

.github/workflows/docs.yml

@@ -1,83 +0,0 @@
-# This workflow builds and deploys the Dokka documentation to GitHub Pages.
-
-name: Deploy Documentation
-
-on:
-  push:
-    branches:
-      - main
-    paths:
-      # Only rebuild docs when source code changes (Dokka generates from KDoc)
-      - 'androidApp/src/**'
-      - 'core/**/src/**'
-      - 'feature/**/src/**'
-      - 'desktopApp/src/**'
-      - 'build-logic/**'
-      - 'build.gradle.kts'
-      - 'settings.gradle.kts'
-      - '.github/workflows/docs.yml'
-
-  # Allows you to run this workflow manually from the Actions tab
-  workflow_dispatch:
-    inputs:
-      ref:
-        description: 'The branch, tag or SHA to checkout'
-        required: false
-        type: string
-  
-  # Allow this workflow to be called from other workflows
-  workflow_call:
-    inputs:
-      ref:
-        description: 'The branch, tag or SHA to checkout'
-        required: false
-        type: string
-
-# 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; cancel queued runs since only the latest
-# main state matters for documentation.
-concurrency:
-  group: "pages"
-  cancel-in-progress: true
-
-jobs:
-  build-docs:
-    if: github.repository == 'meshtastic/Meshtastic-Android'
-    runs-on: ubuntu-24.04
-    steps:
-      - name: Checkout code
-        uses: actions/checkout@v6
-        with:
-          fetch-depth: 0
-          submodules: 'recursive'
-          ref: ${{ inputs.ref || '' }}
-
-      - name: Gradle Setup
-        uses: ./.github/actions/gradle-setup
-        with:
-          gradle_encryption_key: ${{ secrets.GRADLE_ENCRYPTION_KEY }}
-
-      - name: Build Dokka HTML documentation
-        run: ./gradlew dokkaGeneratePublicationHtml --no-configuration-cache
-
-      - name: Upload artifact
-        uses: actions/upload-pages-artifact@v5
-        with:
-          path: build/dokka/html
-
-  deploy:
-    if: github.repository == 'meshtastic/Meshtastic-Android'
-    environment:
-      name: github-pages
-      url: ${{ steps.deployment.outputs.page_url }}
-    runs-on: ubuntu-24.04-arm
-    needs: build-docs
-    steps:
-      - name: Deploy to GitHub Pages
-        id: deployment
-        uses: actions/deploy-pages@v5