Skip to content

Commit 1c25640

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

File tree

15 files changed

+203
-4
lines changed

15 files changed

+203
-4
lines changed

‎.github/images/logo-icon.svg

Lines changed: 1 addition & 0 deletions
Loading

‎.github/workflows/docs.yml

Lines changed: 21 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -72,21 +72,40 @@ 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: Setup Gradle
81+
uses: gradle/actions/setup-gradle@v3
82+
83+
- name: Run Dokka
84+
run: ./gradlew dokkaGenerate
85+
86+
- name: Move API docs to the publication directory
87+
run:
88+
mkdir __docs_publication_dir
89+
cp -r docs/pages/api __docs_publication_dir/api
90+
7591
- name: Download artifacts
7692
uses: actions/download-artifact@v4
7793
with:
7894
name: kotlinx-rpc
7995

8096
- name: Unzip artifact
81-
run: unzip -O UTF-8 -qq '${{ env.ARTIFACT }}' -d dir
97+
run: unzip -O UTF-8 -qq '${{ env.ARTIFACT }}' -d __docs_publication_dir
98+
99+
- name: Update sitemap.xml
100+
run: chmod +x updateSitemap.sh && ./updateSitemap.sh __docs_publication_dir/sitemap.xml __docs_publication_dir/api
82101

83102
- name: Setup Pages
84103
uses: actions/configure-pages@v5
85104

86105
- name: Package and upload Pages artifact
87106
uses: actions/upload-pages-artifact@v3
88107
with:
89-
path: dir
108+
path: __docs_publication_dir
90109

91110
- name: Deploy to GitHub Pages
92111
id: deployment

‎.gitignore

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,7 @@ lib-kotlin
1919
!.idea/icon.svg
2020
!.idea/detekt.xml
2121
!.idea/kotlinTestDataPluginTestDataPaths.xml
22+
!.idea/kotlinx-rpc.iml
2223

2324
samples/**/.idea/*
2425

‎.idea/kotlinx-rpc.iml

Lines changed: 12 additions & 0 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎build.gradle.kts

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,22 +3,60 @@
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+
// enable versioning for stable
44+
// versioning {
45+
// version = libDokkaVersion
46+
// olderVersionsDir = dokkaVersionsDirectory
47+
// }
48+
}
49+
50+
dokkaPublications.html {
51+
outputDirectory = dokkaVersionsDirectory
52+
}
53+
54+
dokkaGeneratorIsolation = ProcessIsolation {
55+
// Configures heap size, use if start to fail with OOM on CI
56+
// maxHeapSize = "4g"
57+
}
58+
}
59+
2260
configureProjectReport()
2361
configureNpm()
2462
configureApiValidation()

‎docs/pages/.gitignore

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
api/**

‎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/">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/"/>
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()

‎gradle.properties

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,9 @@ org.gradle.workers.max=6
1616
org.gradle.caching=true
1717
org.gradle.configuration-cache=true
1818

19+
org.jetbrains.dokka.experimental.gradle.pluginMode=V2Enabled
20+
org.jetbrains.dokka.experimental.gradle.pluginMode.noWarn=true
21+
1922
# development mode for kotlinx.rpc gradle plugin. Uses local project paths to apply the compiler plugin
2023
kotlinx.rpc.plugin.internalDevelopment=true
2124

‎updateSitemap.sh

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
#!/bin/bash
2+
3+
#
4+
# Copyright 2023-2025 JetBrains s.r.o and contributors. Use of this source code is governed by the Apache 2.0 license.
5+
#
6+
7+
# Check if the required arguments are provided
8+
if [ -z "$1" ] || [ -z "$2" ]; then
9+
echo "Usage: $0 <sitemap_file> <api_docs_dir>"
10+
echo "Example: $0 sitemap.xml docs/pages/api"
11+
exit 1
12+
fi
13+
14+
sitemap_file=$1
15+
api_docs_dir=$2
16+
17+
# Check if the files/directories exist
18+
if [ ! -f "$sitemap_file" ]; then
19+
echo "Error: Sitemap file '$sitemap_file' does not exist."
20+
exit 1
21+
fi
22+
23+
if [ ! -d "$api_docs_dir" ]; then
24+
echo "Error: API docs directory '$api_docs_dir' does not exist."
25+
exit 1
26+
fi
27+
28+
# Get the current date in YYYY-MM-DD format
29+
current_date=$(date +%Y-%m-%d)
30+
31+
# Create a temporary file to store the updated sitemap
32+
temp_file=$(mktemp)
33+
34+
# Extract the XML header (everything before the closing urlset tag)
35+
sed -n '1,/<\/urlset>/p' "$sitemap_file" | sed '$d' > "$temp_file"
36+
37+
# Find all HTML files in the API docs directory recursively
38+
find "$api_docs_dir" -type f -name "*.html" | while read -r html_file; do
39+
# Convert the file path to a URL path (remove the docs/pages/ prefix)
40+
url_path=$(echo "$html_file" | sed 's|^docs/pages/||')
41+
42+
# Create the full URL
43+
url="https://kotlin.github.io/kotlinx-rpc/$url_path"
44+
45+
# Add the URL entry to the temporary file
46+
cat >> "$temp_file" << EOF
47+
<url>
48+
<loc>$url</loc>
49+
<lastmod>$current_date</lastmod>
50+
<changefreq>monthly</changefreq>
51+
<priority>0.35</priority>
52+
</url>
53+
EOF
54+
done
55+
56+
# Add the closing tag
57+
echo "</urlset>" >> "$temp_file"
58+
59+
# Replace the original sitemap file with the updated one
60+
mv "$temp_file" "$sitemap_file"
61+
62+
echo "Sitemap updated successfully with entries from $api_docs_dir"

‎versions-root/libs.versions.toml

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,7 @@ intellij = "233.13135.128"
2222
gradle-doctor = "0.10.0"
2323
kotlinx-browser = "0.3"
2424
shadow-jar = "9.0.0-beta12"
25+
dokka = "2.0.0"
2526

2627
# Stub versions – relpaced based on kotlin, mostly for gradle-related (plugins) dependencies
2728
# but also for dependencies for compiler-specific modules.
@@ -101,6 +102,7 @@ coroutines-test = { module = "org.jetbrains.kotlinx:kotlinx-coroutines-test", ve
101102
coroutines-debug = { module = "org.jetbrains.kotlinx:kotlinx-coroutines-debug", version.ref = "coroutines" }
102103
detekt-gradle-plugin = { module = "io.gitlab.arturbosch.detekt:detekt-gradle-plugin", version.ref = "detekt-gradle-plugin" }
103104
kover-gradle-plugin = { module = "org.jetbrains.kotlinx:kover-gradle-plugin", version.ref = "kover" }
105+
dokka-gradle-plugin = { module = "org.jetbrains.dokka:dokka-gradle-plugin", version.ref = "dokka" }
104106
binary-compatibility-validator-gradle-plugin = { module = "org.jetbrains.kotlinx:binary-compatibility-validator", version.ref = "binary-compatibility-validator" }
105107
kotlin-js-wrappers = { module = "org.jetbrains.kotlin-wrappers:kotlin-js", version.ref = "kotlin-wrappers" }
106108
gradle-kotlin-dsl-pluigns = { module = "org.gradle.kotlin:gradle-kotlin-dsl-plugins", version.ref = "gradle-kotlin-dsl" }
@@ -120,6 +122,7 @@ gradle-kotlin-dsl = { id = "org.gradle.kotlin.kotlin-dsl", version.ref = "gradle
120122
kover = { id = "org.jetbrains.kotlinx.kover", version.ref = "kover" }
121123
gradle-plugin-publish = { id = "com.gradle.plugin-publish", version.ref = "gradle-plugin-publish" }
122124
shadow-jar = { id = "com.gradleup.shadow", version.ref = "shadow-jar" }
125+
dokka = { id = "org.jetbrains.dokka", version.ref = "dokka" }
123126

124127
# gradle-conventions project
125128
conventions-common = { id = "conventions-common", version.ref = "kotlinx-rpc" }

0 commit comments

Comments
 (0)