Skip to content

Commit aa77cef

Browse files
softartdevsoftartdev
committed
docs: add Dokka documentation
- Renamed `darkThemeState` to `themeState` across all modules and sample apps for better clarity. - Integrated Dokka for API documentation generation across `theme-prefs`, `theme-material`, and `theme-material3` modules. - Added KDoc comments to public composables, classes, and interfaces, including `ThemePrefs`, `PreferenceHelper`, and various UI components. - Updated GitHub Pages workflow to build and deploy Dokka documentation and the WasmJS web demo to a unified site. - Added a landing page for GitHub Pages and linked documentation and demo in the `README.md`. - Added `dokka` dependency and plugin configuration to `libs.versions.toml` and build scripts.
1 parent 319949b commit aa77cef

25 files changed

Lines changed: 298 additions & 46 deletions

File tree

‎.github/pages-assets/index.html‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
<!DOCTYPE html>
2+
<html lang="en">
3+
<head>
4+
<meta charset="UTF-8">
5+
<meta name="viewport" content="width=device-width, initial-scale=1">
6+
<title>MaterialThemePrefs</title>
7+
<style>
8+
body { font-family: system-ui, sans-serif; max-width: 640px; margin: 2rem auto; padding: 0 1rem; line-height: 1.5; }
9+
h1 { font-size: 1.5rem; }
10+
p { color: #444; }
11+
ul { list-style: none; padding: 0; }
12+
li { margin: 0.75rem 0; }
13+
a { color: #0969da; text-decoration: none; }
14+
a:hover { text-decoration: underline; }
15+
</style>
16+
</head>
17+
<body>
18+
<h1>MaterialThemePrefs</h1>
19+
<p>Kotlin Multiplatform library for persistent light/dark/system theme preference with Compose Multiplatform (Material and Material 3).</p>
20+
<ul>
21+
<li><a href="./docs/">API Documentation</a></li>
22+
<li><a href="./demo/">Web Demo</a></li>
23+
</ul>
24+
</body>
25+
</html>

‎.github/workflows/gh-pages.yml‎

Lines changed: 14 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,10 @@
1+
# GitHub Pages: single artifact with / (landing), /docs/ (Dokka), /demo/ (Wasm).
2+
# In repo Settings > Pages > Build and deployment, set Source to "GitHub Actions".
13
name: Build & Deploy CI/CD
24

35
on:
46
push:
5-
branches: ["master", "dev"]
7+
branches: ["master", "dev", "dokka"]
68

79
# Allows you to run this workflow manually from the Actions tab
810
workflow_dispatch:
@@ -37,19 +39,29 @@ jobs:
3739
cache-overwrite-existing: true
3840
- name: "Build WasmJS App"
3941
run: gradle --no-configure-on-demand :sample:web:wasmJsBrowserDistribution
42+
- name: "Build Dokka"
43+
run: gradle --no-configure-on-demand :dokkaGenerate
44+
- name: "Assemble site"
45+
run: |
46+
mkdir -p build/site/demo
47+
cp .github/pages-assets/index.html build/site/index.html
48+
cp -r sample/web/build/dist/wasmJs/productionExecutable/* build/site/demo/
4049
- name: Setup Pages
4150
uses: actions/configure-pages@v5
4251
- name: Upload artifact
4352
uses: actions/upload-pages-artifact@v3
4453
with:
45-
path: ./sample/web/build/dist/wasmJs/productionExecutable
54+
path: ./build/site
4655

4756
deploy:
4857
environment:
4958
name: github-pages
5059
url: ${{ steps.deployment.outputs.page_url }}
5160
runs-on: ubuntu-latest
5261
needs: build
62+
permissions:
63+
pages: write
64+
id-token: write
5365
steps:
5466
- name: Deploy to GitHub Pages
5567
id: deployment

‎README.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,8 @@ Supported platforms:
1010
- Desktop JVM (MacOS, Linux, Windows)
1111
- Web (wasm JS)
1212

13+
**[API Documentation](https://softartdev.github.io/MaterialThemePrefs/docs/)** · **[Web Demo](https://softartdev.github.io/MaterialThemePrefs/demo/)**
14+
1315
![Android screenshot](doc/screenshots/gif/android/material_design_3/demo.gif)
1416
![iOS screenshot](doc/screenshots/gif/iOS/material_design_3/demo.gif)
1517
![Desktop screenshot](doc/screenshots/gif/desktop/material_design_3/demo.gif)

‎build.gradle.kts‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,4 +5,17 @@ plugins {
55
alias(libs.plugins.android.application) apply false
66
alias(libs.plugins.android.kotlin.multiplatform.library) apply false
77
alias(libs.plugins.compose.multiplatform) apply false
8+
alias(libs.plugins.dokka)
9+
}
10+
11+
dependencies {
12+
dokka(project(":theme:theme-prefs"))
13+
dokka(project(":theme:theme-material"))
14+
dokka(project(":theme:theme-material3"))
15+
}
16+
17+
dokka {
18+
dokkaPublications.html {
19+
outputDirectory.set(layout.buildDirectory.dir("site/docs"))
20+
}
821
}

‎gradle/libs.versions.toml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,7 @@ androidx-navigation = "2.9.2"
1313
androidx-activity-compose = "1.12.4"
1414
kotlinx-serialization-json = "1.10.0"
1515
vanniktech = "0.36.0"
16+
dokka = "2.1.0"
1617

1718
[libraries]
1819
androidx-navigation-compose = { module = "org.jetbrains.androidx.navigation:navigation-compose", version.ref = "androidx-navigation" }
@@ -40,3 +41,4 @@ android-application = { id = "com.android.application", version.ref = "agp" }
4041
android-kotlin-multiplatform-library = { id = "com.android.kotlin.multiplatform.library", version.ref = "agp" }
4142
compose-multiplatform = { id = "org.jetbrains.compose", version.ref = "compose" }
4243
vanniktech-maven-publish = { id = "com.vanniktech.maven.publish", version.ref = "vanniktech" }
44+
dokka = { id = "org.jetbrains.dokka", version.ref = "dokka" }

‎sample/shared/src/commonMain/kotlin/com/softartdev/shared/AppState.kt‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -23,7 +23,7 @@ object AppState {
2323
val isDarkTheme: Boolean
2424
@Composable
2525
@ReadOnlyComposable
26-
get() = when (themePrefs.darkThemeState.value) {
26+
get() = when (themePrefs.themeState.value) {
2727
ThemeEnum.Light -> false
2828
ThemeEnum.Dark -> true
2929
ThemeEnum.SystemDefault -> isSystemInDarkTheme()
@@ -35,11 +35,11 @@ object AppState {
3535
get() {
3636
val currentIsDark: Boolean = isDarkTheme
3737
val themePrefs: ThemePrefs = LocalThemePrefs.current
38-
val darkThemeState = themePrefs.darkThemeState
38+
val themeState = themePrefs.themeState
3939
val prefHelper = themePrefs.preferenceHelper
4040
return {
41-
darkThemeState.value = if (currentIsDark) ThemeEnum.Light else ThemeEnum.Dark
42-
prefHelper.themeEnum = darkThemeState.value
41+
themeState.value = if (currentIsDark) ThemeEnum.Light else ThemeEnum.Dark
42+
prefHelper.themeEnum = themeState.value
4343
}
4444
}
4545

‎sample/shared/src/commonMain/kotlin/com/softartdev/shared/EdgeToEdge.kt‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@ expect fun EnableEdgeToEdge(material3: Boolean, inDark: Boolean)
1212
val ThemePrefs.inDark: Boolean
1313
@Composable
1414
@ReadOnlyComposable
15-
get() = when (darkThemeState.value) {
15+
get() = when (themeState.value) {
1616
ThemeEnum.Light -> false
1717
ThemeEnum.Dark -> true
1818
ThemeEnum.SystemDefault -> isSystemInDarkTheme()

‎theme/theme-material/build.gradle.kts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,7 @@ plugins {
88
alias(libs.plugins.kotlin.compose.compiler)
99
alias(libs.plugins.compose.multiplatform)
1010
alias(libs.plugins.android.kotlin.multiplatform.library)
11+
alias(libs.plugins.dokka)
1112
id("convention.publication")
1213
}
1314

‎theme/theme-material/src/commonMain/kotlin/com/softartdev/theme/material/MaterialThemePrefs.kt‎

Lines changed: 26 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -12,22 +12,36 @@ import com.softartdev.theme.pref.ThemeEnum
1212
import com.softartdev.theme.pref.ThemePrefs
1313
import com.softartdev.theme.pref.rememberPreferenceHelper
1414

15+
/**
16+
* [ThemePrefs] implementation for Material (v1) theming.
17+
* Provides [colors] that switch based on [ThemeEnum] (light/dark/system).
18+
*
19+
* @param preferenceHelper Backing storage for the selected theme.
20+
* @param darkColorPalette Colors used when dark theme is active. Defaults to [darkColors].
21+
* @param lightColorPalette Colors used when light theme is active. Defaults to [lightColors].
22+
*/
1523
public class MaterialThemePrefs(
1624
preferenceHelper: PreferenceHelper,
1725
private val darkColorPalette: Colors = darkColors(),
1826
private val lightColorPalette: Colors = lightColors()
1927
) : ThemePrefs(preferenceHelper) {
2028

29+
/**
30+
* Current [Colors] based on [ThemeEnum]. For [ThemeEnum.SystemDefault], follows system dark/light.
31+
*/
2132
public val colors: Colors
2233
@Composable
2334
@ReadOnlyComposable
24-
get() = when (darkThemeState.value) {
35+
get() = when (themeState.value) {
2536
ThemeEnum.Light -> lightColorPalette
2637
ThemeEnum.Dark -> darkColorPalette
2738
ThemeEnum.SystemDefault -> if (isSystemInDarkTheme()) darkColorPalette else lightColorPalette
2839
}
2940
}
3041

42+
/**
43+
* Returns [Colors] when this [ThemePrefs] is a [MaterialThemePrefs]; use inside Material theme scope.
44+
*/
3145
public val ThemePrefs.colors: Colors
3246
@Composable
3347
@ReadOnlyComposable
@@ -36,12 +50,23 @@ public val ThemePrefs.colors: Colors
3650
return materialThemePrefs.colors
3751
}
3852

53+
/**
54+
* Returns a [MaterialThemePrefs] remembered across recompositions using default [rememberPreferenceHelper].
55+
*/
3956
@Composable
4057
public fun rememberThemePrefs(): MaterialThemePrefs {
4158
val preferenceHelper = rememberPreferenceHelper()
4259
return remember { MaterialThemePrefs(preferenceHelper) }
4360
}
4461

62+
/**
63+
* Returns a [MaterialThemePrefs] with the given [PreferenceHelper] and color palettes.
64+
*
65+
* @param preferHelper Backing storage for theme preference.
66+
* @param darkColorPalette Colors for dark theme.
67+
* @param lightColorPalette Colors for light theme.
68+
* @return Remembered [MaterialThemePrefs] instance.
69+
*/
4570
@Composable
4671
public fun rememberThemePrefs(
4772
preferHelper: PreferenceHelper = rememberPreferenceHelper(),

‎theme/theme-material/src/commonMain/kotlin/com/softartdev/theme/material/MenuPreference.kt‎

Lines changed: 25 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -22,23 +22,38 @@ import io.github.softartdev.theme_prefs.generated.resources.choose_theme
2222
import io.github.softartdev.theme_prefs.generated.resources.theme
2323
import org.jetbrains.compose.resources.stringResource
2424

25+
/**
26+
* List item used as a category header for the "Theme" section in preference screens.
27+
*/
2528
@Composable
2629
public fun ThemePreferencesCategory(): Unit = PreferenceCategory(
2730
title = stringResource(Res.string.theme),
2831
vector = Icons.Filled.Brightness4
2932
)
3033

34+
/**
35+
* List item that opens the theme picker when clicked. Shows current theme in secondary text.
36+
*
37+
* @param themePrefs [ThemePrefs] to read current theme from; defaults to [LocalThemePrefs.current].
38+
* @param onClick Called when the row is clicked (e.g. to show theme dialog).
39+
*/
3140
@Composable
3241
public fun ThemePreferenceItem(
3342
themePrefs: ThemePrefs = LocalThemePrefs.current,
3443
onClick: () -> Unit = {}
3544
): Unit = PreferenceItem(
3645
title = stringResource(Res.string.choose_theme),
3746
vector = Icons.Filled.SettingsBrightness,
38-
secondaryText = { Text(text = stringResource(themePrefs.darkThemeState.value.stringRes)) },
47+
secondaryText = { Text(text = stringResource(themePrefs.themeState.value.stringRes)) },
3948
onClick = onClick
4049
)
4150

51+
/**
52+
* Non-clickable list item used as a section header (icon + title in secondary style).
53+
*
54+
* @param title Section title.
55+
* @param vector Icon for the section.
56+
*/
4257
@Composable
4358
public fun PreferenceCategory(title: String, vector: ImageVector): Unit = ListItem(
4459
icon = { Icon(imageVector = vector, contentDescription = title) },
@@ -49,6 +64,15 @@ public fun PreferenceCategory(title: String, vector: ImageVector): Unit = ListIt
4964
}
5065
)
5166

67+
/**
68+
* Clickable list row for a preference: icon, title, optional secondary/trailing content.
69+
*
70+
* @param title Primary text.
71+
* @param vector Icon for the row.
72+
* @param onClick Called when the row is clicked.
73+
* @param secondaryText Optional secondary text or composable.
74+
* @param trailing Optional trailing composable.
75+
*/
5276
@Composable
5377
public fun PreferenceItem(
5478
title: String,

0 commit comments

Comments
 (0)