Skip to content

Commit 1945fec

Browse files
Mr3zeeMr3zee
committed
Add dokka setup to the repo
1 parent 2935888 commit 1945fec

File tree

13 files changed

+203
-4
lines changed

13 files changed

+203
-4
lines changed

‎.github/images/logo-icon.svg‎

Lines changed: 1 addition & 0 deletions
Loading

‎.github/workflows/docs.yml‎

Lines changed: 15 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -72,21 +72,34 @@ jobs:
7272
needs: [ build, test ]
7373
runs-on: ubuntu-latest
7474
steps:
75+
- name: Checkout repository
76+
uses: actions/checkout@v4
77+
with:
78+
fetch-depth: 0
79+
80+
- name: Move API docs to the publication directory
81+
run:
82+
mkdir __docs_publication_dir
83+
cp -r docs/pages/api __docs_publication_dir/api
84+
7585
- name: Download artifacts
7686
uses: actions/download-artifact@v4
7787
with:
7888
name: kotlinx-rpc
7989

8090
- name: Unzip artifact
81-
run: unzip -O UTF-8 -qq '${{ env.ARTIFACT }}' -d dir
91+
run: unzip -O UTF-8 -qq '${{ env.ARTIFACT }}' -d __docs_publication_dir
92+
93+
- name: Update sitemap.xml
94+
run: chmod +x updateSitemap.sh && ./updateSitemap.sh __docs_publication_dir/sitemap.xml __docs_publication_dir/api
8295

8396
- name: Setup Pages
8497
uses: actions/configure-pages@v5
8598

8699
- name: Package and upload Pages artifact
87100
uses: actions/upload-pages-artifact@v3
88101
with:
89-
path: dir
102+
path: __docs_publication_dir
90103

91104
- name: Deploy to GitHub Pages
92105
id: deployment

‎.github/workflows/dokka.yml‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
name: Verify API Docs
2+
3+
on:
4+
pull_request:
5+
6+
permissions:
7+
contents: read
8+
9+
jobs:
10+
verify-api-docs:
11+
name: Up-To-Date Check
12+
runs-on: ubuntu-latest
13+
steps:
14+
- name: Checkout Sources
15+
uses: actions/checkout@v4
16+
- name: Setup Gradle
17+
uses: gradle/actions/setup-gradle@v3
18+
- name: Check Dokka generation is up-to-date
19+
run: ./gradlew dokkaGenerate
20+
- name: Check Dokka HTML output is up-to-date
21+
run: git status --porcelain | grep "docs/pages/api/" && echo "Run `./gradlew dokkaGenerate` to update API docs and commit changes" && exit 1 || exit 0

‎build.gradle.kts‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,22 +3,59 @@
33
*/
44

55
import org.jetbrains.kotlin.gradle.plugin.getKotlinPluginVersion
6+
import util.asDokkaVersion
67
import util.configureApiValidation
78
import util.configureNpm
89
import util.configureProjectReport
910
import util.registerDumpPlatformTableTask
1011
import util.libs
1112
import util.registerVerifyPlatformTableTask
13+
import java.time.Year
1214

1315
plugins {
1416
alias(libs.plugins.serialization) apply false
1517
alias(libs.plugins.kotlinx.rpc) apply false
1618
alias(libs.plugins.conventions.kover)
1719
alias(libs.plugins.conventions.gradle.doctor)
20+
alias(libs.plugins.dokka)
1821
alias(libs.plugins.atomicfu)
1922
id("build-util")
2023
}
2124

25+
dokka {
26+
val libDokkaVersion = libs.versions.kotlinx.rpc.get().asDokkaVersion()
27+
28+
moduleVersion.set(libDokkaVersion)
29+
30+
val dokkaVersionsDirectory = layout.projectDirectory
31+
.dir("docs")
32+
.dir("pages")
33+
.dir("api")
34+
.asFile
35+
36+
37+
pluginsConfiguration {
38+
html {
39+
customAssets.from(".github/images/logo-icon.svg")
40+
footerMessage = "© ${Year.now()} JetBrains s.r.o and contributors. Apache License 2.0"
41+
}
42+
43+
versioning {
44+
version = libDokkaVersion
45+
olderVersionsDir = dokkaVersionsDirectory
46+
}
47+
}
48+
49+
dokkaPublications.html {
50+
outputDirectory = dokkaVersionsDirectory.resolve(libDokkaVersion)
51+
}
52+
53+
dokkaGeneratorIsolation = ProcessIsolation {
54+
// Configures heap size, use if start to fail with OOM on CI
55+
// maxHeapSize = "4g"
56+
}
57+
}
58+
2259
configureProjectReport()
2360
configureNpm()
2461
configureApiValidation()

‎docs/pages/kotlinx-rpc/cfg/buildprofiles.xml‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,7 @@
2222

2323
<versions-switcher>%docs-raw-path%/help-versions.json</versions-switcher>
2424

25-
<generate-sitemap-url-prefix>https://www.jetbrains.com/help/</generate-sitemap-url-prefix>
25+
<generate-sitemap-url-prefix>%host%</generate-sitemap-url-prefix>
2626

2727
<algolia-id>MMA5Z3JT91</algolia-id>
2828
<algolia-index>prod_kotlin_rpc</algolia-index>
@@ -37,8 +37,9 @@
3737

3838
<sitemap priority="0.35" change-frequency="monthly"/>
3939
<footer>
40-
<copyright>2000-2024 JetBrains s.r.o.</copyright>
40+
<copyright>2000-2025 JetBrains s.r.o.</copyright>
4141
<link href="https://github.com/Kotlin/kotlinx-rpc/blob/main/CONTRIBUTING.md">Contribute to kotlinx.rpc</link>
4242
<link href="https://kotlinlang.slack.com/archives/C072YJ3Q91V">Slack Community</link>
43+
<link href="%host%/api/%kotlinx-rpc-version%/">API Reference</link>
4344
</footer>
4445
</buildprofiles>

‎docs/pages/kotlinx-rpc/rpc.tree‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -49,4 +49,5 @@
4949
<toc-element topic="0-2-4.topic"/>
5050
<toc-element topic="0-2-1.topic"/>
5151
</toc-element>
52+
<toc-element toc-title="API Reference" href="%host%/api/%kotlinx-rpc-version%/"/>
5253
</instance-profile>

‎gradle-conventions/common/build.gradle.kts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,7 @@ dependencies {
1313

1414
api(libs.kotlin.gradle.plugin)
1515
api(libs.detekt.gradle.plugin)
16+
api(libs.dokka.gradle.plugin)
1617
api(libs.binary.compatibility.validator.gradle.plugin)
1718

1819
if (isLatestKotlinVersion) {

‎gradle-conventions/common/src/main/kotlin/util/dokka.kt‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
/*
2+
* Copyright 2023-2025 JetBrains s.r.o and contributors. Use of this source code is governed by the Apache 2.0 license.
3+
*/
4+
5+
package util
6+
7+
import org.gradle.api.Project
8+
import org.gradle.kotlin.dsl.configure
9+
import org.jetbrains.dokka.gradle.DokkaExtension
10+
import org.jetbrains.dokka.gradle.engine.parameters.VisibilityModifier
11+
12+
fun String.asDokkaVersion() = removeSuffix("-SNAPSHOT")
13+
14+
fun Project.applyDokka() {
15+
if (!isPublicModule) {
16+
return
17+
}
18+
19+
plugins.apply(libs.plugins.dokka.get().pluginId)
20+
21+
configure<DokkaExtension> {
22+
moduleName.set("$KOTLINX_RPC_PREFIX-${project.name}")
23+
24+
dokkaSourceSets.configureEach {
25+
sourceLink {
26+
localDirectory.set(rootDir)
27+
remoteUrl("https://github.com/Kotlin/kotlinx-rpc/blob/${libs.versions.kotlinx.rpc.get().asDokkaVersion()}")
28+
remoteLineSuffix.set("#L")
29+
30+
documentedVisibilities.set(
31+
setOf(
32+
VisibilityModifier.Public,
33+
VisibilityModifier.Protected,
34+
)
35+
)
36+
}
37+
}
38+
39+
dokkaPublications.configureEach {
40+
suppressObviousFunctions.set(true)
41+
failOnWarning.set(true)
42+
}
43+
}
44+
45+
val thisProject = project
46+
47+
rootProject.configurations.matching { it.name == "dokka" }.all {
48+
rootProject.dependencies.add("dokka", thisProject)
49+
}
50+
}

‎gradle-conventions/src/main/kotlin/conventions-jvm.gradle.kts‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@
55
import org.jetbrains.kotlin.gradle.dsl.KotlinJvmProjectExtension
66
import util.configureJvm
77
import util.optInForRpcApi
8+
import util.applyDokka
89

910
plugins {
1011
id("conventions-common")
@@ -26,3 +27,5 @@ configure<KotlinJvmProjectExtension> {
2627
}
2728

2829
configureJvm(isKmp = false)
30+
31+
applyDokka()

‎gradle-conventions/src/main/kotlin/conventions-kmp.gradle.kts‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,7 @@
44

55
import org.jetbrains.kotlin.gradle.dsl.KotlinMultiplatformExtension
66
import util.*
7+
import util.applyDokka
78

89
plugins {
910
id("conventions-common")
@@ -23,3 +24,5 @@ withKotlinConfig {
2324
}
2425

2526
configureJvm(isKmp = true)
27+
28+
applyDokka()

0 commit comments

Comments
 (0)