From ee46c9468b4c14bbb74aace551e30d463af50408 Mon Sep 17 00:00:00 2001 From: Alexander Sysoev Date: Mon, 16 Jun 2025 23:31:32 +0200 Subject: [PATCH 1/2] Add dokka setup to the repo --- .github/workflows/docs.yml | 23 ++++++- .gitignore | 1 + .idea/kotlinx-rpc.iml | 12 ++++ build.gradle.kts | 54 ++++++++++++++++ docs/pages/.gitignore | 1 + docs/pages/assets/homepage.svg | 20 ++++++ docs/pages/assets/logo-icon.svg | 1 + docs/pages/kotlinx-rpc/cfg/buildprofiles.xml | 5 +- docs/pages/kotlinx-rpc/rpc.tree | 1 + docs/pages/templates/includes/header.ftl | 45 ++++++++++++++ gradle-conventions/common/build.gradle.kts | 1 + .../common/src/main/kotlin/util/dokka.kt | 59 ++++++++++++++++++ .../main/kotlin/conventions-jvm.gradle.kts | 3 + .../main/kotlin/conventions-kmp.gradle.kts | 3 + gradle.properties | 3 + updateSitemap.sh | 62 +++++++++++++++++++ versions-root/libs.versions.toml | 3 + 17 files changed, 293 insertions(+), 4 deletions(-) create mode 100644 .idea/kotlinx-rpc.iml create mode 100644 docs/pages/.gitignore create mode 100644 docs/pages/assets/homepage.svg create mode 100644 docs/pages/assets/logo-icon.svg create mode 100644 docs/pages/templates/includes/header.ftl create mode 100644 gradle-conventions/common/src/main/kotlin/util/dokka.kt create mode 100644 updateSitemap.sh diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 9cf45d740..ca8eceaeb 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -72,13 +72,32 @@ 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 @@ -86,7 +105,7 @@ jobs: - 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 diff --git a/.gitignore b/.gitignore index 3835c0d6b..493901d14 100644 --- a/.gitignore +++ b/.gitignore @@ -19,6 +19,7 @@ lib-kotlin !.idea/icon.svg !.idea/detekt.xml !.idea/kotlinTestDataPluginTestDataPaths.xml +!.idea/kotlinx-rpc.iml samples/**/.idea/* diff --git a/.idea/kotlinx-rpc.iml b/.idea/kotlinx-rpc.iml new file mode 100644 index 000000000..c707b91ac --- /dev/null +++ b/.idea/kotlinx-rpc.iml @@ -0,0 +1,12 @@ + + + + + + + + + + + + diff --git a/build.gradle.kts b/build.gradle.kts index 74f2a63d3..c6a4d57df 100644 --- a/build.gradle.kts +++ b/build.gradle.kts @@ -3,22 +3,76 @@ */ 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" + } +} + configureProjectReport() configureNpm() configureApiValidation() diff --git a/docs/pages/.gitignore b/docs/pages/.gitignore new file mode 100644 index 000000000..d455b18d1 --- /dev/null +++ b/docs/pages/.gitignore @@ -0,0 +1 @@ +api/** diff --git a/docs/pages/assets/homepage.svg b/docs/pages/assets/homepage.svg new file mode 100644 index 000000000..809511c47 --- /dev/null +++ b/docs/pages/assets/homepage.svg @@ -0,0 +1,20 @@ + + + + Back to docs + + + diff --git a/docs/pages/assets/logo-icon.svg b/docs/pages/assets/logo-icon.svg new file mode 100644 index 000000000..653ae4dca --- /dev/null +++ b/docs/pages/assets/logo-icon.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/pages/kotlinx-rpc/cfg/buildprofiles.xml b/docs/pages/kotlinx-rpc/cfg/buildprofiles.xml index b3599e0a3..1daedb4f2 100644 --- a/docs/pages/kotlinx-rpc/cfg/buildprofiles.xml +++ b/docs/pages/kotlinx-rpc/cfg/buildprofiles.xml @@ -22,7 +22,7 @@ %docs-raw-path%/help-versions.json - https://www.jetbrains.com/help/ + %host% MMA5Z3JT91 prod_kotlin_rpc @@ -37,8 +37,9 @@
- 2000-2024 JetBrains s.r.o. + 2000-2025 JetBrains s.r.o. Contribute to kotlinx.rpc Slack Community + API Reference
diff --git a/docs/pages/kotlinx-rpc/rpc.tree b/docs/pages/kotlinx-rpc/rpc.tree index aab8e8679..409749758 100644 --- a/docs/pages/kotlinx-rpc/rpc.tree +++ b/docs/pages/kotlinx-rpc/rpc.tree @@ -49,4 +49,5 @@ + diff --git a/docs/pages/templates/includes/header.ftl b/docs/pages/templates/includes/header.ftl new file mode 100644 index 000000000..c0d3cba02 --- /dev/null +++ b/docs/pages/templates/includes/header.ftl @@ -0,0 +1,45 @@ +<#import "source_set_selector.ftl" as source_set_selector> +<#macro display> + + diff --git a/gradle-conventions/common/build.gradle.kts b/gradle-conventions/common/build.gradle.kts index 846533eca..f085f7462 100644 --- a/gradle-conventions/common/build.gradle.kts +++ b/gradle-conventions/common/build.gradle.kts @@ -13,6 +13,7 @@ dependencies { api(libs.kotlin.gradle.plugin) api(libs.detekt.gradle.plugin) + api(libs.dokka.gradle.plugin) api(libs.binary.compatibility.validator.gradle.plugin) if (isLatestKotlinVersion) { diff --git a/gradle-conventions/common/src/main/kotlin/util/dokka.kt b/gradle-conventions/common/src/main/kotlin/util/dokka.kt new file mode 100644 index 000000000..0db5c849b --- /dev/null +++ b/gradle-conventions/common/src/main/kotlin/util/dokka.kt @@ -0,0 +1,59 @@ +/* + * Copyright 2023-2025 JetBrains s.r.o and contributors. Use of this source code is governed by the Apache 2.0 license. + */ + +package util + +import org.gradle.api.Project +import org.gradle.api.plugins.ExtensionAware +import org.gradle.kotlin.dsl.configure +import org.jetbrains.dokka.gradle.DokkaExtension +import org.jetbrains.dokka.gradle.engine.parameters.VisibilityModifier +import org.jetbrains.dokka.gradle.engine.plugins.DokkaHtmlPluginParameters +import java.time.Year + +fun String.asDokkaVersion() = removeSuffix("-SNAPSHOT") + +fun Project.applyDokka() { + if (!isPublicModule) { + return + } + + plugins.apply(libs.plugins.dokka.get().pluginId) + + configure { + pluginsConfiguration.apply { + (this as ExtensionAware).extensions.configure { + footerMessage.set("© ${Year.now()} JetBrains s.r.o and contributors. Apache License 2.0") + } + } + + moduleName.set("$KOTLINX_RPC_PREFIX-${project.name}") + + dokkaSourceSets.configureEach { + sourceLink { + localDirectory.set(rootDir) + remoteUrl("https://github.com/Kotlin/kotlinx-rpc/blob/${libs.versions.kotlinx.rpc.get().asDokkaVersion()}") + remoteLineSuffix.set("#L") + + documentedVisibilities.set( + setOf( + VisibilityModifier.Public, + VisibilityModifier.Protected, + ) + ) + } + } + + dokkaPublications.configureEach { + suppressObviousFunctions.set(true) + failOnWarning.set(true) + } + } + + val thisProject = project + + rootProject.configurations.matching { it.name == "dokka" }.all { + rootProject.dependencies.add("dokka", thisProject) + } +} diff --git a/gradle-conventions/src/main/kotlin/conventions-jvm.gradle.kts b/gradle-conventions/src/main/kotlin/conventions-jvm.gradle.kts index 1e02cada8..72c3e1130 100644 --- a/gradle-conventions/src/main/kotlin/conventions-jvm.gradle.kts +++ b/gradle-conventions/src/main/kotlin/conventions-jvm.gradle.kts @@ -5,6 +5,7 @@ import org.jetbrains.kotlin.gradle.dsl.KotlinJvmProjectExtension import util.configureJvm import util.optInForRpcApi +import util.applyDokka plugins { id("conventions-common") @@ -26,3 +27,5 @@ configure { } configureJvm(isKmp = false) + +applyDokka() diff --git a/gradle-conventions/src/main/kotlin/conventions-kmp.gradle.kts b/gradle-conventions/src/main/kotlin/conventions-kmp.gradle.kts index 1c26e2cf5..d946a54fb 100644 --- a/gradle-conventions/src/main/kotlin/conventions-kmp.gradle.kts +++ b/gradle-conventions/src/main/kotlin/conventions-kmp.gradle.kts @@ -4,6 +4,7 @@ import org.jetbrains.kotlin.gradle.dsl.KotlinMultiplatformExtension import util.* +import util.applyDokka plugins { id("conventions-common") @@ -23,3 +24,5 @@ withKotlinConfig { } configureJvm(isKmp = true) + +applyDokka() diff --git a/gradle.properties b/gradle.properties index af680ec82..2c1780cb5 100644 --- a/gradle.properties +++ b/gradle.properties @@ -16,6 +16,9 @@ org.gradle.workers.max=6 org.gradle.caching=true org.gradle.configuration-cache=true +org.jetbrains.dokka.experimental.gradle.pluginMode=V2Enabled +org.jetbrains.dokka.experimental.gradle.pluginMode.noWarn=true + # development mode for kotlinx.rpc gradle plugin. Uses local project paths to apply the compiler plugin kotlinx.rpc.plugin.internalDevelopment=true diff --git a/updateSitemap.sh b/updateSitemap.sh new file mode 100644 index 000000000..779e7da41 --- /dev/null +++ b/updateSitemap.sh @@ -0,0 +1,62 @@ +#!/bin/bash + +# +# Copyright 2023-2025 JetBrains s.r.o and contributors. Use of this source code is governed by the Apache 2.0 license. +# + +# Check if the required arguments are provided +if [ -z "$1" ] || [ -z "$2" ]; then + echo "Usage: $0 " + echo "Example: $0 sitemap.xml docs/pages/api" + exit 1 +fi + +sitemap_file=$1 +api_docs_dir=$2 + +# Check if the files/directories exist +if [ ! -f "$sitemap_file" ]; then + echo "Error: Sitemap file '$sitemap_file' does not exist." + exit 1 +fi + +if [ ! -d "$api_docs_dir" ]; then + echo "Error: API docs directory '$api_docs_dir' does not exist." + exit 1 +fi + +# Get the current date in YYYY-MM-DD format +current_date=$(date +%Y-%m-%d) + +# Create a temporary file to store the updated sitemap +temp_file=$(mktemp) + +# Extract the XML header (everything before the closing urlset tag) +sed -n '1,/<\/urlset>/p' "$sitemap_file" | sed '$d' > "$temp_file" + +# Find all HTML files in the API docs directory recursively +find "$api_docs_dir" -type f -name "*.html" | while read -r html_file; do + # Convert the file path to a URL path (remove the docs/pages/ prefix) + url_path=$(echo "$html_file" | sed 's|^docs/pages/||') + + # Create the full URL + url="https://kotlin.github.io/kotlinx-rpc/$url_path" + + # Add the URL entry to the temporary file + cat >> "$temp_file" << EOF + + $url + $current_date + monthly + 0.35 + +EOF +done + +# Add the closing tag +echo "" >> "$temp_file" + +# Replace the original sitemap file with the updated one +mv "$temp_file" "$sitemap_file" + +echo "Sitemap updated successfully with entries from $api_docs_dir" diff --git a/versions-root/libs.versions.toml b/versions-root/libs.versions.toml index b43272bb1..fb0ab0ce6 100644 --- a/versions-root/libs.versions.toml +++ b/versions-root/libs.versions.toml @@ -22,6 +22,7 @@ intellij = "233.13135.128" gradle-doctor = "0.10.0" kotlinx-browser = "0.3" shadow-jar = "9.0.0-beta12" +dokka = "2.0.0" # Stub versions – relpaced based on kotlin, mostly for gradle-related (plugins) dependencies # but also for dependencies for compiler-specific modules. @@ -101,6 +102,7 @@ coroutines-test = { module = "org.jetbrains.kotlinx:kotlinx-coroutines-test", ve coroutines-debug = { module = "org.jetbrains.kotlinx:kotlinx-coroutines-debug", version.ref = "coroutines" } detekt-gradle-plugin = { module = "io.gitlab.arturbosch.detekt:detekt-gradle-plugin", version.ref = "detekt-gradle-plugin" } kover-gradle-plugin = { module = "org.jetbrains.kotlinx:kover-gradle-plugin", version.ref = "kover" } +dokka-gradle-plugin = { module = "org.jetbrains.dokka:dokka-gradle-plugin", version.ref = "dokka" } binary-compatibility-validator-gradle-plugin = { module = "org.jetbrains.kotlinx:binary-compatibility-validator", version.ref = "binary-compatibility-validator" } kotlin-js-wrappers = { module = "org.jetbrains.kotlin-wrappers:kotlin-js", version.ref = "kotlin-wrappers" } 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 kover = { id = "org.jetbrains.kotlinx.kover", version.ref = "kover" } gradle-plugin-publish = { id = "com.gradle.plugin-publish", version.ref = "gradle-plugin-publish" } shadow-jar = { id = "com.gradleup.shadow", version.ref = "shadow-jar" } +dokka = { id = "org.jetbrains.dokka", version.ref = "dokka" } # gradle-conventions project conventions-common = { id = "conventions-common", version.ref = "kotlinx-rpc" } From a52db724b9f3c251bde84df97d1349177f6a629e Mon Sep 17 00:00:00 2001 From: Alexander Sysoev Date: Tue, 24 Jun 2025 14:54:35 +0200 Subject: [PATCH 2/2] Added dokka plugin for removal of internal declarations --- build.gradle.kts | 4 ++ dokka-plugin/build.gradle.kts | 32 +++++++++++++ dokka-plugin/settings.gradle.kts | 18 +++++++ .../rpc/dokka/AddDocsLinkPageTransformer.kt | 13 +++++ .../dokka/HideInternalRpcApiTransformer.kt | 31 ++++++++++++ .../kotlinx/rpc/dokka/RpcDokkaPlugin.kt | 25 ++++++++++ ...rg.jetbrains.dokka.plugability.DokkaPlugin | 5 ++ .../rpc/dokka/HideInternalRpcApiPluginTest.kt | 47 +++++++++++++++++++ .../common/src/main/kotlin/util/dokka.kt | 2 + settings.gradle.kts | 1 + versions-root/libs.versions.toml | 3 ++ 11 files changed, 181 insertions(+) create mode 100644 dokka-plugin/build.gradle.kts create mode 100644 dokka-plugin/settings.gradle.kts create mode 100644 dokka-plugin/src/main/kotlin/kotlinx/rpc/dokka/AddDocsLinkPageTransformer.kt create mode 100644 dokka-plugin/src/main/kotlin/kotlinx/rpc/dokka/HideInternalRpcApiTransformer.kt create mode 100644 dokka-plugin/src/main/kotlin/kotlinx/rpc/dokka/RpcDokkaPlugin.kt create mode 100644 dokka-plugin/src/main/resources/META-INF/services/org.jetbrains.dokka.plugability.DokkaPlugin create mode 100644 dokka-plugin/src/test/kotlin/kotlinx/rpc/dokka/HideInternalRpcApiPluginTest.kt diff --git a/build.gradle.kts b/build.gradle.kts index c6a4d57df..c82f21ac3 100644 --- a/build.gradle.kts +++ b/build.gradle.kts @@ -73,6 +73,10 @@ dokka { } } +dependencies { + dokkaPlugin(libs.dokka.rpc.plugin) +} + configureProjectReport() configureNpm() configureApiValidation() diff --git a/dokka-plugin/build.gradle.kts b/dokka-plugin/build.gradle.kts new file mode 100644 index 000000000..fa98a2889 --- /dev/null +++ b/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()}") +} diff --git a/dokka-plugin/settings.gradle.kts b/dokka-plugin/settings.gradle.kts new file mode 100644 index 000000000..42d761a1f --- /dev/null +++ b/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") +} diff --git a/dokka-plugin/src/main/kotlin/kotlinx/rpc/dokka/AddDocsLinkPageTransformer.kt b/dokka-plugin/src/main/kotlin/kotlinx/rpc/dokka/AddDocsLinkPageTransformer.kt new file mode 100644 index 000000000..55d6ce4fb --- /dev/null +++ b/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 +} diff --git a/dokka-plugin/src/main/kotlin/kotlinx/rpc/dokka/HideInternalRpcApiTransformer.kt b/dokka-plugin/src/main/kotlin/kotlinx/rpc/dokka/HideInternalRpcApiTransformer.kt new file mode 100644 index 000000000..0aa61c666 --- /dev/null +++ b/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 = + (d as? WithExtraProperties<*>) + ?.extra + ?.allOfType() + ?.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" + } +} diff --git a/dokka-plugin/src/main/kotlin/kotlinx/rpc/dokka/RpcDokkaPlugin.kt b/dokka-plugin/src/main/kotlin/kotlinx/rpc/dokka/RpcDokkaPlugin.kt new file mode 100644 index 000000000..93f4c9b47 --- /dev/null +++ b/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().preMergeDocumentableTransformer providing ::HideInternalRpcApiTransformer + } + + val pageTransformer by extending { + CoreExtensions.pageTransformer providing ::AddDocsLinkPageTransformer + } +} diff --git a/dokka-plugin/src/main/resources/META-INF/services/org.jetbrains.dokka.plugability.DokkaPlugin b/dokka-plugin/src/main/resources/META-INF/services/org.jetbrains.dokka.plugability.DokkaPlugin new file mode 100644 index 000000000..23d42d646 --- /dev/null +++ b/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 diff --git a/dokka-plugin/src/test/kotlin/kotlinx/rpc/dokka/HideInternalRpcApiPluginTest.kt b/dokka-plugin/src/test/kotlin/kotlinx/rpc/dokka/HideInternalRpcApiPluginTest.kt new file mode 100644 index 000000000..00da60659 --- /dev/null +++ b/dokka-plugin/src/test/kotlin/kotlinx/rpc/dokka/HideInternalRpcApiPluginTest.kt @@ -0,0 +1,47 @@ +/* + * 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.testApi.testRunner.BaseAbstractTest +import kotlin.test.Test +import kotlin.test.assertEquals + +class HideInternalRpcApiPluginTest : BaseAbstractTest() { + @Test + fun `should hide annotated functions`() { + val configuration = dokkaConfiguration { + sourceSets { + sourceSet { + sourceRoots = listOf("src/main/kotlin/basic/Test.kt") + } + } + } + + testInline( + """ + |/src/main/kotlin/basic/Test.kt + |package kotlinx.rpc.internal.utils + | + |annotation class InternalRpcApi + | + |fun shouldBeVisible() {} + | + |@InternalRpcApi + |fun shouldBeExcludedFromDocumentation() {} + """.trimMargin(), + configuration = configuration, + pluginOverrides = listOf(RpcDokkaPlugin()) + ) { + preMergeDocumentablesTransformationStage = { modules -> + val testModule = modules.single { it.name == "root" } + val testPackage = testModule.packages.single { it.name == "kotlinx.rpc.internal.utils" } + + val packageFunctions = testPackage.functions + assertEquals(1, packageFunctions.size) + assertEquals("shouldBeVisible", packageFunctions[0].name) + } + } + } +} diff --git a/gradle-conventions/common/src/main/kotlin/util/dokka.kt b/gradle-conventions/common/src/main/kotlin/util/dokka.kt index 0db5c849b..af2a73c69 100644 --- a/gradle-conventions/common/src/main/kotlin/util/dokka.kt +++ b/gradle-conventions/common/src/main/kotlin/util/dokka.kt @@ -51,6 +51,8 @@ fun Project.applyDokka() { } } + dependencies.add("dokkaPlugin", libs.dokka.rpc.plugin) + val thisProject = project rootProject.configurations.matching { it.name == "dokka" }.all { diff --git a/settings.gradle.kts b/settings.gradle.kts index 739a57188..0656e77f7 100644 --- a/settings.gradle.kts +++ b/settings.gradle.kts @@ -32,6 +32,7 @@ plugins { dependencyResolutionManagement { includeBuild("compiler-plugin") + includeBuild("dokka-plugin") } includePublic(":bom") diff --git a/versions-root/libs.versions.toml b/versions-root/libs.versions.toml index fb0ab0ce6..598002f50 100644 --- a/versions-root/libs.versions.toml +++ b/versions-root/libs.versions.toml @@ -102,7 +102,10 @@ coroutines-test = { module = "org.jetbrains.kotlinx:kotlinx-coroutines-test", ve coroutines-debug = { module = "org.jetbrains.kotlinx:kotlinx-coroutines-debug", version.ref = "coroutines" } detekt-gradle-plugin = { module = "io.gitlab.arturbosch.detekt:detekt-gradle-plugin", version.ref = "detekt-gradle-plugin" } kover-gradle-plugin = { module = "org.jetbrains.kotlinx:kover-gradle-plugin", version.ref = "kover" } +dokka-core = { module = "org.jetbrains.dokka:dokka-core", version.ref = "dokka" } +dokka-base = { module = "org.jetbrains.dokka:dokka-base", version.ref = "dokka" } dokka-gradle-plugin = { module = "org.jetbrains.dokka:dokka-gradle-plugin", version.ref = "dokka" } +dokka-rpc-plugin = { module = "org.jetbrains.kotlinx:dokka-rpc-plugin", version.ref = "kotlinx-rpc" } binary-compatibility-validator-gradle-plugin = { module = "org.jetbrains.kotlinx:binary-compatibility-validator", version.ref = "binary-compatibility-validator" } kotlin-js-wrappers = { module = "org.jetbrains.kotlin-wrappers:kotlin-js", version.ref = "kotlin-wrappers" } gradle-kotlin-dsl-pluigns = { module = "org.gradle.kotlin:gradle-kotlin-dsl-plugins", version.ref = "gradle-kotlin-dsl" }