Publish dokka reference docs

.dokka/custom-styles.css

@@ -0,0 +1,11 @@
+/* Custom styles for Customer.io Android SDK documentation */
+
+:root {
+    /* Use custom Customer.io logo instead of default Dokka logo */
+    --dokka-logo-image-url: url('../images/logo.png');
+}
+
+/* Adjust library name alignment */
+.library-name a {
+    vertical-align: middle;
+}

.github/workflows/generate-docs-manual.yml

@@ -0,0 +1,60 @@
+name: Generate Documentation (Manual)
+
+# Allows technical writers to generate docs without local Android SDK setup
+on:
+  workflow_dispatch:  # Manual trigger from GitHub Actions tab
+
+permissions:
+  contents: read
+
+jobs:
+  generate-docs:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up JDK 17
+        uses: actions/setup-java@v4
+        with:
+          java-version: '17'
+          distribution: 'temurin'
+          cache: 'gradle'
+
+      - name: Grant execute permission for gradlew
+        run: chmod +x gradlew
+
+      - name: Generate documentation
+        run: ./gradlew generateDocs
+
+      - name: Upload documentation as artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: android-sdk-docs
+          path: build/dokka/htmlMultiModule/
+          retention-days: 30
+
+      - name: Create downloadable archive
+        run: |
+          cd build/dokka/htmlMultiModule
+          zip -r ../../../android-sdk-docs.zip .
+
+      - name: Upload zip archive
+        uses: actions/upload-artifact@v4
+        with:
+          name: android-sdk-docs-zip
+          path: android-sdk-docs.zip
+          retention-days: 30
+
+      - name: Summary
+        run: |
+          echo "### 📚 Documentation Generated!" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "Download the generated documentation from the artifacts section above." >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "**Two formats available:**" >> $GITHUB_STEP_SUMMARY
+          echo "- \`android-sdk-docs\` - Uncompressed files" >> $GITHUB_STEP_SUMMARY
+          echo "- \`android-sdk-docs-zip\` - Single zip file" >> $GITHUB_STEP_SUMMARY
+
+

.github/workflows/publish-api-docs.yml

@@ -0,0 +1,172 @@
+name: Publish API Documentation
+
+# Publishes API reference documentation to GitHub Pages
+# Separate from main deployment to avoid disrupting SDK releases
+
+on:
+  push:
+    tags:
+      - '[0-9]+.[0-9]+.[0-9]+*'  # Trigger on version tags (e.g., 3.0.0, 3.1.0-beta)
+  workflow_dispatch:  # Allow manual trigger
+    inputs:
+      version:
+        description: 'Version label for docs (e.g., 3.0.0 or "latest")'
+        required: true
+        default: 'latest'
+      ref:
+        description: 'Git ref to generate docs from (branch, tag, or commit)'
+        required: false
+        default: 'main'
+
+permissions:
+  contents: write  # Required to push to gh-pages branch
+
+jobs:
+  publish-docs:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ github.event.inputs.ref || github.ref }}
+          fetch-depth: 0
+
+      - name: Set up JDK 17
+        uses: actions/setup-java@v4
+        with:
+          java-version: '17'
+          distribution: 'temurin'
+          cache: 'gradle'
+
+      - name: Grant execute permission for gradlew
+        run: chmod +x gradlew
+
+      - name: Determine version
+        id: version
+        run: |
+          if [[ "${{ github.event_name }}" == "workflow_dispatch" ]]; then
+            VERSION="${{ github.event.inputs.version }}"
+          else
+            # Extract version from tag (refs/tags/3.0.0 -> 3.0.0)
+            VERSION="${GITHUB_REF#refs/tags/}"
+          fi
+          echo "version=$VERSION" >> $GITHUB_OUTPUT
+          echo "📦 Generating docs for version: $VERSION"
+
+      - name: Generate documentation
+        run: |
+          echo "🔨 Building documentation..."
+          ./gradlew generateDocs
+
+      - name: Verify documentation generated
+        run: |
+          if [ ! -f "build/dokka/htmlMultiModule/index.html" ]; then
+            echo "❌ Documentation was not generated!"
+            exit 1
+          fi
+          echo "✅ Documentation generated successfully"
+
+      - name: Prepare docs for publishing
+        run: |
+          VERSION="${{ steps.version.outputs.version }}"
+
+          # Create directory structure
+          mkdir -p gh-pages-temp/$VERSION
+
+          # Copy generated docs to versioned directory
+          cp -r build/dokka/htmlMultiModule/* gh-pages-temp/$VERSION/
+
+          echo "✅ Documentation prepared for version: $VERSION"
+
+      - name: Checkout gh-pages branch
+        uses: actions/checkout@v4
+        with:
+          ref: gh-pages
+          path: gh-pages-repo
+          fetch-depth: 0
+
+      - name: Update gh-pages content
+        run: |
+          VERSION="${{ steps.version.outputs.version }}"
+
+          # Copy new version docs
+          mkdir -p gh-pages-repo
+          cp -r gh-pages-temp/$VERSION gh-pages-repo/
+
+          # Update "latest" symlink for stable releases only
+          if [[ "$VERSION" != *"alpha"* && "$VERSION" != *"beta"* && "$VERSION" != *"rc"* ]]; then
+            echo "📍 Updating 'latest' to point to $VERSION"
+            rm -rf gh-pages-repo/latest
+            cp -r gh-pages-temp/$VERSION gh-pages-repo/latest
+          else
+            echo "⏭️  Skipping 'latest' update for pre-release version"
+          fi
+
+          # Create simple README for the gh-pages branch
+          cat > gh-pages-repo/README.md << EOF
+          # Customer.io Android SDK - API Reference
+
+          This branch contains the published API reference documentation.
+
+          ## Available Versions
+
+          - [Latest (Stable)](latest/)
+          - [Version $VERSION]($VERSION/)
+
+          ## View Online
+
+          https://${{ github.repository_owner }}.github.io/${{ github.event.repository.name }}/latest/
+          EOF
+
+      - name: Commit and push to gh-pages
+        run: |
+          cd gh-pages-repo
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git add .
+
+          VERSION="${{ steps.version.outputs.version }}"
+          if git diff --staged --quiet; then
+            echo "📝 No changes to commit"
+          else
+            git commit -m "docs: publish API reference for version $VERSION"
+            git push origin gh-pages
+            echo "✅ Documentation published to gh-pages branch"
+          fi
+
+      - name: Create documentation archive (for release assets)
+        if: startsWith(github.ref, 'refs/tags/')
+        run: |
+          VERSION="${{ steps.version.outputs.version }}"
+          cd build/dokka/htmlMultiModule
+          tar -czf ../../../android-sdk-docs-$VERSION.tar.gz .
+          cd ../../..
+          zip -r android-sdk-docs-$VERSION.zip build/dokka/htmlMultiModule/
+
+      - name: Upload documentation as release asset
+        if: startsWith(github.ref, 'refs/tags/')
+        uses: softprops/action-gh-release@v1
+        with:
+          files: |
+            android-sdk-docs-${{ steps.version.outputs.version }}.tar.gz
+            android-sdk-docs-${{ steps.version.outputs.version }}.zip
+          fail_on_unmatched_files: false
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Summary
+        run: |
+          VERSION="${{ steps.version.outputs.version }}"
+          REPO="${{ github.repository }}"
+          OWNER="${{ github.repository_owner }}"
+
+          echo "### 📚 API Documentation Published! 🎉" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "**Version:** \`$VERSION\`" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "**📖 View Documentation:**" >> $GITHUB_STEP_SUMMARY
+          echo "- 🌟 This version: https://$OWNER.github.io/${REPO#*/}/$VERSION/" >> $GITHUB_STEP_SUMMARY
+          echo "- 📚 Latest (stable): https://$OWNER.github.io/${REPO#*/}/latest/" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "**⏱️ Availability:** Documentation will be live in ~1-2 minutes" >> $GITHUB_STEP_SUMMARY

.gitignore

@@ -84,3 +84,5 @@ lint/tmp/
 
 # Kotlin state files
 .kotlin/
+test-gh-pages/
+test-docs-output.sh

Makefile

@@ -1,5 +1,7 @@
 SHELL = /bin/sh
 
+.PHONY: lint-error-message lint-no-format format lint lint-install generate-public-api validate-public-api docs docs-clean
+
 lint-error-message:
 	echo "\n\n!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!\nLooks like there are lint errors to fix.\nRead the LINT.md document in this project to learn how to fix these problems.\n!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!"
 
@@ -35,3 +37,12 @@ generate-public-api:
 # Run kotlin binary validator
 validate-public-api:
 	./scripts/binary-validation.sh
+
+# Generate API reference documentation
+docs:
+	./gradlew generateDocs
+	@echo "\n📚 Documentation ready! Open build/dokka/htmlMultiModule/index.html in your browser"
+
+# Clean generated documentation
+docs-clean:
+	rm -rf build/dokka/

build.gradle

@@ -74,4 +74,75 @@ apiValidation {
 }
 
 apply from: "${rootDir}/scripts/publish-root.gradle"
-apply from: "${rootDir}/scripts/sdk-binary-size.gradle"
+apply from: "${rootDir}/scripts/sdk-binary-size.gradle"
+
+// Documentation generation
+tasks.register('generateDocs') {
+    dependsOn 'dokkaHtmlMultiModule'
+    group = 'documentation'
+    description = 'Generates aggregated HTML reference documentation for all SDK modules'
+
+    doLast {
+        def docsDir = file("${rootDir}/build/dokka/htmlMultiModule")
+        if (docsDir.exists()) {
+            println "\n✅ Documentation generated successfully!"
+            println "📄 Location: ${docsDir.absolutePath}"
+            println "🌐 Open: file://${docsDir.absolutePath}/index.html"
+        }
+    }
+}
+
+// Configure Dokka for better output and to exclude internal APIs
+tasks.withType(org.jetbrains.dokka.gradle.DokkaMultiModuleTask).configureEach {
+    moduleName.set("Customer.io Android SDK")
+
+    // Add custom documentation pages to navigation
+    includes.from("${rootDir}/ref-docs.md")
+
+    // Add custom logo and styling
+    // Note: Paths must be absolute for Dokka to find them during generation
+    pluginsMapConfiguration.set([
+        "org.jetbrains.dokka.base.DokkaBase": """{ 
+            "customAssets": ["${file("${rootDir}/.dokka/logo.png").absolutePath.replace('\\', '/')}"],
+            "customStyleSheets": ["${file("${rootDir}/.dokka/custom-styles.css").absolutePath.replace('\\', '/')}"]
+        }"""
+    ])
+}
+
+// Configure each module's Dokka task to exclude internal APIs
+subprojects {
+    tasks.withType(org.jetbrains.dokka.gradle.DokkaTaskPartial).configureEach {
+        dokkaSourceSets.configureEach {
+            // Only document public APIs (excludes internal, private, protected)
+            includeNonPublic.set(false)
+
+            // Skip deprecated APIs (set to false if you want to document them)
+            skipDeprecated.set(false)
+
+            // Skip empty packages
+            skipEmptyPackages.set(true)
+
+            // Suppress all packages named '*.internal.*'
+            perPackageOption {
+                matchingRegex.set(".*\\.internal.*")
+                suppress.set(true)
+            }
+
+            // Add module-specific documentation if it exists
+            def moduleDocsFile = file("${projectDir}/MODULE.md")
+            if (moduleDocsFile.exists()) {
+                includes.from(moduleDocsFile)
+            }
+
+            // Link to Android SDK documentation
+            externalDocumentationLink {
+                url.set(new URL("https://developer.android.com/reference/"))
+            }
+
+            // Link to Kotlin stdlib
+            externalDocumentationLink {
+                url.set(new URL("https://kotlinlang.org/api/latest/jvm/stdlib/"))
+            }
+        }
+    }
+}