From 2138732f721ab4dbe89e8ae387adedaeb36d1ac0 Mon Sep 17 00:00:00 2001 From: Matthew Nelson Date: Sun, 15 Dec 2024 14:51:12 -0500 Subject: [PATCH] Add Dokka documentation (#126) --- .gitignore | 3 + .kotlin-js-store/yarn.lock | 68 +++++++++---------- RELEASING.md | 5 ++ build-logic/build.gradle.kts | 1 + .../main/kotlin/-KmpConfigurationExtension.kt | 2 +- build-logic/src/main/kotlin/dokka.gradle.kts | 46 +++++++++++++ build.gradle.kts | 1 + gh-pages/publish.sh | 36 ++++++++++ gradle/libs.versions.toml | 5 +- library/process/README.md | 3 + .../kmp/process/internal/JsEvents.kt | 5 +- .../kmp/process/internal/JsPlatform.kt | 2 + 12 files changed, 140 insertions(+), 37 deletions(-) create mode 100644 build-logic/src/main/kotlin/dokka.gradle.kts create mode 100755 gh-pages/publish.sh create mode 100644 library/process/README.md diff --git a/.gitignore b/.gitignore index 3f18343a..15bdb561 100644 --- a/.gitignore +++ b/.gitignore @@ -32,3 +32,6 @@ google-services.json # Android Profiling *.hprof + +gh-pages/* +!gh-pages/publish.sh diff --git a/.kotlin-js-store/yarn.lock b/.kotlin-js-store/yarn.lock index 5890f9df..6ac1eb19 100644 --- a/.kotlin-js-store/yarn.lock +++ b/.kotlin-js-store/yarn.lock @@ -288,40 +288,40 @@ js-yaml@4.1.0: dependencies: argparse "^2.0.1" -kmp-tor.resource-exec-tor.all@408.12.0: - version "408.12.0" - resolved "https://registry.yarnpkg.com/kmp-tor.resource-exec-tor.all/-/kmp-tor.resource-exec-tor.all-408.12.0.tgz#10c365fb3452ba8f5dd8f5be5a9a68ae8d813d81" - integrity sha512-mproBhkmswFep755NswyxBwQjBu+Trn8eML2oTXq+6z3fdu1n+fPhhnoak1gWJOTIizLpxnvO5hHHmH0ag3cOg== - dependencies: - kmp-tor.resource-exec-tor.linux-android "408.12.0" - kmp-tor.resource-exec-tor.linux-libc "408.12.0" - kmp-tor.resource-exec-tor.macos "408.12.0" - kmp-tor.resource-exec-tor.mingw "408.12.0" - -kmp-tor.resource-exec-tor.linux-android@408.12.0: - version "408.12.0" - resolved "https://registry.yarnpkg.com/kmp-tor.resource-exec-tor.linux-android/-/kmp-tor.resource-exec-tor.linux-android-408.12.0.tgz#55cb915f8976ae53c965b91e1e81338c769814b4" - integrity sha512-T6uSnvpr7woLt86V1rYElLS1t6cVX4Uzvq2K3twlScI9WvrKNk+8579eLB63uYIRmT8XG+65mqp2uZqy4rIiNg== - -kmp-tor.resource-exec-tor.linux-libc@408.12.0: - version "408.12.0" - resolved "https://registry.yarnpkg.com/kmp-tor.resource-exec-tor.linux-libc/-/kmp-tor.resource-exec-tor.linux-libc-408.12.0.tgz#174247250eec49b94ff53d23328c0be823cd1fc2" - integrity sha512-bhRQAK/+z9xtyeKWdVNdcLbothr4qRyhAcTsuJEVhS1rMUo0nfQ+ScbJUoE4LDDXQCg0kiZE3qPK6qZxk1DuCw== - -kmp-tor.resource-exec-tor.macos@408.12.0: - version "408.12.0" - resolved "https://registry.yarnpkg.com/kmp-tor.resource-exec-tor.macos/-/kmp-tor.resource-exec-tor.macos-408.12.0.tgz#bdddb7add33af2763da87940a4f234cc42d828a1" - integrity sha512-q45vZwiii9Yu6ql80YezM6E82HSD8Og9vUvGNP+oIr97wnHe6WoAxOk9oaSMMOExi0ZkQG6YXntqfcJS5hj4KQ== - -kmp-tor.resource-exec-tor.mingw@408.12.0: - version "408.12.0" - resolved "https://registry.yarnpkg.com/kmp-tor.resource-exec-tor.mingw/-/kmp-tor.resource-exec-tor.mingw-408.12.0.tgz#5ad4fb58eddcb71207e1ab4b052f9b7b1f8bdc45" - integrity sha512-ycvSEwG7snWCOtfC2jU6mP3n1mTpqFTOyiNjs1FlwYhZRiSDWE+bR0DgZdyRDkwKPlyLioQGbl/x5zjBnS0acw== - -kmp-tor.resource-geoip@408.12.0: - version "408.12.0" - resolved "https://registry.yarnpkg.com/kmp-tor.resource-geoip/-/kmp-tor.resource-geoip-408.12.0.tgz#02c15bb53a174658add7b38dea5d45731535cfbd" - integrity sha512-Sg/mmEo58a6oNo9+W1ygDyIS8KH+1JXTv78Wiyed7D8gIQx4Bn2QXC7jpSH6pN69/OG/CBC7YMRDXTpdACczEA== +kmp-tor.resource-exec-tor.all@408.13.0: + version "408.13.0" + resolved "https://registry.yarnpkg.com/kmp-tor.resource-exec-tor.all/-/kmp-tor.resource-exec-tor.all-408.13.0.tgz#6e37151c29ff286fcf59a34db2b764ab2561dfa7" + integrity sha512-7oOKoAhllo6xP947ygXgulycZBnTnRf9p9/9eLvScwS5AMcR2MTQYjGIL+a+iUXQs4xKTfa9mMCf3Ei8JSJLPg== + dependencies: + kmp-tor.resource-exec-tor.linux-android "408.13.0" + kmp-tor.resource-exec-tor.linux-libc "408.13.0" + kmp-tor.resource-exec-tor.macos "408.13.0" + kmp-tor.resource-exec-tor.mingw "408.13.0" + +kmp-tor.resource-exec-tor.linux-android@408.13.0: + version "408.13.0" + resolved "https://registry.yarnpkg.com/kmp-tor.resource-exec-tor.linux-android/-/kmp-tor.resource-exec-tor.linux-android-408.13.0.tgz#32b39c6c0b41ec8a02aa14aeb46f26648547e817" + integrity sha512-XDOipQAQJxtt41B8bRsk/nGDYJ1ItqFi++xSQKlfSkzZRbfh+ZIjyAWbe+EIOSTe1SzWgKRMGQVTV3Yq0sPSvw== + +kmp-tor.resource-exec-tor.linux-libc@408.13.0: + version "408.13.0" + resolved "https://registry.yarnpkg.com/kmp-tor.resource-exec-tor.linux-libc/-/kmp-tor.resource-exec-tor.linux-libc-408.13.0.tgz#de75df9042ef29408cf417d3a8bec9aea3789859" + integrity sha512-K7E9/bSE85VyeaPjuZVfxWvVzYeEMTFNvmNwnOk/1CeT/gJYgNTkh7OThX2TTmmHGAEGpXYhr22pLA76dxP8Bw== + +kmp-tor.resource-exec-tor.macos@408.13.0: + version "408.13.0" + resolved "https://registry.yarnpkg.com/kmp-tor.resource-exec-tor.macos/-/kmp-tor.resource-exec-tor.macos-408.13.0.tgz#44bc56cbf559c8bed4ab163604ddd7c91f570511" + integrity sha512-JGsd24e4SoMBf5cMYJFAbZG4D66AODG9fCEwdF7xqfjgmsUVmNbzUyR0W3kFeHz4n1AdymnhxcE3kptEhSAGPg== + +kmp-tor.resource-exec-tor.mingw@408.13.0: + version "408.13.0" + resolved "https://registry.yarnpkg.com/kmp-tor.resource-exec-tor.mingw/-/kmp-tor.resource-exec-tor.mingw-408.13.0.tgz#df4e5acf63b2ca14c005aecfe2aa52275597e4e0" + integrity sha512-1Aeyl09Tp+629xFOQlPoULxNEIZlVoY9z/dG4QG270Qmss+QLpaWbHJ1IMIeqzSZmrTg73rvFjLSwuYDm3muSg== + +kmp-tor.resource-geoip@408.13.0: + version "408.13.0" + resolved "https://registry.yarnpkg.com/kmp-tor.resource-geoip/-/kmp-tor.resource-geoip-408.13.0.tgz#57f94a356782c2372a7ba67bd05148b6db0f42eb" + integrity sha512-6lxdb86o7J91sl8qcJn6e/VeGPtbgUG+IPRaw+1gALCTKdpjGpUrKDYY2Nk23bo+DOAGmgg24Pv9nTv9AcH4Jg== locate-path@^6.0.0: version "6.0.0" diff --git a/RELEASING.md b/RELEASING.md index 64d43cdb..c5d4369e 100644 --- a/RELEASING.md +++ b/RELEASING.md @@ -2,4 +2,9 @@ See [KotlinCrypto/documentation/RELEASING.md][url-kotlincrypto-releasing] +Additionally, publish dokka documentation updates +```bash +./gh-pages/publish.sh +``` + [url-kotlincrypto-releasing]: https://github.com/KotlinCrypto/documentation/blob/master/RELEASING.md diff --git a/build-logic/build.gradle.kts b/build-logic/build.gradle.kts index d9f4ef45..010343bb 100644 --- a/build-logic/build.gradle.kts +++ b/build-logic/build.gradle.kts @@ -19,6 +19,7 @@ plugins { dependencies { implementation(libs.gradle.android) + implementation(libs.gradle.dokka) implementation(libs.gradle.kmp.configuration) implementation(libs.gradle.kotlin) implementation(libs.gradle.publish.maven) diff --git a/build-logic/src/main/kotlin/-KmpConfigurationExtension.kt b/build-logic/src/main/kotlin/-KmpConfigurationExtension.kt index 05a1af6b..823ba616 100644 --- a/build-logic/src/main/kotlin/-KmpConfigurationExtension.kt +++ b/build-logic/src/main/kotlin/-KmpConfigurationExtension.kt @@ -71,7 +71,7 @@ fun KmpConfigurationExtension.configureShared( // watchosAll() common { - if (publish) pluginIds("publication") + if (publish) pluginIds("publication", "dokka") sourceSetTest { dependencies { diff --git a/build-logic/src/main/kotlin/dokka.gradle.kts b/build-logic/src/main/kotlin/dokka.gradle.kts new file mode 100644 index 00000000..e1c9bf13 --- /dev/null +++ b/build-logic/src/main/kotlin/dokka.gradle.kts @@ -0,0 +1,46 @@ +/* + * Copyright (c) 2024 Matthew Nelson + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * https://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + **/ +import org.jetbrains.dokka.DokkaConfiguration.Visibility +import org.jetbrains.dokka.gradle.DokkaTaskPartial +import java.net.URI + +plugins { + id("org.jetbrains.dokka") +} + +tasks.withType().configureEach { + suppressInheritedMembers = true + + dokkaSourceSets.configureEach { + includes.from("README.md") + noStdlibLink = true + + externalDocumentationLink { + url = URI("https://kmp-file.matthewnelson.io/").toURL() + } + + sourceLink { + localDirectory = rootDir + remoteUrl = URI("https://github.com/05nelsonm/kmp-process/tree/master").toURL() + remoteLineSuffix = "#L" + } + + documentedVisibilities.set(setOf( + Visibility.PUBLIC, + Visibility.PROTECTED, + )) + } +} diff --git a/build.gradle.kts b/build.gradle.kts index 1b8f4a19..af5b7c03 100644 --- a/build.gradle.kts +++ b/build.gradle.kts @@ -20,6 +20,7 @@ import org.jetbrains.kotlin.gradle.targets.js.yarn.YarnRootExtension plugins { alias(libs.plugins.android.library) apply(false) alias(libs.plugins.binary.compat) + alias(libs.plugins.dokka) alias(libs.plugins.kotlin.multiplatform) apply(false) } diff --git a/gh-pages/publish.sh b/gh-pages/publish.sh new file mode 100755 index 00000000..99cce3f0 --- /dev/null +++ b/gh-pages/publish.sh @@ -0,0 +1,36 @@ +#!/usr/bin/env bash +# Copyright (c) 2024 Matthew Nelson +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# https://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +set -e + +readonly DIR_SCRIPT="$( cd "$( dirname "$0" )" >/dev/null && pwd )" + +trap 'rm -rf "$DIR_SCRIPT/kmp-process"' EXIT + +cd "$DIR_SCRIPT" +git clone -b gh-pages --single-branch https://github.com/05nelsonm/kmp-process.git +rm -rf "$DIR_SCRIPT/kmp-process/"* +echo "kmp-process.matthewnelson.io" > "$DIR_SCRIPT/kmp-process/CNAME" + +cd .. +./gradlew clean -DKMP_TARGETS_ALL +./gradlew dokkaHtmlMultiModule --no-build-cache -DKMP_TARGETS_ALL +cp -aR build/dokka/htmlMultiModule/* gh-pages/kmp-process + +cd "$DIR_SCRIPT/kmp-process" +sed -i "s|module:process|module:library/process|g" "package-list" + +git add --all +git commit -S --message "Update dokka docs" +git push diff --git a/gradle/libs.versions.toml b/gradle/libs.versions.toml index ff76cf21..e6c461f2 100644 --- a/gradle/libs.versions.toml +++ b/gradle/libs.versions.toml @@ -1,6 +1,7 @@ [versions] gradle-android = "8.2.2" gradle-binary-compat = "0.16.3" +gradle-dokka = "1.9.20" gradle-kmp-configuration = "0.3.2" gradle-kotlin = "1.9.24" gradle-publish-maven = "0.29.0" @@ -14,10 +15,11 @@ kotlinx-coroutines = "1.8.1" # tests androidx-test-core = "1.5.0" androidx-test-runner = "1.5.2" -kmp-tor-resource = "408.12.0" +kmp-tor-resource = "408.13.0" [libraries] gradle-android = { module = "com.android.tools.build:gradle", version.ref = "gradle-android" } +gradle-dokka = { module = "org.jetbrains.dokka:dokka-gradle-plugin", version.ref = "gradle-dokka" } gradle-kmp-configuration = { module = "io.matthewnelson:gradle-kmp-configuration-plugin", version.ref = "gradle-kmp-configuration" } gradle-kotlin = { module = "org.jetbrains.kotlin:kotlin-gradle-plugin", version.ref = "gradle-kotlin" } gradle-publish-maven = { module = "com.vanniktech:gradle-maven-publish-plugin", version.ref = "gradle-publish-maven" } @@ -38,4 +40,5 @@ kotlinx-coroutines-test = { module = "org.jetbrains.kotlinx:kotlinx-coroutines-t [plugins] android-library = { id = "com.android.library", version.ref = "gradle-android" } binary-compat = { id = "org.jetbrains.kotlinx.binary-compatibility-validator", version.ref = "gradle-binary-compat" } +dokka = { id = "org.jetbrains.dokka", version.ref = "gradle-dokka" } kotlin-multiplatform = { id = "org.jetbrains.kotlin.multiplatform", version.ref = "gradle-kotlin" } diff --git a/library/process/README.md b/library/process/README.md new file mode 100644 index 00000000..44228fed --- /dev/null +++ b/library/process/README.md @@ -0,0 +1,3 @@ +# Module process + +`Process` implementation for Kotlin Multiplatform. diff --git a/library/process/src/jsMain/kotlin/io/matthewnelson/kmp/process/internal/JsEvents.kt b/library/process/src/jsMain/kotlin/io/matthewnelson/kmp/process/internal/JsEvents.kt index ac8aa7e0..226c7ef7 100644 --- a/library/process/src/jsMain/kotlin/io/matthewnelson/kmp/process/internal/JsEvents.kt +++ b/library/process/src/jsMain/kotlin/io/matthewnelson/kmp/process/internal/JsEvents.kt @@ -21,7 +21,10 @@ package io.matthewnelson.kmp.process.internal import io.matthewnelson.kmp.process.InternalProcessApi -/** [docs](https://nodejs.org/api/events.html#class-eventemitter) */ +/** + * [docs](https://nodejs.org/api/events.html#class-eventemitter) + * @suppress + * */ @InternalProcessApi @JsName("EventEmitter") public open external class events_EventEmitter { diff --git a/library/process/src/jsMain/kotlin/io/matthewnelson/kmp/process/internal/JsPlatform.kt b/library/process/src/jsMain/kotlin/io/matthewnelson/kmp/process/internal/JsPlatform.kt index 59131829..6b13a050 100644 --- a/library/process/src/jsMain/kotlin/io/matthewnelson/kmp/process/internal/JsPlatform.kt +++ b/library/process/src/jsMain/kotlin/io/matthewnelson/kmp/process/internal/JsPlatform.kt @@ -75,6 +75,7 @@ internal inline fun ArrayBufferView.fill() { } } +/** @suppress */ @InternalProcessApi @Suppress("NOTHING_TO_INLINE") public inline fun T.onError( @@ -84,6 +85,7 @@ public inline fun T.onError( return this } +/** @suppress */ @InternalProcessApi @Suppress("NOTHING_TO_INLINE") public inline fun T.onceError(