feat(bulk-cdk): Add Dokka documentation generation with Vercel deployment (#69752)

Co-authored-by: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

.github/workflows/kotlin-bulk-cdk-dokka-publish.yml

@@ -0,0 +1,148 @@
+name: Kotlin Bulk CDK Documentation
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened]
+    paths:
+      - "airbyte-cdk/bulk/**"
+  push:
+    branches:
+      - master
+    paths:
+      - "airbyte-cdk/bulk/**"
+  workflow_dispatch:
+
+# Concurrency group ensures only one deployment runs at a time
+concurrency:
+  group: kotlin-bulk-cdk-docs-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  detect-changes:
+    name: Detect Kotlin Bulk CDK Changes
+    runs-on: ubuntu-24.04
+    steps:
+      - name: Detect Changes
+        id: detect-changes
+        uses: dorny/paths-filter@v3.0.2
+        with:
+          filters: |
+            bulk-cdk:
+              - 'airbyte-cdk/bulk/**'
+
+    outputs:
+      changed: ${{ steps.detect-changes.outputs.bulk-cdk }}
+
+  build-docs:
+    name: Build Kotlin Bulk CDK Documentation
+    runs-on: ubuntu-24.04
+    needs: detect-changes
+    if: needs.detect-changes.outputs.changed == 'true'
+
+    steps:
+      - name: Checkout Repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          repository: ${{ github.event.pull_request.head.repo.full_name || github.repository }}
+          ref: ${{ github.head_ref || github.ref }}
+
+      - name: Set up Java
+        uses: actions/setup-java@v4
+        with:
+          distribution: "zulu"
+          java-version: "21"
+
+      - name: Setup Gradle
+        uses: gradle/gradle-build-action@v3
+        with:
+          gradle-version: wrapper
+
+      - name: Generate Dokka Documentation
+        run: |
+          echo "📚 Generating Dokka documentation for Kotlin Bulk CDK..."
+          ./gradlew :airbyte-cdk:bulk:dokkaHtmlMultiModule --no-daemon
+
+          echo "✅ Documentation generated successfully"
+          ls -la airbyte-cdk/bulk/build/dokka/htmlMultiModule/
+
+      - name: Upload Documentation Artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: kotlin-bulk-cdk-docs-${{ github.sha }}
+          path: airbyte-cdk/bulk/build/dokka/htmlMultiModule/
+          retention-days: 30
+
+  vercel-preview:
+    name: Deploy Docs to Vercel (Preview)
+    needs: [detect-changes, build-docs]
+    # Only deploy for non-fork PRs and master branch, and when Vercel project is configured
+    if: >
+      needs.detect-changes.outputs.changed == 'true'
+      && (
+        github.event_name == 'push'
+        || github.event.pull_request.head.repo.full_name == github.repository
+      )
+      && vars.VERCEL_KOTLIN_CDK_PROJECT_ID != ''
+    runs-on: ubuntu-24.04
+    env:
+      VERCEL_ORG_ID: ${{ secrets.VERCEL_ORG_ID }}
+      VERCEL_PROJECT_ID: ${{ vars.VERCEL_KOTLIN_CDK_PROJECT_ID }}
+
+    steps:
+      - name: Checkout Repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 1
+
+      - name: Download Documentation Artifact
+        uses: actions/download-artifact@v4
+        with:
+          name: kotlin-bulk-cdk-docs-${{ github.sha }}
+          path: docs-output/airbyte-cdk/bulk
+
+      - name: Debug - Show artifact structure
+        run: |
+          echo "📂 Artifact structure:"
+          ls -lah docs-output/airbyte-cdk/bulk
+          echo ""
+          echo "🔍 Looking for index.html:"
+          find docs-output -type f -name "index.html" -print
+          echo ""
+          echo "✅ Verifying deployment path..."
+          test -f docs-output/airbyte-cdk/bulk/index.html && echo "✅ index.html found at expected path" || echo "❌ index.html NOT found at expected path"
+
+      - name: Deploy to Vercel
+        id: deploy-vercel
+        uses: amondnet/vercel-action@v41.1.4
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          vercel-token: ${{ secrets.VERCEL_TOKEN }}
+          vercel-org-id: ${{ env.VERCEL_ORG_ID }}
+          vercel-project-id: ${{ env.VERCEL_PROJECT_ID }}
+          working-directory: docs-output
+          vercel-args: ${{ github.event_name == 'push' && '--prod' || '' }}
+          alias-domains: |
+            ${{ github.event_name == 'push' && 'bulk-cdk-docs.vercel.app' || '' }}
+
+      - name: Authenticate as GitHub App
+        if: github.event_name == 'pull_request'
+        uses: actions/create-github-app-token@v2.0.6
+        id: get-app-token
+        with:
+          owner: "airbytehq"
+          repositories: "airbyte"
+          app-id: ${{ secrets.OCTAVIA_BOT_APP_ID }}
+          private-key: ${{ secrets.OCTAVIA_BOT_PRIVATE_KEY }}
+
+      - name: Post Custom Check with Preview URL
+        if: github.event_name == 'pull_request'
+        uses: LouisBrunner/checks-action@v2.0.0
+        with:
+          name: "Kotlin Bulk CDK Docs Preview"
+          status: completed
+          conclusion: success
+          details_url: ${{ steps.deploy-vercel.outputs.preview-url }}
+          token: ${{ steps.get-app-token.outputs.token }}
+          output: |
+            {"summary":"Documentation preview deployed successfully","text":"View the Kotlin Bulk CDK documentation at the preview URL"}

airbyte-cdk/bulk/CONTRIBUTING.md

@@ -0,0 +1,64 @@
+# Contributing to the Kotlin Bulk CDK
+
+Thank you for your interest in contributing to the Airbyte Kotlin Bulk CDK!
+
+## Prerequisites
+
+- **JDK 21** (Java Development Kit) or higher
+- **Gradle** (uses the wrapper, no separate installation needed)
+
+### If you need to install Java
+
+```bash
+# Get sdkman (https://sdkman.io/)
+curl -s "https://get.sdkman.io" | bash
+source "$HOME/.sdkman/bin/sdkman-init.sh"
+
+# Verify install
+sdk version
+
+# Show available versions
+sdk list java | grep 21
+
+# Install the latest and set as default
+sdk install java 21.0.9-zulu
+sdk default java 21.0.9-zulu
+```
+
+## Generating Documentation
+
+The Kotlin Bulk CDK uses [Dokka](https://kotlinlang.org/docs/dokka-introduction.html) to generate API documentation from KDoc comments.
+
+### Generate Documentation
+
+```bash
+./gradlew :airbyte-cdk:bulk:docsGenerate
+```
+
+This generates HTML documentation in `airbyte-cdk/bulk/build/dokka/htmlMultiModule/`.
+
+### View Generated Documentation
+
+```bash
+# macOS
+open airbyte-cdk/bulk/build/dokka/htmlMultiModule/index.html
+
+# Linux
+xdg-open airbyte-cdk/bulk/build/dokka/htmlMultiModule/index.html
+```
+
+## Other Useful Commands
+
+```bash
+# Build all modules
+./gradlew :airbyte-cdk:bulk:bulkCdkBuild
+
+# Run tests
+./gradlew :airbyte-cdk:bulk:test
+```
+
+## More Information
+
+For architecture, publishing, development workflow, and other details, see the [README](README.md).
+
+For general Airbyte contribution guidelines, see the [main contributing guide](../../docs/contributing-to-airbyte/README.md).

airbyte-cdk/bulk/README.md

@@ -4,6 +4,8 @@ The Bulk CDK is the "new java CDK" that's currently incubating.
 As the name suggests, its purpose is to help develop connectors which extract or load data in bulk.
 The Bulk CDK is written in Kotlin and uses the Micronaut framework for dependency injection.
 
+**Contributing**: See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, building, testing, and documentation generation instructions.
+
 ## Structure
 
 The Bulk CDK consists of a _core_ and a bunch of _toolkits_.

airbyte-cdk/bulk/build.gradle

@@ -9,6 +9,10 @@ import org.gradle.api.tasks.TaskAction
 import org.gradle.api.tasks.options.Option
 import org.w3c.dom.Document
 
+plugins {
+    id 'org.jetbrains.dokka' version '2.0.0'
+}
+
 final var versionFile = file("version.properties")
 
 final var cdkVersion = {
@@ -22,6 +26,7 @@ allprojects {
     version = cdkVersion
     apply plugin: 'java-library'
     apply plugin: 'maven-publish'
+    apply plugin: 'org.jetbrains.dokka'
 
     group 'io.airbyte.bulk-cdk'
 
@@ -79,6 +84,67 @@ allprojects {
     }
 }
 
+// Configure Dokka for all subprojects
+subprojects {
+    tasks.withType(org.jetbrains.dokka.gradle.DokkaTask.class) {
+        dokkaSourceSets {
+            configureEach {
+                // Only document public APIs
+                includeNonPublic.set(false)
+                skipEmptyPackages.set(true)
+
+                // Report undocumented members
+                reportUndocumented.set(true)
+
+                // Add external documentation links
+                externalDocumentationLinks {
+                    create("kotlin") {
+                        url.set(uri("https://kotlinlang.org/api/latest/jvm/stdlib/").toURL())
+                        packageListUrl.set(uri("https://kotlinlang.org/api/latest/jvm/stdlib/package-list").toURL())
+                    }
+                    create("kotlinx-coroutines") {
+                        url.set(uri("https://kotlinlang.org/api/kotlinx.coroutines/").toURL())
+                    }
+                    create("micronaut") {
+                        url.set(uri("https://docs.micronaut.io/latest/api/").toURL())
+                    }
+                }
+
+                // Source links back to GitHub
+                sourceLink {
+                    localDirectory.set(file("src/main"))
+                    remoteUrl.set(uri("https://github.com/airbytehq/airbyte/tree/master/airbyte-cdk/bulk/${project.name}/src/main").toURL())
+                    remoteLineSuffix.set("#L")
+                }
+            }
+        }
+    }
+}
+
+// Configure the multi-module documentation task
+tasks.named('dokkaHtmlMultiModule') {
+    moduleName.set("Airbyte Kotlin Bulk CDK")
+    outputDirectory.set(layout.buildDirectory.dir("dokka/htmlMultiModule"))
+}
+
+// Convenience task for local development
+tasks.register('docsGenerate') {
+    group = 'documentation'
+    description = 'Generate Dokka documentation for all modules'
+    dependsOn 'dokkaHtmlMultiModule'
+
+    doLast {
+        println "Documentation generated at: ${layout.buildDirectory.dir("dokka/htmlMultiModule").get()}"
+    }
+}
+
+// Backwards-compatible alias
+tasks.register('dokkaGenerate') {
+    group = 'documentation'
+    description = 'Generate Dokka documentation for all modules (alias for docsGenerate)'
+    dependsOn 'docsGenerate'
+}
+
 tasks.register('checkBuildNumber') {
     description = "Check that the version doesn't exist"