API Reference

.github/workflows/docs-deploy.yml

@@ -0,0 +1,52 @@
+name: Deploy Docs
+
+on:
+  push:
+    branches: [ 'main' ]
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Validate Gradle Wrapper
+        uses: gradle/wrapper-validation-action@v1
+      - uses: actions/cache@v3
+        with:
+          path: ~/.konan
+          key: ${{ runner.os }}-${{ hashFiles('**/.lock') }}
+      - name: Set up JDK 17
+        uses: actions/setup-java@v3
+        with:
+          java-version: '17'
+          distribution: 'temurin'
+      - name: Set up Gradle
+        uses: gradle/actions/setup-gradle@v4
+      - name: Build Docs
+        run: |
+          ./gradlew \
+           -PGITHUB_PUBLISH_TOKEN=${{ secrets.GITHUB_TOKEN }} \
+          dokkaGenerate
+        shell: bash
+      - name: Upload static files as artifact
+        id: deployment
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: build/dokka/html
+
+  # Deployment job
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

build.gradle.kts

@@ -1,3 +1,9 @@
+import com.sun.net.httpserver.HttpExchange
+import com.sun.net.httpserver.HttpServer
+import java.net.InetSocketAddress
+import java.net.URLDecoder
+import java.nio.file.Files
+
 plugins {
     alias(libs.plugins.jetbrainsCompose) apply false
     alias(libs.plugins.compose.compiler) apply false
@@ -16,6 +22,8 @@ plugins {
     alias(libs.plugins.kotlinter) apply false
     alias(libs.plugins.keeper) apply false
     alias(libs.plugins.kotlin.atomicfu) apply false
+    id("org.jetbrains.dokka") version libs.versions.dokkaBase
+    id("dokka-convention")
 }
 
 allprojects {
@@ -54,6 +62,56 @@ subprojects {
     version = LIBRARY_VERSION
 }
 
-tasks.register<Delete>("clean") {
+tasks.getByName<Delete>("clean") {
     delete(rootProject.layout.buildDirectory)
 }
+
+// Merges individual module docs into a single HTML output
+dependencies {
+    dokka(project(":core:"))
+    dokka(project(":connectors:supabase"))
+}
+
+dokka {
+    moduleName.set("PowerSync Kotlin")
+}
+
+// Serve the generated Dokka documentation using a simple HTTP server
+// File changes are not watched here
+tasks.register("serveDokka") {
+    dependsOn("dokkaGenerate")
+    doLast {
+        val server = HttpServer.create(InetSocketAddress(0), 0)
+        val root = file("build/dokka/html")
+
+        val handler =
+            com.sun.net.httpserver.HttpHandler { exchange: HttpExchange ->
+                val rawPath = exchange.requestURI.path
+                val cleanPath = URLDecoder.decode(rawPath.removePrefix("/"), "UTF-8")
+                val requestedFile = File(root, cleanPath)
+
+                val file =
+                    when {
+                        requestedFile.exists() && !requestedFile.isDirectory -> requestedFile
+                        else -> File(root, "index.html") // fallback
+                    }
+
+                val contentType =
+                    Files.probeContentType(file.toPath()) ?: "application/octet-stream"
+                val bytes = file.readBytes()
+                exchange.responseHeaders.add("Content-Type", contentType)
+                exchange.sendResponseHeaders(200, bytes.size.toLong())
+                exchange.responseBody.use { it.write(bytes) }
+            }
+
+        server.createContext("/", handler)
+        server.executor = null
+        server.start()
+
+        println("📘 Serving Dokka docs at http://localhost:${server.address.port}/")
+        println("Press Ctrl+C to stop.")
+
+        // Keep the task alive
+        Thread.currentThread().join()
+    }
+}

connectors/supabase/build.gradle.kts

@@ -8,6 +8,7 @@ plugins {
     alias(libs.plugins.androidLibrary)
     alias(libs.plugins.kotlinter)
     id("com.powersync.plugins.sonatype")
+    id("dokka-convention")
 }
 
 kotlin {
@@ -51,3 +52,7 @@ android {
 }
 
 setupGithubRepository()
+
+dokka {
+    moduleName.set("PowerSync Supabase Connector")
+}

core/build.gradle.kts

@@ -19,6 +19,7 @@ plugins {
     id("com.powersync.plugins.sharedbuild")
     alias(libs.plugins.mokkery)
     alias(libs.plugins.kotlin.atomicfu)
+    id("dokka-convention")
 }
 
 val binariesFolder = project.layout.buildDirectory.dir("binaries/desktop")
@@ -295,3 +296,7 @@ tasks.withType<KotlinTest> {
     }
 }
 setupGithubRepository()
+
+dokka {
+    moduleName.set("PowerSync Core")
+}

core/src/commonMain/kotlin/com/powersync/db/schema/Schema.kt

@@ -2,15 +2,30 @@ package com.powersync.db.schema
 
 import kotlinx.serialization.Serializable
 
+/**
+ * The schema used by the database.
+ *
+ * The implementation uses the schema as a "VIEW" on top of JSON data.
+ * No migrations are required on the client.
+ */
 public data class Schema(
     val tables: List<Table>,
 ) {
     init {
         validate()
     }
 
+    /**
+     * Secondary constructor to create a schema with a variable number of tables.
+     */
     public constructor(vararg tables: Table) : this(tables.asList())
 
+    /**
+     * Validates the schema by ensuring there are no duplicate table names
+     * and that each table is valid.
+     *
+     * @throws AssertionError if duplicate table names are found.
+     */
     public fun validate() {
         val tableNames = mutableSetOf<String>()
         tables.forEach { table ->

docs/assets/doc-styles.css

@@ -0,0 +1,34 @@
+:root {
+    --dokka-logo-image-url: url('../images/powersync-logo.png');
+}
+
+.footer-container {
+    display: flex;
+    flex-wrap: wrap;
+    justify-content: center;
+    gap: 8px;
+    margin-top: auto;
+    box-sizing: border-box;
+    background-color: var(--footer-background);
+    color: var(--footer-font-color);
+}
+
+.footer-title {
+    margin-bottom: 8px;
+}
+
+.footer-column {
+    flex: 1 1 0; 
+    align-items: center;
+    text-align: center;
+    min-width: 300px; 
+    padding: 8px;
+}
+
+.footer-icon-row {
+    display: flex;
+    justify-content: center;
+    align-items: center;
+    gap: 8px;
+    flex-wrap: wrap;
+  }

docs/assets/dokka-templates/includes/footer.ftl

@@ -0,0 +1,48 @@
+<#macro display>
+<@template_cmd name="pathToRoot">
+<div style="margin-top:auto">
+<div class="footer-container">
+  <div class="footer-column">
+    <strong class="footer-title">Community</strong>
+    <div class="footer-icon-row">
+      <a href="https://discord.gg/powersync" target="_blank">
+        <img src="./${pathToRoot}/images/discord.svg" loading="lazy" alt="Discord" height="24">
+      </a>
+      <a href="https://twitter.com/powersync_" target="_blank">
+        <img src="./${pathToRoot}/images/x.svg" loading="lazy" alt="Twitter" height="20">
+      </a>
+      <a href="https://www.youtube.com/@powersync_" target="_blank">
+        <img src="./${pathToRoot}/images/youtube.svg" loading="lazy" alt="YouTube" width="32" height="28">
+      </a>
+      <a href="https://www.linkedin.com/showcase/journeyapps-powersync/" target="_blank">
+        <img src="./${pathToRoot}/images/linkedin.svg" loading="lazy" alt="LinkedIn" height="24">
+      </a>
+    </div>
+  </div>
+
+  <div class="footer-column">
+    <strong class="footer-title">More</strong>
+    <div class="footer-icon-row">
+      <a href="https://github.com/powersync-ja" target="_blank">
+        <img src="./${pathToRoot}/images/github.svg" loading="lazy" alt="GitHub" height="24">
+      </a>
+      <a href="https://www.powersync.com/" target="_blank">
+        <img src="./${pathToRoot}/images/web.svg" loading="lazy" alt="Website" height="30">
+      </a>
+    </div>
+  </div>
+</div>
+
+<div class="footer-container">
+    <span>© 2025 Journey Mobile, Inc.</span>
+    <span class="pull-right">
+        <span>Generated by </span>
+            <a class="footer--link footer--link_external" href="https://github.com/Kotlin/dokka">
+                <span>dokka</span>
+            </a>
+    </span>
+</div>
+
+</div>
+</@template_cmd>
+</#macro>

gradle.properties

@@ -31,3 +31,5 @@ POM_DEVELOPER_ID=powersync
 POM_DEVELOPER_NAME=PowerSync SDK Team
 POM_DEVELOPER_URL=https://powersync.com/
 [email protected]
+#Dokka
+org.jetbrains.dokka.experimental.gradle.pluginMode=V2Enabled

gradle/libs.versions.toml

@@ -4,6 +4,7 @@ android-minSdk = "24"
 android-targetSdk = "35"
 android-compileSdk = "35"
 configurationAnnotations = "0.9.5"
+dokkaBase = "2.0.0"
 gradleDownloadTask = "5.5.0"
 java = "17"
 idea = "243.22562.218" # Meerkat | 2024.3.1 (see https://plugins.jetbrains.com/docs/intellij/android-studio-releases-list.html)
@@ -56,6 +57,7 @@ junitVersion = "1.2.1"
 
 [libraries]
 configuration-annotations = { module = "co.touchlab.skie:configuration-annotations", version.ref = "configurationAnnotations" }
+dokka-gradle-plugin = { module = "org.jetbrains.dokka:dokka-gradle-plugin", version.ref = "dokkaBase" }
 gradle-download-task = { module = "de.undercouch:gradle-download-task", version.ref = "gradleDownloadTask" }
 kermit = { module = "co.touchlab:kermit", version.ref = "kermit" }
 kermit-test = { module = "co.touchlab:kermit-test", version.ref = "kermit" }

plugins/build-plugin/build.gradle.kts

@@ -3,8 +3,8 @@ plugins {
 }
 
 gradlePlugin {
-      // Define the plugin
-    val sonatypeCentralUpload by plugins.creating {
+    // Define the plugin
+    val sharedBuild by plugins.creating {
         id = "com.powersync.plugins.sharedbuild"
         implementationClass = "com.powersync.plugins.sharedbuild.SharedBuildPlugin"
     }
@@ -13,4 +13,5 @@ gradlePlugin {
 dependencies {
     implementation(libs.gradle.download.task)
     implementation(libs.kotlin.gradle.plugin)
+    implementation(libs.dokka.gradle.plugin)
 }