Skip to content

Commit 4ad8c0c

Browse files
stevensJourneystevensJourney
authored
API Reference (#163)
1 parent 16a79c5 commit 4ad8c0c

File tree

24 files changed

+336
-11
lines changed

24 files changed

+336
-11
lines changed

‎.github/workflows/docs-deploy.yml

+52
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
name: Deploy Docs
2+
3+
on:
4+
push:
5+
branches: [ 'main' ]
6+
7+
permissions:
8+
contents: read
9+
pages: write
10+
id-token: write
11+
12+
jobs:
13+
build:
14+
runs-on: ubuntu-latest
15+
steps:
16+
- uses: actions/checkout@v4
17+
- name: Validate Gradle Wrapper
18+
uses: gradle/wrapper-validation-action@v1
19+
- uses: actions/cache@v3
20+
with:
21+
path: ~/.konan
22+
key: ${{ runner.os }}-${{ hashFiles('**/.lock') }}
23+
- name: Set up JDK 17
24+
uses: actions/setup-java@v3
25+
with:
26+
java-version: '17'
27+
distribution: 'temurin'
28+
- name: Set up Gradle
29+
uses: gradle/actions/setup-gradle@v4
30+
- name: Build Docs
31+
run: |
32+
./gradlew \
33+
-PGITHUB_PUBLISH_TOKEN=${{ secrets.GITHUB_TOKEN }} \
34+
dokkaGenerate
35+
shell: bash
36+
- name: Upload static files as artifact
37+
id: deployment
38+
uses: actions/upload-pages-artifact@v3
39+
with:
40+
path: build/dokka/html
41+
42+
# Deployment job
43+
deploy:
44+
environment:
45+
name: github-pages
46+
url: ${{ steps.deployment.outputs.page_url }}
47+
runs-on: ubuntu-latest
48+
needs: build
49+
steps:
50+
- name: Deploy to GitHub Pages
51+
id: deployment
52+
uses: actions/deploy-pages@v4

‎build.gradle.kts

+61-1
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,9 @@
1+
import com.sun.net.httpserver.HttpExchange
2+
import com.sun.net.httpserver.HttpServer
3+
import java.net.InetSocketAddress
4+
import java.net.URLDecoder
5+
import java.nio.file.Files
6+
17
plugins {
28
alias(libs.plugins.jetbrainsCompose) apply false
39
alias(libs.plugins.compose.compiler) apply false
@@ -16,6 +22,8 @@ plugins {
1622
alias(libs.plugins.kotlinter) apply false
1723
alias(libs.plugins.keeper) apply false
1824
alias(libs.plugins.kotlin.atomicfu) apply false
25+
id("org.jetbrains.dokka") version libs.versions.dokkaBase
26+
id("dokka-convention")
1927
}
2028

2129
allprojects {
@@ -54,6 +62,58 @@ subprojects {
5462
version = LIBRARY_VERSION
5563
}
5664

57-
tasks.register<Delete>("clean") {
65+
tasks.getByName<Delete>("clean") {
5866
delete(rootProject.layout.buildDirectory)
5967
}
68+
69+
// Merges individual module docs into a single HTML output
70+
dependencies {
71+
dokka(project(":core:"))
72+
dokka(project(":connectors:supabase"))
73+
dokka(project(":compose:"))
74+
}
75+
76+
dokka {
77+
moduleName.set("PowerSync Kotlin")
78+
}
79+
80+
// Serve the generated Dokka documentation using a simple HTTP server
81+
// File changes are not watched here
82+
tasks.register("serveDokka") {
83+
group = "dokka"
84+
dependsOn("dokkaGenerate")
85+
doLast {
86+
val server = HttpServer.create(InetSocketAddress(0), 0)
87+
val root = file("build/dokka/html")
88+
89+
val handler =
90+
com.sun.net.httpserver.HttpHandler { exchange: HttpExchange ->
91+
val rawPath = exchange.requestURI.path
92+
val cleanPath = URLDecoder.decode(rawPath.removePrefix("/"), "UTF-8")
93+
val requestedFile = File(root, cleanPath)
94+
95+
val file =
96+
when {
97+
requestedFile.exists() && !requestedFile.isDirectory -> requestedFile
98+
else -> File(root, "index.html") // fallback
99+
}
100+
101+
val contentType =
102+
Files.probeContentType(file.toPath()) ?: "application/octet-stream"
103+
val bytes = file.readBytes()
104+
exchange.responseHeaders.add("Content-Type", contentType)
105+
exchange.sendResponseHeaders(200, bytes.size.toLong())
106+
exchange.responseBody.use { it.write(bytes) }
107+
}
108+
109+
server.createContext("/", handler)
110+
server.executor = null
111+
server.start()
112+
113+
println("📘 Serving Dokka docs at http://localhost:${server.address.port}/")
114+
println("Press Ctrl+C to stop.")
115+
116+
// Keep the task alive
117+
Thread.currentThread().join()
118+
}
119+
}

‎compose/build.gradle.kts

+5
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,7 @@ plugins {
88
alias(libs.plugins.compose.compiler)
99
alias(libs.plugins.kotlinter)
1010
id("com.powersync.plugins.sonatype")
11+
id("dokka-convention")
1112
}
1213

1314
kotlin {
@@ -45,3 +46,7 @@ android {
4546
}
4647

4748
setupGithubRepository()
49+
50+
dokka {
51+
moduleName.set("PowerSync Compose")
52+
}

‎connectors/supabase/build.gradle.kts

+5
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,7 @@ plugins {
88
alias(libs.plugins.androidLibrary)
99
alias(libs.plugins.kotlinter)
1010
id("com.powersync.plugins.sonatype")
11+
id("dokka-convention")
1112
}
1213

1314
kotlin {
@@ -51,3 +52,7 @@ android {
5152
}
5253

5354
setupGithubRepository()
55+
56+
dokka {
57+
moduleName.set("PowerSync Supabase Connector")
58+
}

‎core/build.gradle.kts

+5
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,7 @@ plugins {
1919
id("com.powersync.plugins.sharedbuild")
2020
alias(libs.plugins.mokkery)
2121
alias(libs.plugins.kotlin.atomicfu)
22+
id("dokka-convention")
2223
}
2324

2425
val binariesFolder = project.layout.buildDirectory.dir("binaries/desktop")
@@ -295,3 +296,7 @@ tasks.withType<KotlinTest> {
295296
}
296297
}
297298
setupGithubRepository()
299+
300+
dokka {
301+
moduleName.set("PowerSync Core")
302+
}

‎core/src/androidMain/kotlin/BuildConfig.kt

+2-2
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
@Suppress("EXPECT_ACTUAL_CLASSIFIERS_ARE_IN_BETA_WARNING")
2-
public actual object BuildConfig {
3-
public actual val isDebug: Boolean
2+
internal actual object BuildConfig {
3+
actual val isDebug: Boolean
44
get() = com.powersync.BuildConfig.DEBUG
55
}

‎core/src/appleMain/kotlin/BuildConfig.kt

+2-2
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@ import kotlin.experimental.ExperimentalNativeApi
22
import kotlin.native.Platform
33

44
@Suppress("EXPECT_ACTUAL_CLASSIFIERS_ARE_IN_BETA_WARNING")
5-
public actual object BuildConfig {
5+
internal actual object BuildConfig {
66
@OptIn(ExperimentalNativeApi::class)
7-
public actual val isDebug: Boolean = Platform.isDebugBinary
7+
actual val isDebug: Boolean = Platform.isDebugBinary
88
}

‎core/src/commonMain/kotlin/BuildConfig.kt

+2-2
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
11
@Suppress("EXPECT_ACTUAL_CLASSIFIERS_ARE_IN_BETA_WARNING")
2-
public expect object BuildConfig {
3-
public val isDebug: Boolean
2+
internal expect object BuildConfig {
3+
val isDebug: Boolean
44
}

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

+15
Original file line numberDiff line numberDiff line change
@@ -2,15 +2,30 @@ package com.powersync.db.schema
22

33
import kotlinx.serialization.Serializable
44

5+
/**
6+
* The schema used by the database.
7+
*
8+
* The implementation uses the schema as a "VIEW" on top of JSON data.
9+
* No migrations are required on the client.
10+
*/
511
public data class Schema(
612
val tables: List<Table>,
713
) {
814
init {
915
validate()
1016
}
1117

18+
/**
19+
* Secondary constructor to create a schema with a variable number of tables.
20+
*/
1221
public constructor(vararg tables: Table) : this(tables.asList())
1322

23+
/**
24+
* Validates the schema by ensuring there are no duplicate table names
25+
* and that each table is valid.
26+
*
27+
* @throws AssertionError if duplicate table names are found.
28+
*/
1429
public fun validate() {
1530
val tableNames = mutableSetOf<String>()
1631
tables.forEach { table ->

‎core/src/jvmMain/kotlin/BuildConfig.kt

+2-2
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,12 @@
11
@Suppress("EXPECT_ACTUAL_CLASSIFIERS_ARE_IN_BETA_WARNING")
2-
public actual object BuildConfig {
2+
internal actual object BuildConfig {
33
/*
44
To debug on the JVM, you can:
55
- Set the com.powersync.debug property with System.setProperty("com.powersync.debug", true) BEFORE calling any powersync API.
66
- Start your java program with the -Dcom.powersync.debug=true command line argument.
77
- Set the POWERSYNC_JVM_DEBUG environment variable to "true" before starting your program.
88
*/
9-
public actual val isDebug: Boolean =
9+
actual val isDebug: Boolean =
1010
System.getProperty("com.powersync.debug") == "true" ||
1111
System.getenv("POWERSYNC_JVM_DEBUG") == "true"
1212
}

‎docs/assets/discord.svg

+18
Loading

‎docs/assets/doc-styles.css

+34
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
:root {
2+
--dokka-logo-image-url: url('../images/powersync-logo.png');
3+
}
4+
5+
.footer-container {
6+
display: flex;
7+
flex-wrap: wrap;
8+
justify-content: center;
9+
gap: 8px;
10+
margin-top: auto;
11+
box-sizing: border-box;
12+
background-color: var(--footer-background);
13+
color: var(--footer-font-color);
14+
}
15+
16+
.footer-title {
17+
margin-bottom: 8px;
18+
}
19+
20+
.footer-column {
21+
flex: 1 1 0;
22+
align-items: center;
23+
text-align: center;
24+
min-width: 300px;
25+
padding: 8px;
26+
}
27+
28+
.footer-icon-row {
29+
display: flex;
30+
justify-content: center;
31+
align-items: center;
32+
gap: 8px;
33+
flex-wrap: wrap;
34+
}

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

+48
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
<#macro display>
2+
<@template_cmd name="pathToRoot">
3+
<div style="margin-top:auto">
4+
<div class="footer-container">
5+
<div class="footer-column">
6+
<strong class="footer-title">Community</strong>
7+
<div class="footer-icon-row">
8+
<a href="https://discord.gg/powersync" target="_blank">
9+
<img src="./${pathToRoot}images/discord.svg" loading="lazy" alt="Discord" height="24">
10+
</a>
11+
<a href="https://twitter.com/powersync_" target="_blank">
12+
<img src="./${pathToRoot}images/x.svg" loading="lazy" alt="Twitter" height="20">
13+
</a>
14+
<a href="https://www.youtube.com/@powersync_" target="_blank">
15+
<img src="./${pathToRoot}images/youtube.svg" loading="lazy" alt="YouTube" width="32" height="28">
16+
</a>
17+
<a href="https://www.linkedin.com/showcase/journeyapps-powersync/" target="_blank">
18+
<img src="./${pathToRoot}images/linkedin.svg" loading="lazy" alt="LinkedIn" height="24">
19+
</a>
20+
</div>
21+
</div>
22+
23+
<div class="footer-column">
24+
<strong class="footer-title">More</strong>
25+
<div class="footer-icon-row">
26+
<a href="https://github.com/powersync-ja" target="_blank">
27+
<img src="./${pathToRoot}images/github.svg" loading="lazy" alt="GitHub" height="24">
28+
</a>
29+
<a href="https://www.powersync.com/" target="_blank">
30+
<img src="./${pathToRoot}images/web.svg" loading="lazy" alt="Website" height="30">
31+
</a>
32+
</div>
33+
</div>
34+
</div>
35+
36+
<div class="footer-container">
37+
<span>© 2025 Journey Mobile, Inc.</span>
38+
<span class="pull-right">
39+
<span>Generated by </span>
40+
<a class="footer--link footer--link_external" href="https://github.com/Kotlin/dokka">
41+
<span>dokka</span>
42+
</a>
43+
</span>
44+
</div>
45+
46+
</div>
47+
</@template_cmd>
48+
</#macro>

‎docs/assets/github.svg

+22
Loading

‎docs/assets/linkedin.svg

+12
Loading

‎docs/assets/logo-icon.svg

+5
Loading

‎docs/assets/powersync-logo.png

53.2 KB
Loading

‎docs/assets/web.svg

+7
Loading

0 commit comments

Comments
 (0)