Skip to content

Commit 65c372a

Browse files
afarberafarber
committed
Use dokka to build documentation
1 parent 9646df1 commit 65c372a

File tree

7 files changed

+209
-18
lines changed

7 files changed

+209
-18
lines changed

‎.github/workflows/_docs.yml‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
name: Documentation
2+
3+
on:
4+
workflow_call:
5+
6+
permissions:
7+
contents: read
8+
9+
jobs:
10+
docs:
11+
name: Build Documentation
12+
runs-on: ubuntu-latest
13+
14+
steps:
15+
- name: Checkout repository
16+
uses: actions/checkout@v4
17+
18+
- name: Set up JDK 17
19+
uses: actions/setup-java@v4
20+
with:
21+
distribution: temurin
22+
java-version: 17
23+
24+
- name: Cache Gradle
25+
uses: actions/cache@v4
26+
with:
27+
path: |
28+
~/.gradle/caches
29+
~/.gradle/wrapper
30+
key: ${{ runner.os }}-gradle-${{ hashFiles('**/*.gradle*', '**/gradle-wrapper.properties') }}
31+
restore-keys: |
32+
${{ runner.os }}-gradle-
33+
34+
- name: Grant execute permission for Gradle wrapper
35+
run: chmod +x gradlew
36+
37+
- name: Build documentation
38+
run: ./gradlew dokkaGenerate --no-daemon
39+
40+
- name: Upload documentation artifact
41+
uses: actions/upload-artifact@v4
42+
with:
43+
name: documentation
44+
path: 'openmapview/build/dokka/html/**'
45+
retention-days: 30

‎.github/workflows/ci.yml‎

Lines changed: 7 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -28,14 +28,19 @@ jobs:
2828
needs: [format, copyright]
2929
uses: ./.github/workflows/_coverage.yml
3030

31+
docs:
32+
name: Documentation
33+
needs: [format, copyright]
34+
uses: ./.github/workflows/_docs.yml
35+
3136
build-library:
3237
name: Build Library
33-
needs: [format, copyright, test, coverage]
38+
needs: [format, copyright, test, coverage, docs]
3439
uses: ./.github/workflows/_build-library.yml
3540

3641
build-examples:
3742
name: Build Examples
38-
needs: [format, copyright, test, coverage]
43+
needs: [format, copyright, test, coverage, docs]
3944
uses: ./.github/workflows/_build-examples.yml
4045

4146
instrumented-test:

‎.github/workflows/docs-deploy.yml‎

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
name: Deploy Documentation
2+
3+
on:
4+
push:
5+
branches: [main, master]
6+
paths:
7+
- 'openmapview/src/**/*.kt'
8+
- 'README.md'
9+
- '.github/workflows/_docs.yml'
10+
- '.github/workflows/docs-deploy.yml'
11+
12+
permissions:
13+
contents: read
14+
pages: write
15+
id-token: write
16+
17+
concurrency:
18+
group: pages
19+
cancel-in-progress: true
20+
21+
jobs:
22+
build-docs:
23+
name: Build Documentation
24+
uses: ./.github/workflows/_docs.yml
25+
26+
deploy:
27+
name: Deploy to GitHub Pages
28+
needs: build-docs
29+
runs-on: ubuntu-latest
30+
environment:
31+
name: github-pages
32+
url: ${{ steps.deployment.outputs.page_url }}
33+
34+
steps:
35+
- name: Download documentation artifact
36+
uses: actions/download-artifact@v4
37+
with:
38+
name: documentation
39+
path: ./docs
40+
41+
- name: Upload Pages artifact
42+
uses: actions/upload-pages-artifact@v3
43+
with:
44+
path: ./docs
45+
46+
- name: Deploy to GitHub Pages
47+
id: deployment
48+
uses: actions/deploy-pages@v4

‎README.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,7 @@
22
[![Daily Tests](https://github.com/afarber/OpenMapView/actions/workflows/daily.yml/badge.svg)](https://github.com/afarber/OpenMapView/actions/workflows/daily.yml)
33
[![Release](https://github.com/afarber/OpenMapView/actions/workflows/release.yml/badge.svg)](https://github.com/afarber/OpenMapView/actions/workflows/release.yml)
44
[![codecov](https://codecov.io/gh/afarber/OpenMapView/branch/main/graph/badge.svg)](https://codecov.io/gh/afarber/OpenMapView)
5+
[![API Documentation](https://img.shields.io/badge/API-Documentation-blue)](https://afarber.github.io/OpenMapView/)
56

67
# OpenMapView
78

@@ -28,6 +29,12 @@ The library is available on [Maven Central](https://central.sonatype.com/artifac
2829
- Extensible marker, overlay, and gesture handling
2930
- MIT licensed (use freely in commercial apps)
3031

32+
## API Documentation
33+
34+
Full API reference documentation is available at [afarber.github.io/OpenMapView](https://afarber.github.io/OpenMapView/).
35+
36+
The documentation is automatically generated from KDoc comments and updated with every commit to main.
37+
3138
## Examples
3239

3340
Explore the example applications to see OpenMapView in action:

‎build.gradle.kts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,7 @@ plugins {
1919
id("org.jetbrains.kotlin.android") version "2.0.21" apply false
2020
id("org.jetbrains.kotlin.plugin.compose") version "2.0.21" apply false
2121
id("com.diffplug.spotless") version "6.25.0" apply false
22+
id("org.jetbrains.dokka") version "2.1.0" apply false
2223
id("com.gradleup.nmcp.aggregation") version "0.1.2"
2324
}
2425

‎docs/GITHUB_WORKFLOWS.md‎

Lines changed: 73 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,10 @@
44

55
This document explains the GitHub Actions workflows used in the OpenMapView project.
66

7+
> **Naming Convention:** Reusable workflows are prefixed with an underscore (e.g., `_docs.yml`, `_test.yml`)
8+
> to distinguish them from caller workflows (e.g., `ci.yml`, `release.yml`). This convention
9+
> makes it easy to identify modular components that can be composed into different pipelines.
10+
711
## Architecture Overview
812

913
The workflows are designed using a **modular, reusable component architecture** to eliminate code duplication and enable parallel execution.
@@ -69,6 +73,13 @@ Located in `.github/workflows/`:
6973
- **Usage**: Called by daily.yml and ci.yml (PR only)
7074
- **Duration**: ~10-15 minutes (may vary due to emulator startup and potential flakiness)
7175

76+
#### `_docs.yml`
77+
- **Purpose**: Build API documentation with Dokka
78+
- **Runs**: `./gradlew dokkaGenerate`
79+
- **Artifacts**: Uploads generated HTML documentation
80+
- **Usage**: Called by CI for validation and docs-deploy for publishing
81+
- **Duration**: ~1-2 minutes
82+
7283
### Main Workflows
7384

7485
#### `ci.yml` - Continuous Integration
@@ -84,18 +95,19 @@ format (Check formatting)
8495
copyright (Check headers)
8596
|
8697
v
87-
+----------------+----------------+
88-
| |
89-
v v
90-
test (Unit tests) coverage (Test coverage)
91-
| |
92-
+----------------+----------------+
93-
|
94-
+----------------+----------------+
95-
| |
96-
v v
97-
build-library build-examples
98-
(Build AAR) (Build 3 APKs)
98+
+----------------+----------------+----------------+
99+
| | |
100+
v v v
101+
test docs coverage
102+
(Unit tests) (Build API docs) (Test coverage)
103+
| | |
104+
+----------------+----------------+----------------+
105+
|
106+
+--------------------------+-------------------------+
107+
| |
108+
v v
109+
build-library build-examples
110+
(Build AAR) (Build 3 APKs)
99111
100112
For Pull Requests only:
101113
v
@@ -107,10 +119,11 @@ instrumented-test (Phone + Automotive)
107119
1. **format** - Runs Spotless formatting check
108120
2. **copyright** - Verifies MIT license headers
109121
3. **test** - Runs unit tests (depends on format + copyright)
110-
4. **coverage** - Checks test coverage meets 20% minimum (depends on format + copyright)
111-
5. **build-library** - Builds library AAR (depends on format + copyright + test + coverage, runs in parallel with build-examples)
112-
6. **build-examples** - Builds example APKs (depends on format + copyright + test + coverage, runs in parallel with build-library)
113-
7. **instrumented-test** - Runs instrumentation tests on phone and automotive emulators (PR only, runs independently)
122+
4. **docs** - Builds API documentation with Dokka (depends on format + copyright)
123+
5. **coverage** - Checks test coverage meets 20% minimum (depends on format + copyright)
124+
6. **build-library** - Builds library AAR (depends on format + copyright + test + docs + coverage, runs in parallel with build-examples)
125+
7. **build-examples** - Builds example APKs (depends on format + copyright + test + docs + coverage, runs in parallel with build-library)
126+
8. **instrumented-test** - Runs instrumentation tests on phone and automotive emulators (PR only, runs independently)
114127

115128
**Total Duration**:
116129
- **Maintainer pushes to main**: ~3-4 minutes (no instrumentation tests)
@@ -202,6 +215,50 @@ Phone Tests Automotive Tests
202215
- Manual trigger available for on-demand testing
203216
- Acceptable flakiness since it doesn't block development workflow
204217

218+
#### `docs-deploy.yml` - API Documentation Deployment
219+
**Trigger**: Push to `main` or `master` branch (paths: `openmapview/src/**/*.kt`, `README.md`, `.github/workflows/_docs.yml`, `.github/workflows/docs-deploy.yml`)
220+
221+
**Purpose**: Generate API documentation from KDoc comments and deploy to GitHub Pages
222+
223+
**Execution Flow**:
224+
```
225+
Push to main (filtered by paths)
226+
|
227+
v
228+
build-docs (calls _docs.yml)
229+
|
230+
v
231+
Build documentation with Dokka
232+
|
233+
v
234+
Upload documentation artifact
235+
|
236+
v
237+
deploy (Download artifact)
238+
|
239+
v
240+
Deploy to GitHub Pages
241+
```
242+
243+
**Jobs**:
244+
1. **build-docs** - Calls the reusable `_docs.yml` workflow to build documentation
245+
2. **deploy** - Downloads artifact and deploys to GitHub Pages
246+
247+
**Configuration**:
248+
- Only runs when Kotlin source files or docs workflows change
249+
- Uses concurrency control (only one deployment at a time)
250+
- Requires GitHub Pages to be enabled with "GitHub Actions" as source
251+
252+
**Total Duration**: ~2-3 minutes
253+
254+
**Published URL**: https://afarber.github.io/OpenMapView/
255+
256+
**Benefits**:
257+
- Documentation always in sync with code
258+
- Automatic updates on every push to main
259+
- No manual publishing needed
260+
- Professional, searchable API reference
261+
205262
## Required GitHub Secrets
206263

207264
For the release workflow to function, the project owner must configure these secrets in the GitHub repository:

‎openmapview/build.gradle.kts‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,7 @@ plugins {
22
id("com.android.library")
33
id("org.jetbrains.kotlin.android")
44
id("com.diffplug.spotless")
5+
id("org.jetbrains.dokka")
56
id("maven-publish")
67
id("signing")
78
id("jacoco")
@@ -219,3 +220,30 @@ signing {
219220
)
220221
sign(publishing.publications)
221222
}
223+
224+
dokka {
225+
moduleName.set("OpenMapView")
226+
moduleVersion.set(rootProject.ext["libVersion"] as String)
227+
228+
dokkaSourceSets.main {
229+
documentedVisibilities.set(
230+
setOf(
231+
org.jetbrains.dokka.gradle.engine.parameters.VisibilityModifier.Public,
232+
org.jetbrains.dokka.gradle.engine.parameters.VisibilityModifier.Protected,
233+
),
234+
)
235+
236+
sourceLink {
237+
localDirectory.set(file("src/main/kotlin"))
238+
remoteUrl.set(uri("https://github.com/afarber/OpenMapView/tree/main/openmapview/src/main/kotlin"))
239+
remoteLineSuffix.set("#L")
240+
}
241+
242+
perPackageOption {
243+
matchingRegex.set(".*\\.internal.*")
244+
suppress.set(true)
245+
}
246+
247+
enableAndroidDocumentationLink.set(true)
248+
}
249+
}

0 commit comments

Comments
 (0)