Dokka

.github/workflows/docs.yml

@@ -72,21 +72,40 @@ jobs:
     needs: [ build, test ]
     runs-on: ubuntu-latest
     steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup Gradle
+        uses: gradle/actions/setup-gradle@v3
+
+      - name: Run Dokka
+        run: ./gradlew dokkaGenerate
+
+      - name: Move API docs to the publication directory
+        run:
+          mkdir __docs_publication_dir
+          cp -r docs/pages/api __docs_publication_dir/api
+
       - name: Download artifacts
         uses: actions/download-artifact@v4
         with:
           name: kotlinx-rpc
 
       - name: Unzip artifact
-        run: unzip -O UTF-8 -qq '${{ env.ARTIFACT }}' -d dir
+        run: unzip -O UTF-8 -qq '${{ env.ARTIFACT }}' -d __docs_publication_dir
+
+      - name: Update sitemap.xml
+        run: chmod +x updateSitemap.sh && ./updateSitemap.sh __docs_publication_dir/sitemap.xml __docs_publication_dir/api
 
       - name: Setup Pages
         uses: actions/configure-pages@v5
 
       - name: Package and upload Pages artifact
         uses: actions/upload-pages-artifact@v3
         with:
-          path: dir
+          path: __docs_publication_dir
 
       - name: Deploy to GitHub Pages
         id: deployment

.gitignore

@@ -19,6 +19,7 @@ lib-kotlin
 !.idea/icon.svg
 !.idea/detekt.xml
 !.idea/kotlinTestDataPluginTestDataPaths.xml
+!.idea/kotlinx-rpc.iml
 
 samples/**/.idea/*
 

build.gradle.kts

@@ -3,22 +3,80 @@
  */
 
 import org.jetbrains.kotlin.gradle.plugin.getKotlinPluginVersion
+import util.asDokkaVersion
 import util.configureApiValidation
 import util.configureNpm
 import util.configureProjectReport
 import util.registerDumpPlatformTableTask
 import util.libs
 import util.registerVerifyPlatformTableTask
+import java.time.Year
 
 plugins {
     alias(libs.plugins.serialization) apply false
     alias(libs.plugins.kotlinx.rpc) apply false
     alias(libs.plugins.conventions.kover)
     alias(libs.plugins.conventions.gradle.doctor)
+    alias(libs.plugins.dokka)
     alias(libs.plugins.atomicfu)
     id("build-util")
 }
 
+dokka {
+    val libDokkaVersion = libs.versions.kotlinx.rpc.get().asDokkaVersion()
+
+    moduleVersion.set(libDokkaVersion)
+
+    val pagesDirectory = layout.projectDirectory
+        .dir("docs")
+        .dir("pages")
+
+    val dokkaVersionsDirectory = pagesDirectory
+        .dir("api")
+        .asFile
+
+    val templatesDirectory = pagesDirectory
+        .dir("templates")
+
+    pluginsConfiguration {
+        html {
+            customAssets.from(
+                "docs/pages/assets/logo-icon.svg",
+                "docs/pages/assets/homepage.svg", // Doesn't work due to https://github.com/Kotlin/dokka/issues/4007
+            )
+
+            footerMessage = "© ${Year.now()} JetBrains s.r.o and contributors. Apache License 2.0"
+            homepageLink = "https://kotlin.github.io/kotlinx-rpc/get-started.html"
+
+            // replace with homepage.svg once the mentioned issue is resolved
+            templatesDir.set(templatesDirectory)
+        }
+
+        // enable versioning for stable
+//        versioning {
+//            version = libDokkaVersion
+//            olderVersionsDir = dokkaVersionsDirectory
+//        }
+    }
+
+    dokkaPublications.html {
+        outputDirectory = dokkaVersionsDirectory
+    }
+
+    tasks.clean {
+        delete(dokkaVersionsDirectory)
+    }
+
+    dokkaGeneratorIsolation = ProcessIsolation {
+        // Configures heap size, use if start to fail with OOM on CI
+//        maxHeapSize = "4g"
+    }
+}
+
+dependencies {
+    dokkaPlugin(libs.dokka.rpc.plugin)
+}
+
 configureProjectReport()
 configureNpm()
 configureApiValidation()

docs/pages/.gitignore

@@ -0,0 +1 @@
+api/**

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

@@ -22,7 +22,7 @@
 
         <versions-switcher>%docs-raw-path%/help-versions.json</versions-switcher>
 
-        <generate-sitemap-url-prefix>https://www.jetbrains.com/help/</generate-sitemap-url-prefix>
+        <generate-sitemap-url-prefix>%host%</generate-sitemap-url-prefix>
 
         <algolia-id>MMA5Z3JT91</algolia-id>
         <algolia-index>prod_kotlin_rpc</algolia-index>
@@ -37,8 +37,9 @@
 
     <sitemap priority="0.35" change-frequency="monthly"/>
     <footer>
-        <copyright>2000-2024 JetBrains s.r.o.</copyright>
+        <copyright>2000-2025 JetBrains s.r.o.</copyright>
         <link href="https://github.com/Kotlin/kotlinx-rpc/blob/main/CONTRIBUTING.md">Contribute to kotlinx.rpc</link>
         <link href="https://kotlinlang.slack.com/archives/C072YJ3Q91V">Slack Community</link>
+        <link href="%host%/api/">API Reference</link>
     </footer>
 </buildprofiles>

docs/pages/kotlinx-rpc/rpc.tree

@@ -49,4 +49,5 @@
         <toc-element topic="0-2-4.topic"/>
         <toc-element topic="0-2-1.topic"/>
     </toc-element>
+    <toc-element toc-title="API Reference" href="%host%/api/"/>
 </instance-profile>

docs/pages/templates/includes/header.ftl

@@ -0,0 +1,45 @@
+<#import "source_set_selector.ftl" as source_set_selector>
+<#macro display>
+    <header class="navigation theme-dark" id="navigation-wrapper" role="banner">
+        <@template_cmd name="pathToRoot">
+            <a class="library-name--link" href="${pathToRoot}index.html" tabindex="1">
+                <@template_cmd name="projectName">
+                    ${projectName}
+                </@template_cmd>
+            </a>
+        </@template_cmd>
+        <button class="navigation-controls--btn navigation-controls--btn_toc ui-kit_mobile-only" id="toc-toggle"
+                type="button">Toggle table of contents
+        </button>
+        <div class="navigation-controls--break ui-kit_mobile-only"></div>
+        <div class="library-version" id="library-version">
+            <#-- This can be handled by the versioning plugin -->
+            <@version/>
+        </div>
+        <div class="navigation-controls">
+            <@source_set_selector.display/>
+            <#if homepageLink?has_content>
+                <a class="navigation-controls--btn" id="homepage-link" href="${homepageLink}"
+                   style="width: fit-content; padding-left: 10px;">
+                    <p style="color: var(--color-text-dt); font: var(--font-text-m); ">Back to docs</p>
+                    <div class="navigation-controls--btn_homepage"
+                         style="
+                            height: 40px;
+                            width: 40px;
+                            background-color: transparent;
+                            background-repeat: no-repeat;
+                            background-position: 50% 50%;
+                            background-size: 24px 24px;
+                        ">
+                    </div>
+                </a>
+            </#if>
+            <button class="navigation-controls--btn navigation-controls--btn_theme" id="theme-toggle-button"
+                    type="button">Switch theme
+            </button>
+            <div class="navigation-controls--btn navigation-controls--btn_search" id="searchBar" role="button">Search in
+                API
+            </div>
+        </div>
+    </header>
+</#macro>

dokka-plugin/build.gradle.kts

@@ -0,0 +1,32 @@
+/*
+ * Copyright 2023-2025 JetBrains s.r.o and contributors. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+plugins {
+    alias(libs.plugins.conventions.gradle.doctor)
+    id("build-util")
+    alias(libs.plugins.kotlin.jvm)
+}
+
+val rpcVersion: String = libs.versions.kotlinx.rpc.get()
+val kotlinLangVersion = libs.versions.kotlin.lang.get()
+
+group = "org.jetbrains.kotlinx"
+version = rpcVersion
+
+println("[Dokka Plugin] kotlinx.rpc project version: $version, Kotlin version: $kotlinLangVersion")
+
+kotlin {
+    jvmToolchain(8)
+}
+
+dependencies {
+    compileOnly(libs.dokka.core)
+    compileOnly(libs.dokka.base)
+
+    testImplementation(kotlin("test"))
+    testImplementation(libs.dokka.base)
+    testImplementation("org.jetbrains.dokka:dokka-test-api:${libs.versions.dokka.get()}")
+    testImplementation("org.jetbrains.dokka:dokka-base-test-utils:${libs.versions.dokka.get()}")
+    testImplementation("org.jetbrains.dokka:analysis-kotlin-symbols:${libs.versions.dokka.get()}")
+}

dokka-plugin/settings.gradle.kts

@@ -0,0 +1,18 @@
+/*
+ * Copyright 2023-2024 JetBrains s.r.o and contributors. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+rootProject.name = "dokka-rpc-plugin"
+
+enableFeaturePreview("TYPESAFE_PROJECT_ACCESSORS")
+
+pluginManagement {
+    includeBuild("../gradle-conventions")
+    includeBuild("../gradle-conventions-settings")
+}
+
+plugins {
+    id("conventions-repositories")
+    id("conventions-version-resolution")
+    id("conventions-develocity")
+}

dokka-plugin/src/main/kotlin/kotlinx/rpc/dokka/AddDocsLinkPageTransformer.kt

@@ -0,0 +1,13 @@
+/*
+ * Copyright 2023-2025 JetBrains s.r.o and contributors. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+package kotlinx.rpc.dokka
+
+import org.jetbrains.dokka.pages.RootPageNode
+import org.jetbrains.dokka.plugability.DokkaContext
+import org.jetbrains.dokka.transformers.pages.PageTransformer
+
+class AddDocsLinkPageTransformer(private val context: DokkaContext) : PageTransformer {
+    override fun invoke(input: RootPageNode): RootPageNode = input
+}

dokka-plugin/src/main/kotlin/kotlinx/rpc/dokka/HideInternalRpcApiTransformer.kt

@@ -0,0 +1,31 @@
+/*
+ * Copyright 2023-2025 JetBrains s.r.o and contributors. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+package kotlinx.rpc.dokka
+
+import org.jetbrains.dokka.base.DokkaBaseConfiguration
+import org.jetbrains.dokka.base.transformers.documentables.SuppressedByConditionDocumentableFilterTransformer
+import org.jetbrains.dokka.model.Annotations
+import org.jetbrains.dokka.model.Documentable
+import org.jetbrains.dokka.model.properties.WithExtraProperties
+import org.jetbrains.dokka.plugability.DokkaContext
+
+class HideInternalRpcApiTransformer(context: DokkaContext) : SuppressedByConditionDocumentableFilterTransformer(context) {
+    override fun shouldBeSuppressed(d: Documentable): Boolean {
+        DokkaBaseConfiguration
+        val annotations: List<Annotations.Annotation> =
+            (d as? WithExtraProperties<*>)
+                ?.extra
+                ?.allOfType<Annotations>()
+                ?.flatMap { it.directAnnotations.values.flatten() }
+                ?: emptyList()
+
+        return annotations.any { isInternalRpcAnnotation(it) }
+    }
+
+    private fun isInternalRpcAnnotation(annotation: Annotations.Annotation): Boolean {
+        return annotation.dri.packageName == "kotlinx.rpc.internal.utils"
+                && annotation.dri.classNames == "InternalRpcApi"
+    }
+}

dokka-plugin/src/main/kotlin/kotlinx/rpc/dokka/RpcDokkaPlugin.kt

@@ -0,0 +1,25 @@
+/*
+ * Copyright 2023-2025 JetBrains s.r.o and contributors. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+package kotlinx.rpc.dokka
+
+import org.jetbrains.dokka.CoreExtensions
+import org.jetbrains.dokka.base.DokkaBase
+import org.jetbrains.dokka.plugability.DokkaPlugin
+import org.jetbrains.dokka.plugability.DokkaPluginApiPreview
+import org.jetbrains.dokka.plugability.PluginApiPreviewAcknowledgement
+
+@Suppress("unused")
+class RpcDokkaPlugin : DokkaPlugin() {
+    @OptIn(DokkaPluginApiPreview::class)
+    override fun pluginApiPreviewAcknowledgement() = PluginApiPreviewAcknowledgement
+
+    val rpcInternalApiTransformer by extending {
+        plugin<DokkaBase>().preMergeDocumentableTransformer providing ::HideInternalRpcApiTransformer
+    }
+
+    val pageTransformer by extending {
+        CoreExtensions.pageTransformer providing ::AddDocsLinkPageTransformer
+    }
+}

dokka-plugin/src/main/resources/META-INF/services/org.jetbrains.dokka.plugability.DokkaPlugin

@@ -0,0 +1,5 @@
+#
+# Copyright 2023-2025 JetBrains s.r.o and contributors. Use of this source code is governed by the Apache 2.0 license.
+#
+
+kotlinx.rpc.dokka.RpcDokkaPlugin