From 35d15601f2d129a7d3db67dd9e2f4c41c87ef083 Mon Sep 17 00:00:00 2001 From: Adam <897017+aSemy@users.noreply.github.com> Date: Fri, 20 Oct 2023 00:39:12 +1300 Subject: Contribute Dokkatoo (#3188) --- build-logic/build.gradle.kts | 2 +- dokka-runners/dokkatoo/.gitattributes | 51 +++ dokka-runners/dokkatoo/.gitignore | 71 ++++ dokka-runners/dokkatoo/build.gradle.kts | 47 +++ dokka-runners/dokkatoo/buildSrc/build.gradle.kts | 19 + .../dokkatoo/buildSrc/settings.gradle.kts | 25 ++ .../buildsrc/conventions/android-setup.gradle.kts | 78 ++++ .../kotlin/buildsrc/conventions/base.gradle.kts | 155 +++++++ .../conventions/dokka-source-downloader.gradle.kts | 68 +++ .../dokkatoo-example-projects-base.gradle.kts | 27 ++ .../dokkatoo-example-projects.gradle.kts | 160 +++++++ .../conventions/gradle-plugin-variants.gradle.kts | 44 ++ .../buildsrc/conventions/java-base.gradle.kts | 19 + .../conventions/kotlin-gradle-plugin.gradle.kts | 37 ++ .../conventions/maven-publish-test.gradle.kts | 93 ++++ .../conventions/maven-publishing.gradle.kts | 137 ++++++ .../settings/DokkaSourceDownloaderSettings.kt | 13 + .../settings/DokkaTemplateProjectSettings.kt | 96 +++++ .../settings/DokkatooExampleProjectsSettings.kt | 62 +++ .../buildsrc/settings/MavenPublishTestSettings.kt | 19 + .../buildsrc/settings/MavenPublishingSettings.kt | 68 +++ .../kotlin/buildsrc/tasks/SetupDokkaProjects.kt | 73 ++++ .../tasks/UpdateDokkatooExampleProjects.kt | 49 +++ .../src/main/kotlin/buildsrc/utils/gradle.kt | 118 ++++++ .../src/main/kotlin/buildsrc/utils/intellij.kt | 45 ++ .../src/main/kotlin/buildsrc/utils/strings.kt | 26 ++ dokka-runners/dokkatoo/devOps/release.main.kts | 415 ++++++++++++++++++ dokka-runners/dokkatoo/examples/.gitignore | 10 + dokka-runners/dokkatoo/examples/README.md | 18 + dokka-runners/dokkatoo/examples/build.gradle.kts | 48 +++ .../examples/custom-format-example/dokka/README.md | 17 + .../custom-format-example/dokka/build.gradle.kts | 35 ++ .../examples/custom-format-example/dokka/demo.png | Bin 0 -> 77918 bytes .../custom-format-example/dokka/ktor-logo.png | Bin 0 -> 179624 bytes .../custom-format-example/dokka/logo-styles.css | 20 + .../dokka/settings.gradle.kts | 1 + .../dokka/src/main/kotlin/demo/HelloWorld.kt | 20 + .../dokkatoo/build.gradle.kts | 18 + .../custom-format-example/dokkatoo/ktor-logo.png | Bin 0 -> 179624 bytes .../custom-format-example/dokkatoo/logo-styles.css | 20 + .../dokkatoo/settings.gradle.kts | 17 + .../dokkatoo/src/main/kotlin/demo/HelloWorld.kt | 20 + .../examples/gradle-example/dokka/Module.md | 7 + .../examples/gradle-example/dokka/README.md | 22 + .../examples/gradle-example/dokka/build.gradle.kts | 37 ++ .../examples/gradle-example/dokka/demo.png | Bin 0 -> 71039 bytes .../gradle-example/dokka/settings.gradle.kts | 1 + .../dokka/src/main/kotlin/demo/HelloWorld.kt | 20 + .../examples/gradle-example/dokkatoo/Module.md | 7 + .../gradle-example/dokkatoo/build.gradle.kts | 23 + .../gradle-example/dokkatoo/settings.gradle.kts | 17 + .../dokkatoo/src/main/kotlin/demo/HelloWorld.kt | 20 + .../kotlin-as-java-example/dokka/README.md | 19 + .../kotlin-as-java-example/dokka/build.gradle.kts | 21 + .../examples/kotlin-as-java-example/dokka/demo.png | Bin 0 -> 101974 bytes .../dokka/settings.gradle.kts | 1 + .../dokka/src/main/kotlin/demo/HelloWorld.kt | 20 + .../dokkatoo/settings.gradle.kts | 17 + .../library-publishing-example/dokka/README.md | 41 ++ .../dokka/build.gradle.kts | 39 ++ .../dokka/settings.gradle.kts | 1 + .../dokka/src/main/kotlin/demo/HelloWorld.kt | 20 + .../dokkatoo/settings.gradle.kts | 17 + .../examples/multimodule-example/dokka/README.md | 25 ++ .../multimodule-example/dokka/build.gradle.kts | 5 + .../examples/multimodule-example/dokka/demo.png | Bin 0 -> 93395 bytes .../dokka/parentProject/build.gradle.kts | 38 ++ .../dokka/parentProject/childProjectA/ModuleA.md | 5 + .../parentProject/childProjectA/build.gradle.kts | 16 + .../src/main/kotlin/demo/ChildProjectAClass.kt | 8 + .../dokka/parentProject/childProjectB/ModuleB.md | 5 + .../parentProject/childProjectB/build.gradle.kts | 16 + .../src/main/kotlin/demo/ChildProjectBClass.kt | 8 + .../multimodule-example/dokka/settings.gradle.kts | 15 + .../dokkatoo/buildSrc/build.gradle.kts | 8 + .../dokkatoo/buildSrc/settings.gradle.kts | 21 + .../src/main/kotlin/dokka-convention.gradle.kts | 17 + .../dokkatoo/parentProject/build.gradle.kts | 23 + .../parentProject/childProjectA/ModuleA.md | 5 + .../parentProject/childProjectA/build.gradle.kts | 21 + .../src/main/kotlin/demo/ChildProjectAClass.kt | 8 + .../parentProject/childProjectB/ModuleB.md | 5 + .../parentProject/childProjectB/build.gradle.kts | 21 + .../src/main/kotlin/demo/ChildProjectBClass.kt | 8 + .../dokkatoo/settings.gradle.kts | 21 + .../examples/multiplatform-example/dokka/README.md | 29 ++ .../multiplatform-example/dokka/build.gradle.kts | 42 ++ .../examples/multiplatform-example/dokka/demo.png | Bin 0 -> 183500 bytes .../dokka/settings.gradle.kts | 2 + .../org/kotlintestmpp/CommonCoroutineExtensions.kt | 15 + .../kotlin/org/kotlintestmpp/CommonDateUtils.kt | 14 + .../kotlin/org/kotlintestmpp/common/Foo.kt | 7 + .../org/kotlintest/jdk9/CustomSourceSetFile.kt | 11 + .../org/kotlintestmpp/JsCoroutineExtensions.kt | 11 + .../jsMain/kotlin/org/kotlintestmpp/JsDateUtils.kt | 8 + .../jsMain/kotlin/org/kotlintestmpp/JsFunctions.kt | 18 + .../kotlin/org/kotlintestmpp/JavaAnnotation.java | 19 + .../org/kotlintestmpp/JvmCoroutineExtensions.kt | 11 + .../kotlin/org/kotlintestmpp/JvmDateUtils.kt | 8 + .../kotlin/org/kotlintestmpp/JvmFunctions.kt | 35 ++ .../linuxMain/kotlin/org/kotlintestmpp/CInterop.kt | 15 + .../org/kotlintestmpp/LinuxCoroutineExtensions.kt | 11 + .../kotlin/org/kotlintestmpp/LinuxDateUtils.kt | 8 + .../org/kotlintestmpp/MacOsCoroutineExtensions.kt | 11 + .../kotlin/org/kotlintestmpp/MacOsDateUtils.kt | 8 + .../dokkatoo/build.gradle.kts | 39 ++ .../dokkatoo/settings.gradle.kts | 17 + .../org/kotlintestmpp/CommonCoroutineExtensions.kt | 15 + .../kotlin/org/kotlintestmpp/CommonDateUtils.kt | 14 + .../kotlin/org/kotlintestmpp/common/Foo.kt | 7 + .../org/kotlintest/jdk9/CustomSourceSetFile.kt | 11 + .../org/kotlintestmpp/JsCoroutineExtensions.kt | 11 + .../jsMain/kotlin/org/kotlintestmpp/JsDateUtils.kt | 8 + .../jsMain/kotlin/org/kotlintestmpp/JsFunctions.kt | 18 + .../kotlin/org/kotlintestmpp/JavaAnnotation.java | 19 + .../org/kotlintestmpp/JvmCoroutineExtensions.kt | 11 + .../kotlin/org/kotlintestmpp/JvmDateUtils.kt | 8 + .../kotlin/org/kotlintestmpp/JvmFunctions.kt | 35 ++ .../linuxMain/kotlin/org/kotlintestmpp/CInterop.kt | 15 + .../org/kotlintestmpp/LinuxCoroutineExtensions.kt | 11 + .../kotlin/org/kotlintestmpp/LinuxDateUtils.kt | 8 + .../org/kotlintestmpp/MacOsCoroutineExtensions.kt | 11 + .../kotlin/org/kotlintestmpp/MacOsDateUtils.kt | 8 + .../versioning-multimodule-example/dokka/README.md | 25 ++ .../dokka/build.gradle.kts | 19 + .../versioning-multimodule-example/dokka/demo.png | Bin 0 -> 35812 bytes .../dokka/parentProject/build.gradle.kts | 27 ++ .../parentProject/childProjectA/build.gradle.kts | 1 + .../src/main/kotlin/demo/ChildProjectAClass.kt | 18 + .../childProjectA/src/main/kotlin/demo/FancyAPI.kt | 10 + .../parentProject/childProjectB/build.gradle.kts | 1 + .../src/main/kotlin/demo/ChildProjectBClass.kt | 10 + .../src/main/kotlin/demo/Functions.kt | 8 + .../dokka/settings.gradle.kts | 5 + .../dokkatoo/settings.gradle.kts | 17 + dokka-runners/dokkatoo/gradle.properties | 12 + dokka-runners/dokkatoo/gradle/libs.versions.toml | 48 +++ .../dokkatoo/modules/docs/build.gradle.kts | 58 +++ .../dokkatoo/modules/docs/images/banner.svg | 100 +++++ .../dokkatoo/modules/docs/images/logo-icon.svg | 84 ++++ .../modules/docs/images/social_preview_banner.png | Bin 0 -> 38562 bytes .../modules/docs/images/social_preview_banner.svg | 106 +++++ .../dokkatoo/modules/docs/style/logo-styles.css | 44 ++ .../build.gradle.kts | 281 +++++++++++++ .../projects/.gitignore | 15 + .../ANDROID_SDK/licenses/android-googletv-license | 2 + .../licenses/android-sdk-arm-dbt-license | 2 + .../ANDROID_SDK/licenses/android-sdk-license | 2 + .../licenses/android-sdk-preview-license | 2 + .../ANDROID_SDK/licenses/google-gdk-license | 2 + .../licenses/intel-android-extra-license | 2 + .../licenses/mips-android-sysimage-license | 2 + .../projects/it-android-0/dokka/build.gradle.kts | 18 + .../it-android-0/dokka/settings.gradle.kts | 5 + .../dokka/src/main/AndroidManifest.xml | 1 + .../main/java/it/android/AndroidSpecificClass.kt | 16 + .../java/it/android/IntegrationTestActivity.kt | 22 + .../it-android-0/dokka/template.root.gradle.kts | 23 + .../dokka/template.settings.gradle.kts | 38 ++ .../it-android-0/dokkatoo/build.gradle.kts | 32 ++ .../it-android-0/dokkatoo/settings.gradle.kts | 19 + .../dokkatoo/src/main/AndroidManifest.xml | 1 + .../main/java/it/android/AndroidSpecificClass.kt | 16 + .../java/it/android/IntegrationTestActivity.kt | 22 + .../projects/it-basic-groovy/dokka/build.gradle | 54 +++ .../it-basic-groovy/dokka/settings.gradle.kts | 5 + .../main/java/it/basic/java/SampleJavaClass.java | 17 + .../dokka/src/main/kotlin/it/basic/PublicClass.kt | 48 +++ .../it-basic-groovy/dokka/template.root.gradle.kts | 23 + .../dokka/template.settings.gradle.kts | 38 ++ .../it-basic-groovy/dokkatoo/settings.gradle | 16 + .../projects/it-basic/dokka/build.gradle.kts | 63 +++ .../dokka/customResources/custom-resource.svg | 3 + .../dokka/customResources/custom-style-to-add.css | 1 + .../it-basic/dokka/customResources/logo-styles.css | 3 + .../projects/it-basic/dokka/settings.gradle.kts | 5 + .../main/java/it/basic/java/SampleJavaClass.java | 17 + .../dokka/src/main/kotlin/RootPackageClass.kt | 8 + .../dokka/src/main/kotlin/it/basic/PublicClass.kt | 69 +++ .../src/main/kotlin/it/internal/InternalClass.kt | 7 + .../it/overriddenVisibility/VisiblePrivateClass.kt | 12 + .../src/main/kotlin/it/protected/ProtectedClass.kt | 10 + .../it/suppressedByPackage/SuppressedByPackage.kt | 7 + .../kotlin/it/suppressedByPath/SuppressedByPath.kt | 7 + .../dokka/src/test/kotlin/it/basic/TestClass.kt | 17 + .../it-basic/dokka/template.root.gradle.kts | 23 + .../it-basic/dokka/template.settings.gradle.kts | 38 ++ .../projects/it-basic/dokkatoo/build.gradle.kts | 64 +++ .../dokkatoo/customResources/custom-resource.svg | 3 + .../customResources/custom-style-to-add.css | 1 + .../dokkatoo/customResources/logo-styles.css | 3 + .../projects/it-basic/dokkatoo/settings.gradle.kts | 17 + .../main/java/it/basic/java/SampleJavaClass.java | 17 + .../dokkatoo/src/main/kotlin/RootPackageClass.kt | 8 + .../src/main/kotlin/it/basic/PublicClass.kt | 69 +++ .../src/main/kotlin/it/internal/InternalClass.kt | 7 + .../it/overriddenVisibility/VisiblePrivateClass.kt | 12 + .../src/main/kotlin/it/protected/ProtectedClass.kt | 10 + .../it/suppressedByPackage/SuppressedByPackage.kt | 7 + .../kotlin/it/suppressedByPath/SuppressedByPath.kt | 7 + .../dokkatoo/src/test/kotlin/it/basic/TestClass.kt | 17 + .../projects/it-collector-0/dokka/build.gradle.kts | 1 + .../it-collector-0/dokka/moduleA/build.gradle.kts | 6 + .../it-collector-0/dokka/moduleA/moduleB/README.md | 2 + .../dokka/moduleA/moduleB/build.gradle.kts | 4 + .../org/jetbrains/dokka/it/moduleB/ModuleB.kt | 6 + .../it-collector-0/dokka/moduleA/moduleC/README.md | 2 + .../dokka/moduleA/moduleC/build.gradle.kts | 4 + .../org/jetbrains/dokka/it/moduleC/ModuleC.kt | 6 + .../it-collector-0/dokka/settings.gradle.kts | 5 + .../it-collector-0/dokka/template.root.gradle.kts | 23 + .../dokka/template.settings.gradle.kts | 38 ++ .../it-collector-0/dokkatoo/settings.gradle.kts | 17 + .../projects/it-js-ir-0/dokka/build.gradle.kts | 21 + .../projects/it-js-ir-0/dokka/settings.gradle.kts | 5 + .../dokka/src/main/kotlin/RootPackageClass.kt | 26 ++ .../dokka/src/main/kotlin/it/basic/PublicClass.kt | 53 +++ .../src/main/kotlin/it/internal/InternalClass.kt | 7 + .../it/suppressedByPackage/SuppressedByPackage.kt | 7 + .../kotlin/it/suppressedByPath/SuppressedByPath.kt | 7 + .../it-js-ir-0/dokka/template.root.gradle.kts | 23 + .../it-js-ir-0/dokka/template.settings.gradle.kts | 38 ++ .../it-js-ir-0/dokkatoo/settings.gradle.kts | 17 + .../it-multimodule-0/dokka/build.gradle.kts | 1 + .../dokka/moduleA/build.gradle.kts | 6 + .../dokka/moduleA/moduleB/Module.md | 6 + .../dokka/moduleA/moduleB/build.gradle.kts | 13 + .../org/jetbrains/dokka/it/moduleB/ModuleB.kt | 6 + .../dokka/moduleA/moduleC/Module.md | 2 + .../dokka/moduleA/moduleC/build.gradle.kts | 12 + .../org/jetbrains/dokka/it/moduleC/ModuleC.kt | 6 + .../dokka/moduleA/moduleD/build.gradle.kts | 6 + .../org/jetbrains/dokka/it/moduleD/ModuleC.kt | 6 + .../it-multimodule-0/dokka/settings.gradle.kts | 6 + .../dokka/template.root.gradle.kts | 23 + .../dokka/template.settings.gradle.kts | 38 ++ .../it-multimodule-0/dokkatoo/settings.gradle.kts | 17 + .../projects/it-multimodule-1/dokka/build.gradle | 18 + .../it-multimodule-1/dokka/first/build.gradle | 0 .../dokka/first/src/main/kotlin/foo/FirstClass.kt | 11 + .../first/src/main/kotlin/foo/FirstSubclass.kt | 12 + .../dokka/first/src/main/kotlin/foo/Main.kt | 8 + .../dokka/first/src/main/kotlin/noPackage.kt | 3 + .../it-multimodule-1/dokka/second/build.gradle | 14 + .../dokka/second/src/main/kotlin/NoPackageClass.kt | 1 + .../second/src/main/kotlin/bar/SecondClass.kt | 21 + .../dokka/second/src/main/kotlin/foo/ThirdClass.kt | 11 + .../it-multimodule-1/dokka/settings.gradle.kts | 4 + .../dokka/template.root.gradle.kts | 23 + .../dokka/template.settings.gradle.kts | 38 ++ .../it-multimodule-1/dokkatoo/settings.gradle.kts | 17 + .../it-multimodule-versioning-0/dokka/build.gradle | 43 ++ .../dokka/first/build.gradle | 0 .../dokka/first/src/main/kotlin/foo/FirstClass.kt | 11 + .../dokka/second/build.gradle | 3 + .../second/src/main/kotlin/bar/SecondClass.kt | 21 + .../dokka/settings.gradle.kts | 4 + .../dokka/template.root.gradle.kts | 23 + .../dokka/template.settings.gradle.kts | 38 ++ .../dokkatoo/settings.gradle.kts | 17 + .../it-multiplatform-0/dokka/build.gradle.kts | 48 +++ .../it-multiplatform-0/dokka/settings.gradle.kts | 2 + .../commonMain/kotlin/it/mpp0/CommonMainClass.kt | 8 + .../src/commonMain/kotlin/it/mpp0/ExpectedClass.kt | 5 + .../src/commonMain/kotlin/it/mpp0/coroutines.kt | 5 + .../kotlin/it/mpp0/CPointerExtension.kt | 11 + .../desktopMain/kotlin/it/mpp0/ExpectedClass.kt | 5 + .../src/jsMain/kotlin/it/mpp0/ExpectedClass.kt | 5 + .../dokka/src/jsMain/kotlin/it/mpp0/runBlocking.kt | 7 + .../src/jvmMain/kotlin/it/mpp0/ExpectedClass.kt | 11 + .../src/jvmMain/kotlin/it/mpp0/JvmOnlyClass.kt | 13 + .../src/jvmMain/kotlin/it/mpp0/runBlocking.kt | 7 + .../linuxMain/kotlin/it/mpp0/CPointerExtension.kt | 11 + .../src/linuxMain/kotlin/it/mpp0/ExpectedClass.kt | 5 + .../src/linuxMain/kotlin/it/mpp0/runBlocking.kt | 13 + .../src/macosMain/kotlin/it/mpp0/ExpectedClass.kt | 5 + .../src/macosMain/kotlin/it/mpp0/runBlocking.kt | 7 + .../dokka/template.root.gradle.kts | 23 + .../dokka/template.settings.gradle.kts | 38 ++ .../dokkatoo/settings.gradle.kts | 17 + .../testExamples/kotlin/CustomFormatExampleTest.kt | 197 +++++++++ .../src/testExamples/kotlin/GradleExampleTest.kt | 190 +++++++++ .../kotlin/KotlinMultiplatformExampleTest.kt | 226 ++++++++++ .../testExamples/kotlin/MultimoduleExampleTest.kt | 244 +++++++++++ .../testFixtures/kotlin/templateProjectUtils.kt | 17 + .../kotlin/AndroidProjectIntegrationTest.kt | 166 ++++++++ .../kotlin/BasicProjectIntegrationTest.kt | 153 +++++++ .../example/dokka-multi-module/childProjectA.json | 83 ++++ .../example/dokka-multi-module/childProjectB.json | 83 ++++ .../example/dokka-multi-module/parentProject.json | 55 +++ .../it/example/dokka-multi-module/readme.md | 5 + .../dokkatoo-plugin/api/dokkatoo-plugin.api | 397 +++++++++++++++++ .../modules/dokkatoo-plugin/build.gradle.kts | 254 +++++++++++ .../src/main/kotlin/DokkatooBasePlugin.kt | 355 ++++++++++++++++ .../src/main/kotlin/DokkatooExtension.kt | 130 ++++++ .../src/main/kotlin/DokkatooPlugin.kt | 32 ++ .../main/kotlin/adapters/DokkatooAndroidAdapter.kt | 214 ++++++++++ .../main/kotlin/adapters/DokkatooJavaAdapter.kt | 40 ++ .../main/kotlin/adapters/DokkatooKotlinAdapter.kt | 459 ++++++++++++++++++++ .../DokkatooConfigurationAttributes.kt | 59 +++ .../src/main/kotlin/dokka/DokkaPublication.kt | 122 ++++++ .../DokkaExternalDocumentationLinkSpec.kt | 120 ++++++ .../parameters/DokkaGeneratorParametersSpec.kt | 93 ++++ .../dokka/parameters/DokkaModuleDescriptionSpec.kt | 49 +++ .../dokka/parameters/DokkaPackageOptionsSpec.kt | 84 ++++ .../kotlin/dokka/parameters/DokkaParametersKxs.kt | 78 ++++ .../kotlin/dokka/parameters/DokkaSourceLinkSpec.kt | 106 +++++ .../dokka/parameters/DokkaSourceSetIdSpec.kt | 61 +++ .../kotlin/dokka/parameters/DokkaSourceSetSpec.kt | 366 ++++++++++++++++ .../HasConfigurableVisibilityModifiers.kt | 14 + .../main/kotlin/dokka/parameters/KotlinPlatform.kt | 54 +++ .../kotlin/dokka/parameters/VisibilityModifier.kt | 42 ++ .../builders/DokkaModuleDescriptionBuilder.kt | 33 ++ .../parameters/builders/DokkaParametersBuilder.kt | 77 ++++ .../parameters/builders/DokkaSourceSetBuilder.kt | 112 +++++ .../dokka/plugins/DokkaHtmlPluginParameters.kt | 129 ++++++ .../dokka/plugins/DokkaPluginParametersBaseSpec.kt | 32 ++ .../dokka/plugins/DokkaPluginParametersBuilder.kt | 232 ++++++++++ .../plugins/DokkaVersioningPluginParameters.kt | 101 +++++ .../formats/DokkatooFormatDependencyContainers.kt | 152 +++++++ .../main/kotlin/formats/DokkatooFormatPlugin.kt | 174 ++++++++ .../src/main/kotlin/formats/DokkatooFormatTasks.kt | 105 +++++ .../src/main/kotlin/formats/DokkatooGfmPlugin.kt | 14 + .../src/main/kotlin/formats/DokkatooHtmlPlugin.kt | 72 ++++ .../main/kotlin/formats/DokkatooJavadocPlugin.kt | 14 + .../main/kotlin/formats/DokkatooJekyllPlugin.kt | 14 + .../main/kotlin/internal/DokkatooInternalApi.kt | 37 ++ .../src/main/kotlin/internal/LoggerAdapter.kt | 65 +++ .../src/main/kotlin/internal/collectionsUtils.kt | 7 + .../kotlin/internal/gradleExtensionAccessors.kt | 9 + .../src/main/kotlin/internal/gradleTypealiases.kt | 20 + .../src/main/kotlin/internal/gradleUtils.kt | 187 ++++++++ .../kotlin/internal/kotlinxSerializationUtils.kt | 36 ++ .../src/main/kotlin/internal/stringUtils.kt | 11 + .../src/main/kotlin/internal/uriUtils.kt | 9 + .../src/main/kotlin/tasks/DokkatooGenerateTask.kt | 187 ++++++++ .../tasks/DokkatooPrepareModuleDescriptorTask.kt | 62 +++ .../src/main/kotlin/tasks/DokkatooTask.kt | 22 + .../kotlin/tasks/LogHtmlPublicationLinkTask.kt | 156 +++++++ .../main/kotlin/workers/DokkaGeneratorWorker.kt | 77 ++++ .../src/test/kotlin/DokkatooPluginTest.kt | 76 ++++ .../DokkaExternalDocumentationLinkSpecTest.kt | 102 +++++ .../dokka/parameters/DokkaSourceLinkSpecTest.kt | 58 +++ .../kotlin/dokka/parameters/KotlinPlatformTest.kt | 37 ++ .../dokka/parameters/VisibilityModifierTest.kt | 17 + .../builders/DokkaModuleDescriptionBuilderTest.kt | 7 + .../builders/DokkaParametersBuilderTest.kt | 7 + .../builders/DokkaSourceSetBuilderTest.kt | 198 +++++++++ .../src/testFixtures/kotlin/GradleTestKitUtils.kt | 274 ++++++++++++ .../src/testFixtures/kotlin/KotestProjectConfig.kt | 10 + .../src/testFixtures/kotlin/fileTree.kt | 61 +++ .../src/testFixtures/kotlin/files.kt | 6 + .../src/testFixtures/kotlin/gradleRunnerUtils.kt | 47 +++ .../kotlin/kotestCollectionMatchers.kt | 20 + .../src/testFixtures/kotlin/kotestConditions.kt | 10 + .../testFixtures/kotlin/kotestGradleAssertions.kt | 130 ++++++ .../testFixtures/kotlin/kotestStringMatchers.kt | 65 +++ .../kotlin/samWithReceiverWorkarounds.kt | 77 ++++ .../src/testFixtures/kotlin/stringUtils.kt | 21 + .../testFixtures/kotlin/systemVariableProviders.kt | 40 ++ .../src/testFixtures/kotlin/text.kt | 24 ++ .../kotlin/DokkatooPluginFunctionalTest.kt | 205 +++++++++ .../kotlin/GradlePluginProjectIntegrationTest.kt | 110 +++++ .../kotlin/KotlinMultiplatformFunctionalTest.kt | 247 +++++++++++ .../kotlin/MultiModuleFunctionalTest.kt | 468 +++++++++++++++++++++ dokka-runners/dokkatoo/settings.gradle.kts | 95 +++++ settings.gradle.kts | 4 +- 367 files changed, 15468 insertions(+), 3 deletions(-) create mode 100644 dokka-runners/dokkatoo/.gitattributes create mode 100644 dokka-runners/dokkatoo/.gitignore create mode 100644 dokka-runners/dokkatoo/build.gradle.kts create mode 100644 dokka-runners/dokkatoo/buildSrc/build.gradle.kts create mode 100644 dokka-runners/dokkatoo/buildSrc/settings.gradle.kts create mode 100644 dokka-runners/dokkatoo/buildSrc/src/main/kotlin/buildsrc/conventions/android-setup.gradle.kts create mode 100644 dokka-runners/dokkatoo/buildSrc/src/main/kotlin/buildsrc/conventions/base.gradle.kts create mode 100644 dokka-runners/dokkatoo/buildSrc/src/main/kotlin/buildsrc/conventions/dokka-source-downloader.gradle.kts create mode 100644 dokka-runners/dokkatoo/buildSrc/src/main/kotlin/buildsrc/conventions/dokkatoo-example-projects-base.gradle.kts create mode 100644 dokka-runners/dokkatoo/buildSrc/src/main/kotlin/buildsrc/conventions/dokkatoo-example-projects.gradle.kts create mode 100644 dokka-runners/dokkatoo/buildSrc/src/main/kotlin/buildsrc/conventions/gradle-plugin-variants.gradle.kts create mode 100644 dokka-runners/dokkatoo/buildSrc/src/main/kotlin/buildsrc/conventions/java-base.gradle.kts create mode 100644 dokka-runners/dokkatoo/buildSrc/src/main/kotlin/buildsrc/conventions/kotlin-gradle-plugin.gradle.kts create mode 100644 dokka-runners/dokkatoo/buildSrc/src/main/kotlin/buildsrc/conventions/maven-publish-test.gradle.kts create mode 100644 dokka-runners/dokkatoo/buildSrc/src/main/kotlin/buildsrc/conventions/maven-publishing.gradle.kts create mode 100644 dokka-runners/dokkatoo/buildSrc/src/main/kotlin/buildsrc/settings/DokkaSourceDownloaderSettings.kt create mode 100644 dokka-runners/dokkatoo/buildSrc/src/main/kotlin/buildsrc/settings/DokkaTemplateProjectSettings.kt create mode 100644 dokka-runners/dokkatoo/buildSrc/src/main/kotlin/buildsrc/settings/DokkatooExampleProjectsSettings.kt create mode 100644 dokka-runners/dokkatoo/buildSrc/src/main/kotlin/buildsrc/settings/MavenPublishTestSettings.kt create mode 100644 dokka-runners/dokkatoo/buildSrc/src/main/kotlin/buildsrc/settings/MavenPublishingSettings.kt create mode 100644 dokka-runners/dokkatoo/buildSrc/src/main/kotlin/buildsrc/tasks/SetupDokkaProjects.kt create mode 100644 dokka-runners/dokkatoo/buildSrc/src/main/kotlin/buildsrc/tasks/UpdateDokkatooExampleProjects.kt create mode 100644 dokka-runners/dokkatoo/buildSrc/src/main/kotlin/buildsrc/utils/gradle.kt create mode 100644 dokka-runners/dokkatoo/buildSrc/src/main/kotlin/buildsrc/utils/intellij.kt create mode 100644 dokka-runners/dokkatoo/buildSrc/src/main/kotlin/buildsrc/utils/strings.kt create mode 100644 dokka-runners/dokkatoo/devOps/release.main.kts create mode 100644 dokka-runners/dokkatoo/examples/.gitignore create mode 100644 dokka-runners/dokkatoo/examples/README.md create mode 100644 dokka-runners/dokkatoo/examples/build.gradle.kts create mode 100644 dokka-runners/dokkatoo/examples/custom-format-example/dokka/README.md create mode 100644 dokka-runners/dokkatoo/examples/custom-format-example/dokka/build.gradle.kts create mode 100644 dokka-runners/dokkatoo/examples/custom-format-example/dokka/demo.png create mode 100644 dokka-runners/dokkatoo/examples/custom-format-example/dokka/ktor-logo.png create mode 100644 dokka-runners/dokkatoo/examples/custom-format-example/dokka/logo-styles.css create mode 100644 dokka-runners/dokkatoo/examples/custom-format-example/dokka/settings.gradle.kts create mode 100644 dokka-runners/dokkatoo/examples/custom-format-example/dokka/src/main/kotlin/demo/HelloWorld.kt create mode 100644 dokka-runners/dokkatoo/examples/custom-format-example/dokkatoo/build.gradle.kts create mode 100644 dokka-runners/dokkatoo/examples/custom-format-example/dokkatoo/ktor-logo.png create mode 100644 dokka-runners/dokkatoo/examples/custom-format-example/dokkatoo/logo-styles.css create mode 100644 dokka-runners/dokkatoo/examples/custom-format-example/dokkatoo/settings.gradle.kts create mode 100644 dokka-runners/dokkatoo/examples/custom-format-example/dokkatoo/src/main/kotlin/demo/HelloWorld.kt create mode 100644 dokka-runners/dokkatoo/examples/gradle-example/dokka/Module.md create mode 100644 dokka-runners/dokkatoo/examples/gradle-example/dokka/README.md create mode 100644 dokka-runners/dokkatoo/examples/gradle-example/dokka/build.gradle.kts create mode 100644 dokka-runners/dokkatoo/examples/gradle-example/dokka/demo.png create mode 100644 dokka-runners/dokkatoo/examples/gradle-example/dokka/settings.gradle.kts create mode 100644 dokka-runners/dokkatoo/examples/gradle-example/dokka/src/main/kotlin/demo/HelloWorld.kt create mode 100644 dokka-runners/dokkatoo/examples/gradle-example/dokkatoo/Module.md create mode 100644 dokka-runners/dokkatoo/examples/gradle-example/dokkatoo/build.gradle.kts create mode 100644 dokka-runners/dokkatoo/examples/gradle-example/dokkatoo/settings.gradle.kts create mode 100644 dokka-runners/dokkatoo/examples/gradle-example/dokkatoo/src/main/kotlin/demo/HelloWorld.kt create mode 100644 dokka-runners/dokkatoo/examples/kotlin-as-java-example/dokka/README.md create mode 100644 dokka-runners/dokkatoo/examples/kotlin-as-java-example/dokka/build.gradle.kts create mode 100644 dokka-runners/dokkatoo/examples/kotlin-as-java-example/dokka/demo.png create mode 100644 dokka-runners/dokkatoo/examples/kotlin-as-java-example/dokka/settings.gradle.kts create mode 100644 dokka-runners/dokkatoo/examples/kotlin-as-java-example/dokka/src/main/kotlin/demo/HelloWorld.kt create mode 100644 dokka-runners/dokkatoo/examples/kotlin-as-java-example/dokkatoo/settings.gradle.kts create mode 100644 dokka-runners/dokkatoo/examples/library-publishing-example/dokka/README.md create mode 100644 dokka-runners/dokkatoo/examples/library-publishing-example/dokka/build.gradle.kts create mode 100644 dokka-runners/dokkatoo/examples/library-publishing-example/dokka/settings.gradle.kts create mode 100644 dokka-runners/dokkatoo/examples/library-publishing-example/dokka/src/main/kotlin/demo/HelloWorld.kt create mode 100644 dokka-runners/dokkatoo/examples/library-publishing-example/dokkatoo/settings.gradle.kts create mode 100644 dokka-runners/dokkatoo/examples/multimodule-example/dokka/README.md create mode 100644 dokka-runners/dokkatoo/examples/multimodule-example/dokka/build.gradle.kts create mode 100644 dokka-runners/dokkatoo/examples/multimodule-example/dokka/demo.png create mode 100644 dokka-runners/dokkatoo/examples/multimodule-example/dokka/parentProject/build.gradle.kts create mode 100644 dokka-runners/dokkatoo/examples/multimodule-example/dokka/parentProject/childProjectA/ModuleA.md create mode 100644 dokka-runners/dokkatoo/examples/multimodule-example/dokka/parentProject/childProjectA/build.gradle.kts create mode 100644 dokka-runners/dokkatoo/examples/multimodule-example/dokka/parentProject/childProjectA/src/main/kotlin/demo/ChildProjectAClass.kt create mode 100644 dokka-runners/dokkatoo/examples/multimodule-example/dokka/parentProject/childProjectB/ModuleB.md create mode 100644 dokka-runners/dokkatoo/examples/multimodule-example/dokka/parentProject/childProjectB/build.gradle.kts create mode 100644 dokka-runners/dokkatoo/examples/multimodule-example/dokka/parentProject/childProjectB/src/main/kotlin/demo/ChildProjectBClass.kt create mode 100644 dokka-runners/dokkatoo/examples/multimodule-example/dokka/settings.gradle.kts create mode 100644 dokka-runners/dokkatoo/examples/multimodule-example/dokkatoo/buildSrc/build.gradle.kts create mode 100644 dokka-runners/dokkatoo/examples/multimodule-example/dokkatoo/buildSrc/settings.gradle.kts create mode 100644 dokka-runners/dokkatoo/examples/multimodule-example/dokkatoo/buildSrc/src/main/kotlin/dokka-convention.gradle.kts create mode 100644 dokka-runners/dokkatoo/examples/multimodule-example/dokkatoo/parentProject/build.gradle.kts create mode 100644 dokka-runners/dokkatoo/examples/multimodule-example/dokkatoo/parentProject/childProjectA/ModuleA.md create mode 100644 dokka-runners/dokkatoo/examples/multimodule-example/dokkatoo/parentProject/childProjectA/build.gradle.kts create mode 100644 dokka-runners/dokkatoo/examples/multimodule-example/dokkatoo/parentProject/childProjectA/src/main/kotlin/demo/ChildProjectAClass.kt create mode 100644 dokka-runners/dokkatoo/examples/multimodule-example/dokkatoo/parentProject/childProjectB/ModuleB.md create mode 100644 dokka-runners/dokkatoo/examples/multimodule-example/dokkatoo/parentProject/childProjectB/build.gradle.kts create mode 100644 dokka-runners/dokkatoo/examples/multimodule-example/dokkatoo/parentProject/childProjectB/src/main/kotlin/demo/ChildProjectBClass.kt create mode 100644 dokka-runners/dokkatoo/examples/multimodule-example/dokkatoo/settings.gradle.kts create mode 100644 dokka-runners/dokkatoo/examples/multiplatform-example/dokka/README.md create mode 100644 dokka-runners/dokkatoo/examples/multiplatform-example/dokka/build.gradle.kts create mode 100644 dokka-runners/dokkatoo/examples/multiplatform-example/dokka/demo.png create mode 100644 dokka-runners/dokkatoo/examples/multiplatform-example/dokka/settings.gradle.kts create mode 100644 dokka-runners/dokkatoo/examples/multiplatform-example/dokka/src/commonMain/kotlin/org/kotlintestmpp/CommonCoroutineExtensions.kt create mode 100644 dokka-runners/dokkatoo/examples/multiplatform-example/dokka/src/commonMain/kotlin/org/kotlintestmpp/CommonDateUtils.kt create mode 100644 dokka-runners/dokkatoo/examples/multiplatform-example/dokka/src/commonMain/kotlin/org/kotlintestmpp/common/Foo.kt create mode 100644 dokka-runners/dokkatoo/examples/multiplatform-example/dokka/src/customJdk9/kotlin/org/kotlintest/jdk9/CustomSourceSetFile.kt create mode 100644 dokka-runners/dokkatoo/examples/multiplatform-example/dokka/src/jsMain/kotlin/org/kotlintestmpp/JsCoroutineExtensions.kt create mode 100644 dokka-runners/dokkatoo/examples/multiplatform-example/dokka/src/jsMain/kotlin/org/kotlintestmpp/JsDateUtils.kt create mode 100644 dokka-runners/dokkatoo/examples/multiplatform-example/dokka/src/jsMain/kotlin/org/kotlintestmpp/JsFunctions.kt create mode 100644 dokka-runners/dokkatoo/examples/multiplatform-example/dokka/src/jvmMain/kotlin/org/kotlintestmpp/JavaAnnotation.java create mode 100644 dokka-runners/dokkatoo/examples/multiplatform-example/dokka/src/jvmMain/kotlin/org/kotlintestmpp/JvmCoroutineExtensions.kt create mode 100644 dokka-runners/dokkatoo/examples/multiplatform-example/dokka/src/jvmMain/kotlin/org/kotlintestmpp/JvmDateUtils.kt create mode 100644 dokka-runners/dokkatoo/examples/multiplatform-example/dokka/src/jvmMain/kotlin/org/kotlintestmpp/JvmFunctions.kt create mode 100644 dokka-runners/dokkatoo/examples/multiplatform-example/dokka/src/linuxMain/kotlin/org/kotlintestmpp/CInterop.kt create mode 100644 dokka-runners/dokkatoo/examples/multiplatform-example/dokka/src/linuxMain/kotlin/org/kotlintestmpp/LinuxCoroutineExtensions.kt create mode 100644 dokka-runners/dokkatoo/examples/multiplatform-example/dokka/src/linuxMain/kotlin/org/kotlintestmpp/LinuxDateUtils.kt create mode 100644 dokka-runners/dokkatoo/examples/multiplatform-example/dokka/src/macosMain/kotlin/org/kotlintestmpp/MacOsCoroutineExtensions.kt create mode 100644 dokka-runners/dokkatoo/examples/multiplatform-example/dokka/src/macosMain/kotlin/org/kotlintestmpp/MacOsDateUtils.kt create mode 100644 dokka-runners/dokkatoo/examples/multiplatform-example/dokkatoo/build.gradle.kts create mode 100644 dokka-runners/dokkatoo/examples/multiplatform-example/dokkatoo/settings.gradle.kts create mode 100644 dokka-runners/dokkatoo/examples/multiplatform-example/dokkatoo/src/commonMain/kotlin/org/kotlintestmpp/CommonCoroutineExtensions.kt create mode 100644 dokka-runners/dokkatoo/examples/multiplatform-example/dokkatoo/src/commonMain/kotlin/org/kotlintestmpp/CommonDateUtils.kt create mode 100644 dokka-runners/dokkatoo/examples/multiplatform-example/dokkatoo/src/commonMain/kotlin/org/kotlintestmpp/common/Foo.kt create mode 100644 dokka-runners/dokkatoo/examples/multiplatform-example/dokkatoo/src/customJdk9/kotlin/org/kotlintest/jdk9/CustomSourceSetFile.kt create mode 100644 dokka-runners/dokkatoo/examples/multiplatform-example/dokkatoo/src/jsMain/kotlin/org/kotlintestmpp/JsCoroutineExtensions.kt create mode 100644 dokka-runners/dokkatoo/examples/multiplatform-example/dokkatoo/src/jsMain/kotlin/org/kotlintestmpp/JsDateUtils.kt create mode 100644 dokka-runners/dokkatoo/examples/multiplatform-example/dokkatoo/src/jsMain/kotlin/org/kotlintestmpp/JsFunctions.kt create mode 100644 dokka-runners/dokkatoo/examples/multiplatform-example/dokkatoo/src/jvmMain/kotlin/org/kotlintestmpp/JavaAnnotation.java create mode 100644 dokka-runners/dokkatoo/examples/multiplatform-example/dokkatoo/src/jvmMain/kotlin/org/kotlintestmpp/JvmCoroutineExtensions.kt create mode 100644 dokka-runners/dokkatoo/examples/multiplatform-example/dokkatoo/src/jvmMain/kotlin/org/kotlintestmpp/JvmDateUtils.kt create mode 100644 dokka-runners/dokkatoo/examples/multiplatform-example/dokkatoo/src/jvmMain/kotlin/org/kotlintestmpp/JvmFunctions.kt create mode 100644 dokka-runners/dokkatoo/examples/multiplatform-example/dokkatoo/src/linuxMain/kotlin/org/kotlintestmpp/CInterop.kt create mode 100644 dokka-runners/dokkatoo/examples/multiplatform-example/dokkatoo/src/linuxMain/kotlin/org/kotlintestmpp/LinuxCoroutineExtensions.kt create mode 100644 dokka-runners/dokkatoo/examples/multiplatform-example/dokkatoo/src/linuxMain/kotlin/org/kotlintestmpp/LinuxDateUtils.kt create mode 100644 dokka-runners/dokkatoo/examples/multiplatform-example/dokkatoo/src/macosMain/kotlin/org/kotlintestmpp/MacOsCoroutineExtensions.kt create mode 100644 dokka-runners/dokkatoo/examples/multiplatform-example/dokkatoo/src/macosMain/kotlin/org/kotlintestmpp/MacOsDateUtils.kt create mode 100644 dokka-runners/dokkatoo/examples/versioning-multimodule-example/dokka/README.md create mode 100644 dokka-runners/dokkatoo/examples/versioning-multimodule-example/dokka/build.gradle.kts create mode 100644 dokka-runners/dokkatoo/examples/versioning-multimodule-example/dokka/demo.png create mode 100644 dokka-runners/dokkatoo/examples/versioning-multimodule-example/dokka/parentProject/build.gradle.kts create mode 100644 dokka-runners/dokkatoo/examples/versioning-multimodule-example/dokka/parentProject/childProjectA/build.gradle.kts create mode 100644 dokka-runners/dokkatoo/examples/versioning-multimodule-example/dokka/parentProject/childProjectA/src/main/kotlin/demo/ChildProjectAClass.kt create mode 100644 dokka-runners/dokkatoo/examples/versioning-multimodule-example/dokka/parentProject/childProjectA/src/main/kotlin/demo/FancyAPI.kt create mode 100644 dokka-runners/dokkatoo/examples/versioning-multimodule-example/dokka/parentProject/childProjectB/build.gradle.kts create mode 100644 dokka-runners/dokkatoo/examples/versioning-multimodule-example/dokka/parentProject/childProjectB/src/main/kotlin/demo/ChildProjectBClass.kt create mode 100644 dokka-runners/dokkatoo/examples/versioning-multimodule-example/dokka/parentProject/childProjectB/src/main/kotlin/demo/Functions.kt create mode 100644 dokka-runners/dokkatoo/examples/versioning-multimodule-example/dokka/settings.gradle.kts create mode 100644 dokka-runners/dokkatoo/examples/versioning-multimodule-example/dokkatoo/settings.gradle.kts create mode 100644 dokka-runners/dokkatoo/gradle.properties create mode 100644 dokka-runners/dokkatoo/gradle/libs.versions.toml create mode 100644 dokka-runners/dokkatoo/modules/docs/build.gradle.kts create mode 100644 dokka-runners/dokkatoo/modules/docs/images/banner.svg create mode 100644 dokka-runners/dokkatoo/modules/docs/images/logo-icon.svg create mode 100644 dokka-runners/dokkatoo/modules/docs/images/social_preview_banner.png create mode 100644 dokka-runners/dokkatoo/modules/docs/images/social_preview_banner.svg create mode 100644 dokka-runners/dokkatoo/modules/docs/style/logo-styles.css create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/build.gradle.kts create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/projects/.gitignore create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/projects/ANDROID_SDK/licenses/android-googletv-license create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/projects/ANDROID_SDK/licenses/android-sdk-arm-dbt-license create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/projects/ANDROID_SDK/licenses/android-sdk-license create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/projects/ANDROID_SDK/licenses/android-sdk-preview-license create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/projects/ANDROID_SDK/licenses/google-gdk-license create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/projects/ANDROID_SDK/licenses/intel-android-extra-license create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/projects/ANDROID_SDK/licenses/mips-android-sysimage-license create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/projects/it-android-0/dokka/build.gradle.kts create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/projects/it-android-0/dokka/settings.gradle.kts create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/projects/it-android-0/dokka/src/main/AndroidManifest.xml create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/projects/it-android-0/dokka/src/main/java/it/android/AndroidSpecificClass.kt create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/projects/it-android-0/dokka/src/main/java/it/android/IntegrationTestActivity.kt create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/projects/it-android-0/dokka/template.root.gradle.kts create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/projects/it-android-0/dokka/template.settings.gradle.kts create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/projects/it-android-0/dokkatoo/build.gradle.kts create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/projects/it-android-0/dokkatoo/settings.gradle.kts create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/projects/it-android-0/dokkatoo/src/main/AndroidManifest.xml create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/projects/it-android-0/dokkatoo/src/main/java/it/android/AndroidSpecificClass.kt create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/projects/it-android-0/dokkatoo/src/main/java/it/android/IntegrationTestActivity.kt create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/projects/it-basic-groovy/dokka/build.gradle create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/projects/it-basic-groovy/dokka/settings.gradle.kts create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/projects/it-basic-groovy/dokka/src/main/java/it/basic/java/SampleJavaClass.java create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/projects/it-basic-groovy/dokka/src/main/kotlin/it/basic/PublicClass.kt create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/projects/it-basic-groovy/dokka/template.root.gradle.kts create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/projects/it-basic-groovy/dokka/template.settings.gradle.kts create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/projects/it-basic-groovy/dokkatoo/settings.gradle create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/projects/it-basic/dokka/build.gradle.kts create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/projects/it-basic/dokka/customResources/custom-resource.svg create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/projects/it-basic/dokka/customResources/custom-style-to-add.css create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/projects/it-basic/dokka/customResources/logo-styles.css create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/projects/it-basic/dokka/settings.gradle.kts create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/projects/it-basic/dokka/src/main/java/it/basic/java/SampleJavaClass.java create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/projects/it-basic/dokka/src/main/kotlin/RootPackageClass.kt create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/projects/it-basic/dokka/src/main/kotlin/it/basic/PublicClass.kt create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/projects/it-basic/dokka/src/main/kotlin/it/internal/InternalClass.kt create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/projects/it-basic/dokka/src/main/kotlin/it/overriddenVisibility/VisiblePrivateClass.kt create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/projects/it-basic/dokka/src/main/kotlin/it/protected/ProtectedClass.kt create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/projects/it-basic/dokka/src/main/kotlin/it/suppressedByPackage/SuppressedByPackage.kt create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/projects/it-basic/dokka/src/main/kotlin/it/suppressedByPath/SuppressedByPath.kt create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/projects/it-basic/dokka/src/test/kotlin/it/basic/TestClass.kt create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/projects/it-basic/dokka/template.root.gradle.kts create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/projects/it-basic/dokka/template.settings.gradle.kts create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/projects/it-basic/dokkatoo/build.gradle.kts create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/projects/it-basic/dokkatoo/customResources/custom-resource.svg create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/projects/it-basic/dokkatoo/customResources/custom-style-to-add.css create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/projects/it-basic/dokkatoo/customResources/logo-styles.css create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/projects/it-basic/dokkatoo/settings.gradle.kts create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/projects/it-basic/dokkatoo/src/main/java/it/basic/java/SampleJavaClass.java create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/projects/it-basic/dokkatoo/src/main/kotlin/RootPackageClass.kt create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/projects/it-basic/dokkatoo/src/main/kotlin/it/basic/PublicClass.kt create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/projects/it-basic/dokkatoo/src/main/kotlin/it/internal/InternalClass.kt create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/projects/it-basic/dokkatoo/src/main/kotlin/it/overriddenVisibility/VisiblePrivateClass.kt create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/projects/it-basic/dokkatoo/src/main/kotlin/it/protected/ProtectedClass.kt create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/projects/it-basic/dokkatoo/src/main/kotlin/it/suppressedByPackage/SuppressedByPackage.kt create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/projects/it-basic/dokkatoo/src/main/kotlin/it/suppressedByPath/SuppressedByPath.kt create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/projects/it-basic/dokkatoo/src/test/kotlin/it/basic/TestClass.kt create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/projects/it-collector-0/dokka/build.gradle.kts create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/projects/it-collector-0/dokka/moduleA/build.gradle.kts create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/projects/it-collector-0/dokka/moduleA/moduleB/README.md create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/projects/it-collector-0/dokka/moduleA/moduleB/build.gradle.kts create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/projects/it-collector-0/dokka/moduleA/moduleB/src/main/kotlin/org/jetbrains/dokka/it/moduleB/ModuleB.kt create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/projects/it-collector-0/dokka/moduleA/moduleC/README.md create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/projects/it-collector-0/dokka/moduleA/moduleC/build.gradle.kts create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/projects/it-collector-0/dokka/moduleA/moduleC/src/main/kotlin/org/jetbrains/dokka/it/moduleC/ModuleC.kt create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/projects/it-collector-0/dokka/settings.gradle.kts create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/projects/it-collector-0/dokka/template.root.gradle.kts create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/projects/it-collector-0/dokka/template.settings.gradle.kts create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/projects/it-collector-0/dokkatoo/settings.gradle.kts create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/projects/it-js-ir-0/dokka/build.gradle.kts create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/projects/it-js-ir-0/dokka/settings.gradle.kts create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/projects/it-js-ir-0/dokka/src/main/kotlin/RootPackageClass.kt create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/projects/it-js-ir-0/dokka/src/main/kotlin/it/basic/PublicClass.kt create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/projects/it-js-ir-0/dokka/src/main/kotlin/it/internal/InternalClass.kt create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/projects/it-js-ir-0/dokka/src/main/kotlin/it/suppressedByPackage/SuppressedByPackage.kt create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/projects/it-js-ir-0/dokka/src/main/kotlin/it/suppressedByPath/SuppressedByPath.kt create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/projects/it-js-ir-0/dokka/template.root.gradle.kts create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/projects/it-js-ir-0/dokka/template.settings.gradle.kts create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/projects/it-js-ir-0/dokkatoo/settings.gradle.kts create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/projects/it-multimodule-0/dokka/build.gradle.kts create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/projects/it-multimodule-0/dokka/moduleA/build.gradle.kts create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/projects/it-multimodule-0/dokka/moduleA/moduleB/Module.md create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/projects/it-multimodule-0/dokka/moduleA/moduleB/build.gradle.kts create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/projects/it-multimodule-0/dokka/moduleA/moduleB/src/main/kotlin/org/jetbrains/dokka/it/moduleB/ModuleB.kt create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/projects/it-multimodule-0/dokka/moduleA/moduleC/Module.md create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/projects/it-multimodule-0/dokka/moduleA/moduleC/build.gradle.kts create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/projects/it-multimodule-0/dokka/moduleA/moduleC/src/main/kotlin/org/jetbrains/dokka/it/moduleC/ModuleC.kt create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/projects/it-multimodule-0/dokka/moduleA/moduleD/build.gradle.kts create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/projects/it-multimodule-0/dokka/moduleA/moduleD/src/main/kotlin/org/jetbrains/dokka/it/moduleD/ModuleC.kt create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/projects/it-multimodule-0/dokka/settings.gradle.kts create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/projects/it-multimodule-0/dokka/template.root.gradle.kts create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/projects/it-multimodule-0/dokka/template.settings.gradle.kts create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/projects/it-multimodule-0/dokkatoo/settings.gradle.kts create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/projects/it-multimodule-1/dokka/build.gradle create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/projects/it-multimodule-1/dokka/first/build.gradle create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/projects/it-multimodule-1/dokka/first/src/main/kotlin/foo/FirstClass.kt create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/projects/it-multimodule-1/dokka/first/src/main/kotlin/foo/FirstSubclass.kt create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/projects/it-multimodule-1/dokka/first/src/main/kotlin/foo/Main.kt create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/projects/it-multimodule-1/dokka/first/src/main/kotlin/noPackage.kt create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/projects/it-multimodule-1/dokka/second/build.gradle create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/projects/it-multimodule-1/dokka/second/src/main/kotlin/NoPackageClass.kt create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/projects/it-multimodule-1/dokka/second/src/main/kotlin/bar/SecondClass.kt create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/projects/it-multimodule-1/dokka/second/src/main/kotlin/foo/ThirdClass.kt create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/projects/it-multimodule-1/dokka/settings.gradle.kts create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/projects/it-multimodule-1/dokka/template.root.gradle.kts create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/projects/it-multimodule-1/dokka/template.settings.gradle.kts create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/projects/it-multimodule-1/dokkatoo/settings.gradle.kts create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/projects/it-multimodule-versioning-0/dokka/build.gradle create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/projects/it-multimodule-versioning-0/dokka/first/build.gradle create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/projects/it-multimodule-versioning-0/dokka/first/src/main/kotlin/foo/FirstClass.kt create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/projects/it-multimodule-versioning-0/dokka/second/build.gradle create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/projects/it-multimodule-versioning-0/dokka/second/src/main/kotlin/bar/SecondClass.kt create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/projects/it-multimodule-versioning-0/dokka/settings.gradle.kts create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/projects/it-multimodule-versioning-0/dokka/template.root.gradle.kts create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/projects/it-multimodule-versioning-0/dokka/template.settings.gradle.kts create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/projects/it-multimodule-versioning-0/dokkatoo/settings.gradle.kts create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/projects/it-multiplatform-0/dokka/build.gradle.kts create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/projects/it-multiplatform-0/dokka/settings.gradle.kts create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/projects/it-multiplatform-0/dokka/src/commonMain/kotlin/it/mpp0/CommonMainClass.kt create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/projects/it-multiplatform-0/dokka/src/commonMain/kotlin/it/mpp0/ExpectedClass.kt create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/projects/it-multiplatform-0/dokka/src/commonMain/kotlin/it/mpp0/coroutines.kt create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/projects/it-multiplatform-0/dokka/src/desktopMain/kotlin/it/mpp0/CPointerExtension.kt create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/projects/it-multiplatform-0/dokka/src/desktopMain/kotlin/it/mpp0/ExpectedClass.kt create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/projects/it-multiplatform-0/dokka/src/jsMain/kotlin/it/mpp0/ExpectedClass.kt create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/projects/it-multiplatform-0/dokka/src/jsMain/kotlin/it/mpp0/runBlocking.kt create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/projects/it-multiplatform-0/dokka/src/jvmMain/kotlin/it/mpp0/ExpectedClass.kt create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/projects/it-multiplatform-0/dokka/src/jvmMain/kotlin/it/mpp0/JvmOnlyClass.kt create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/projects/it-multiplatform-0/dokka/src/jvmMain/kotlin/it/mpp0/runBlocking.kt create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/projects/it-multiplatform-0/dokka/src/linuxMain/kotlin/it/mpp0/CPointerExtension.kt create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/projects/it-multiplatform-0/dokka/src/linuxMain/kotlin/it/mpp0/ExpectedClass.kt create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/projects/it-multiplatform-0/dokka/src/linuxMain/kotlin/it/mpp0/runBlocking.kt create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/projects/it-multiplatform-0/dokka/src/macosMain/kotlin/it/mpp0/ExpectedClass.kt create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/projects/it-multiplatform-0/dokka/src/macosMain/kotlin/it/mpp0/runBlocking.kt create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/projects/it-multiplatform-0/dokka/template.root.gradle.kts create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/projects/it-multiplatform-0/dokka/template.settings.gradle.kts create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/projects/it-multiplatform-0/dokkatoo/settings.gradle.kts create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/src/testExamples/kotlin/CustomFormatExampleTest.kt create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/src/testExamples/kotlin/GradleExampleTest.kt create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/src/testExamples/kotlin/KotlinMultiplatformExampleTest.kt create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/src/testExamples/kotlin/MultimoduleExampleTest.kt create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/src/testFixtures/kotlin/templateProjectUtils.kt create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/src/testIntegration/kotlin/AndroidProjectIntegrationTest.kt create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/src/testIntegration/kotlin/BasicProjectIntegrationTest.kt create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/src/testIntegration/resources/it/example/dokka-multi-module/childProjectA.json create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/src/testIntegration/resources/it/example/dokka-multi-module/childProjectB.json create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/src/testIntegration/resources/it/example/dokka-multi-module/parentProject.json create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/src/testIntegration/resources/it/example/dokka-multi-module/readme.md create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin/api/dokkatoo-plugin.api create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin/build.gradle.kts create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin/src/main/kotlin/DokkatooBasePlugin.kt create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin/src/main/kotlin/DokkatooExtension.kt create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin/src/main/kotlin/DokkatooPlugin.kt create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin/src/main/kotlin/adapters/DokkatooAndroidAdapter.kt create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin/src/main/kotlin/adapters/DokkatooJavaAdapter.kt create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin/src/main/kotlin/adapters/DokkatooKotlinAdapter.kt create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin/src/main/kotlin/distributions/DokkatooConfigurationAttributes.kt create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin/src/main/kotlin/dokka/DokkaPublication.kt create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin/src/main/kotlin/dokka/parameters/DokkaExternalDocumentationLinkSpec.kt create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin/src/main/kotlin/dokka/parameters/DokkaGeneratorParametersSpec.kt create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin/src/main/kotlin/dokka/parameters/DokkaModuleDescriptionSpec.kt create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin/src/main/kotlin/dokka/parameters/DokkaPackageOptionsSpec.kt create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin/src/main/kotlin/dokka/parameters/DokkaParametersKxs.kt create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin/src/main/kotlin/dokka/parameters/DokkaSourceLinkSpec.kt create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin/src/main/kotlin/dokka/parameters/DokkaSourceSetIdSpec.kt create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin/src/main/kotlin/dokka/parameters/DokkaSourceSetSpec.kt create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin/src/main/kotlin/dokka/parameters/HasConfigurableVisibilityModifiers.kt create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin/src/main/kotlin/dokka/parameters/KotlinPlatform.kt create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin/src/main/kotlin/dokka/parameters/VisibilityModifier.kt create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin/src/main/kotlin/dokka/parameters/builders/DokkaModuleDescriptionBuilder.kt create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin/src/main/kotlin/dokka/parameters/builders/DokkaParametersBuilder.kt create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin/src/main/kotlin/dokka/parameters/builders/DokkaSourceSetBuilder.kt create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin/src/main/kotlin/dokka/plugins/DokkaHtmlPluginParameters.kt create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin/src/main/kotlin/dokka/plugins/DokkaPluginParametersBaseSpec.kt create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin/src/main/kotlin/dokka/plugins/DokkaPluginParametersBuilder.kt create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin/src/main/kotlin/dokka/plugins/DokkaVersioningPluginParameters.kt create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin/src/main/kotlin/formats/DokkatooFormatDependencyContainers.kt create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin/src/main/kotlin/formats/DokkatooFormatPlugin.kt create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin/src/main/kotlin/formats/DokkatooFormatTasks.kt create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin/src/main/kotlin/formats/DokkatooGfmPlugin.kt create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin/src/main/kotlin/formats/DokkatooHtmlPlugin.kt create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin/src/main/kotlin/formats/DokkatooJavadocPlugin.kt create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin/src/main/kotlin/formats/DokkatooJekyllPlugin.kt create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin/src/main/kotlin/internal/DokkatooInternalApi.kt create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin/src/main/kotlin/internal/LoggerAdapter.kt create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin/src/main/kotlin/internal/collectionsUtils.kt create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin/src/main/kotlin/internal/gradleExtensionAccessors.kt create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin/src/main/kotlin/internal/gradleTypealiases.kt create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin/src/main/kotlin/internal/gradleUtils.kt create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin/src/main/kotlin/internal/kotlinxSerializationUtils.kt create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin/src/main/kotlin/internal/stringUtils.kt create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin/src/main/kotlin/internal/uriUtils.kt create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin/src/main/kotlin/tasks/DokkatooGenerateTask.kt create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin/src/main/kotlin/tasks/DokkatooPrepareModuleDescriptorTask.kt create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin/src/main/kotlin/tasks/DokkatooTask.kt create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin/src/main/kotlin/tasks/LogHtmlPublicationLinkTask.kt create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin/src/main/kotlin/workers/DokkaGeneratorWorker.kt create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin/src/test/kotlin/DokkatooPluginTest.kt create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin/src/test/kotlin/dokka/parameters/DokkaExternalDocumentationLinkSpecTest.kt create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin/src/test/kotlin/dokka/parameters/DokkaSourceLinkSpecTest.kt create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin/src/test/kotlin/dokka/parameters/KotlinPlatformTest.kt create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin/src/test/kotlin/dokka/parameters/VisibilityModifierTest.kt create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin/src/test/kotlin/dokka/parameters/builders/DokkaModuleDescriptionBuilderTest.kt create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin/src/test/kotlin/dokka/parameters/builders/DokkaParametersBuilderTest.kt create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin/src/test/kotlin/dokka/parameters/builders/DokkaSourceSetBuilderTest.kt create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin/src/testFixtures/kotlin/GradleTestKitUtils.kt create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin/src/testFixtures/kotlin/KotestProjectConfig.kt create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin/src/testFixtures/kotlin/fileTree.kt create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin/src/testFixtures/kotlin/files.kt create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin/src/testFixtures/kotlin/gradleRunnerUtils.kt create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin/src/testFixtures/kotlin/kotestCollectionMatchers.kt create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin/src/testFixtures/kotlin/kotestConditions.kt create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin/src/testFixtures/kotlin/kotestGradleAssertions.kt create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin/src/testFixtures/kotlin/kotestStringMatchers.kt create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin/src/testFixtures/kotlin/samWithReceiverWorkarounds.kt create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin/src/testFixtures/kotlin/stringUtils.kt create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin/src/testFixtures/kotlin/systemVariableProviders.kt create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin/src/testFixtures/kotlin/text.kt create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin/src/testFunctional/kotlin/DokkatooPluginFunctionalTest.kt create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin/src/testFunctional/kotlin/GradlePluginProjectIntegrationTest.kt create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin/src/testFunctional/kotlin/KotlinMultiplatformFunctionalTest.kt create mode 100644 dokka-runners/dokkatoo/modules/dokkatoo-plugin/src/testFunctional/kotlin/MultiModuleFunctionalTest.kt create mode 100644 dokka-runners/dokkatoo/settings.gradle.kts diff --git a/build-logic/build.gradle.kts b/build-logic/build.gradle.kts index c32bdd25..fedf3403 100644 --- a/build-logic/build.gradle.kts +++ b/build-logic/build.gradle.kts @@ -10,7 +10,7 @@ plugins { kotlin { jvmToolchain { - languageVersion.set(JavaLanguageVersion.of(8)) + languageVersion.set(JavaLanguageVersion.of(11)) } } diff --git a/dokka-runners/dokkatoo/.gitattributes b/dokka-runners/dokkatoo/.gitattributes new file mode 100644 index 00000000..2ba525d5 --- /dev/null +++ b/dokka-runners/dokkatoo/.gitattributes @@ -0,0 +1,51 @@ +# https://help.github.com/articles/dealing-with-line-endings/ +# https://github.com/alexkaratarakis/gitattributes + +* text=auto + +# The above will handle all files NOT found below + +*.json text +*.toml text +*.xml text +*.yaml text +*.yml text +.editorconfig text +.env text + +# Documentation +*.md text diff=markdown +*.txt text +LICENSE text + +# JVM +*.java text diff=java +*.kt text diff=kotlin +*.kts text diff=kotlin +*.properties text +*.jar binary + + +# Linux start script should use lf +gradlew text eol=lf +*.bash text eol=lf +*.sh text eol=lf + +# These are Windows script files and should use crlf +*.bat text eol=crlf +*.cmd text eol=crlf + +# SVG treated as an asset (binary) by default. +*.svg text + +# Exclude external libs from GitHub language stats https://github.com/github/linguist/blob/v7.24.1/docs/overrides.md +examples/** linguist-documentation +examples/*/dokka linguist-vendored +modules/dokkatoo-plugin-integration-tests/projects/**dokka/ linguist-vendored +modules/dokkatoo-plugin-integration-tests/projects/**dokkatoo/ linguist-documentation + +# Exclude files from exporting + +.gitattributes export-ignore +.gitignore export-ignore +.gitkeep export-ignore diff --git a/dokka-runners/dokkatoo/.gitignore b/dokka-runners/dokkatoo/.gitignore new file mode 100644 index 00000000..e733d08a --- /dev/null +++ b/dokka-runners/dokkatoo/.gitignore @@ -0,0 +1,71 @@ +### Gradle ### +.gradle +build/ + +!gradle/wrapper/gradle-wrapper.jar +!gradle/wrapper/gradle-wrapper.properties + + +### Kotlin/JVM ### +*.class +*.log + +hs_err_pid* +replay_pid* +*.hprof + +*.jar +*.war +*.nar +*.ear +*.zip +*.tar.gz +*.rar + + +### IntelliJ ### +.idea/** +!.idea/codeStyles/ +!.idea/codeStyles/** + + +### Eclipse ### +.metadata +bin/ +tmp/ +*.tmp +*.bak +*.swp +*~.nib +.settings/ +.loadpath +.recommenders +.classpath + +.apt_generated/ +.apt_generated_test/ +.project + + +### Linux ### +*~ +.fuse_hidden* +.Trash-* +.nfs* + + +### Windows ### +[Dd]esktop.ini +$RECYCLE.BIN/ +*.lnk + + +### macOS ### +.DS_Store +._* + +# Icon must end with two \r +Icon + + +########################### diff --git a/dokka-runners/dokkatoo/build.gradle.kts b/dokka-runners/dokkatoo/build.gradle.kts new file mode 100644 index 00000000..67184998 --- /dev/null +++ b/dokka-runners/dokkatoo/build.gradle.kts @@ -0,0 +1,47 @@ +import buildsrc.utils.excludeGeneratedGradleDsl +import buildsrc.utils.initIdeProjectLogo + +plugins { + buildsrc.conventions.base + idea +} + +group = "org.jetbrains.dokka.dokkatoo" +version = "2.1.0-SNAPSHOT" + + +idea { + module { + excludeGeneratedGradleDsl(layout) + + excludeDirs.apply { + // exclude .gradle, IDE dirs from nested projects (e.g. example & template projects) + // so IntelliJ project-wide search isn't cluttered with irrelevant files + val excludedDirs = setOf( + ".idea", + ".gradle", + "build", + "gradle/wrapper", + "ANDROID_SDK", + ) + addAll( + projectDir.walk().filter { file -> + excludedDirs.any { + file.invariantSeparatorsPath.endsWith(it) + } + } + ) + } + } +} + +initIdeProjectLogo("modules/docs/images/logo-icon.svg") + +val dokkatooVersion by tasks.registering { + description = "prints the Dokkatoo project version (used during release to verify the version)" + group = "help" + val version = providers.provider { project.version } + doLast { + logger.quiet("${version.orNull}") + } +} diff --git a/dokka-runners/dokkatoo/buildSrc/build.gradle.kts b/dokka-runners/dokkatoo/buildSrc/build.gradle.kts new file mode 100644 index 00000000..832a98b9 --- /dev/null +++ b/dokka-runners/dokkatoo/buildSrc/build.gradle.kts @@ -0,0 +1,19 @@ +import org.gradle.kotlin.dsl.support.expectedKotlinDslPluginsVersion + +plugins { + `kotlin-dsl` +} + +dependencies { + implementation("org.gradle.kotlin:gradle-kotlin-dsl-plugins:$expectedKotlinDslPluginsVersion") + implementation(libs.gradlePlugin.bcvMu) + implementation(libs.gradlePlugin.dokkatoo) + implementation(libs.gradlePlugin.gradlePublishPlugin) + implementation("org.jetbrains.kotlin:kotlin-serialization:$embeddedKotlinVersion") +} + +java { + toolchain { + languageVersion.set(JavaLanguageVersion.of(11)) + } +} diff --git a/dokka-runners/dokkatoo/buildSrc/settings.gradle.kts b/dokka-runners/dokkatoo/buildSrc/settings.gradle.kts new file mode 100644 index 00000000..855fe5d9 --- /dev/null +++ b/dokka-runners/dokkatoo/buildSrc/settings.gradle.kts @@ -0,0 +1,25 @@ +rootProject.name = "buildSrc" + +pluginManagement { + repositories { + mavenCentral() + gradlePluginPortal() + } +} + +@Suppress("UnstableApiUsage") +dependencyResolutionManagement { + + repositoriesMode.set(RepositoriesMode.PREFER_SETTINGS) + + repositories { + mavenCentral() + gradlePluginPortal() + } + + versionCatalogs { + create("libs") { + from(files("../gradle/libs.versions.toml")) + } + } +} diff --git a/dokka-runners/dokkatoo/buildSrc/src/main/kotlin/buildsrc/conventions/android-setup.gradle.kts b/dokka-runners/dokkatoo/buildSrc/src/main/kotlin/buildsrc/conventions/android-setup.gradle.kts new file mode 100644 index 00000000..ed22d799 --- /dev/null +++ b/dokka-runners/dokkatoo/buildSrc/src/main/kotlin/buildsrc/conventions/android-setup.gradle.kts @@ -0,0 +1,78 @@ +package buildsrc.conventions + +import org.jetbrains.kotlin.util.suffixIfNot + + +/** + * Utilities for preparing Android projects + */ + +plugins { + base + id("buildsrc.conventions.base") +} + + +val androidSdkDirPath: Provider = providers + // first try getting the SDK installed on via GitHub step setup-android + .environmentVariable("ANDROID_SDK_ROOT").map(::File) + // else get the project-local SDK + .orElse(layout.projectDirectory.file("projects/ANDROID_SDK").asFile) + .map { it.invariantSeparatorsPath } + + +val createAndroidLocalPropertiesFile by tasks.registering { + + val localPropertiesFile = temporaryDir.resolve("local.properties") + outputs.file(localPropertiesFile).withPropertyName("localPropertiesFile") + + val androidSdkDirPath = androidSdkDirPath + inputs.property("androidSdkDirPath", androidSdkDirPath) + + doLast { + localPropertiesFile.apply { + parentFile.mkdirs() + createNewFile() + writeText( + """ + |# DO NOT EDIT - Generated by $path + | + |sdk.dir=${androidSdkDirPath.get()} + | + """.trimMargin() + ) + } + } +} + + +val updateAndroidLocalProperties by tasks.registering { + + // find all local.properties files + val localPropertiesFiles = layout.projectDirectory.dir("projects") + .asFileTree + .matching { include("**/local.properties") } + .files + + outputs.files(localPropertiesFiles).withPropertyName("localPropertiesFiles") + + val androidSdkDirPath = androidSdkDirPath + inputs.property("androidSdkDirPath", androidSdkDirPath) + + doLast { + localPropertiesFiles + .filter { it.exists() } + .forEach { file -> + file.writeText( + file.useLines { lines -> + lines.joinToString("\n") { line -> + when { + line.startsWith("sdk.dir=") -> "sdk.dir=${androidSdkDirPath.get()}" + else -> line + } + }.suffixIfNot("\n") + } + ) + } + } +} diff --git a/dokka-runners/dokkatoo/buildSrc/src/main/kotlin/buildsrc/conventions/base.gradle.kts b/dokka-runners/dokkatoo/buildSrc/src/main/kotlin/buildsrc/conventions/base.gradle.kts new file mode 100644 index 00000000..60bfa2fe --- /dev/null +++ b/dokka-runners/dokkatoo/buildSrc/src/main/kotlin/buildsrc/conventions/base.gradle.kts @@ -0,0 +1,155 @@ +package buildsrc.conventions + +import java.time.Duration +import org.gradle.api.tasks.testing.logging.TestLogEvent + +/** + * A convention plugin that sets up common config and sensible defaults for all subprojects. + */ + +plugins { + base +} + +if (project != rootProject) { + project.version = rootProject.version + project.group = rootProject.group +} + +tasks.withType().configureEach { + // https://docs.gradle.org/current/userguide/working_with_files.html#sec:reproducible_archives + isPreserveFileTimestamps = false + isReproducibleFileOrder = true +} + +tasks.withType().configureEach { + timeout.set(Duration.ofMinutes(60)) + + testLogging { + showCauses = true + showExceptions = true + showStackTraces = true + showStandardStreams = true + events( + TestLogEvent.PASSED, + TestLogEvent.FAILED, + TestLogEvent.SKIPPED, + TestLogEvent.STARTED, + TestLogEvent.STANDARD_ERROR, + TestLogEvent.STANDARD_OUT, + ) + } +} + +tasks.withType().configureEach { + includeEmptyDirs = false +} + +val updateTestReportCss by tasks.registering { + description = "Hack so the Gradle test reports have dark mode" + // the CSS is based on https://github.com/gradle/gradle/pull/12177 + + mustRunAfter(tasks.withType()) + mustRunAfter(tasks.withType()) + + val cssFiles = layout.buildDirectory.asFileTree.matching { + include("reports/**/css/base-style.css") + include("reports/**/css/style.css") + } + + outputs.files(cssFiles.files) + + doLast { + cssFiles.forEach { cssFile -> + val fileContent = cssFile.readText() + + if ("/* Dark mode */" in fileContent) { + return@forEach + } else { + when (cssFile.name) { + "base-style.css" -> cssFile.writeText( + fileContent + """ + + /* Dark mode */ + @media (prefers-color-scheme: dark) { + html { + background: black; + } + body, a, a:visited { + color: #E7E7E7FF; + } + #footer, #footer a { + color: #cacaca; + } + ul.tabLinks li { + border: solid 1px #cacaca; + background-color: #151515; + } + ul.tabLinks li:hover { + background-color: #383838; + } + ul.tabLinks li.selected { + background-color: #002d32; + border-color: #007987; + } + div.tab th, div.tab table { + border-bottom: solid #d0d0d0 1px; + } + span.code pre { + background-color: #0a0a0a; + border: solid 1px #5f5f5f; + } + } + """.trimIndent() + ) + + "style.css" -> cssFile.writeText( + fileContent + """ + + /* Dark mode */ + @media (prefers-color-scheme: dark) { + .breadcrumbs, .breadcrumbs a { + color: #9b9b9b; + } + #successRate, .summaryGroup { + border: solid 2px #d0d0d0; + } + .success, .success a { + color: #7fff7f; + } + div.success, #successRate.success { + background-color: #001c00; + border-color: #7fff7f; + } + .failures, .failures a { + color: #a30000; + } + .skipped, .skipped a { + color: #a26d13; + } + div.failures, #successRate.failures { + background-color: #170000; + border-color: #a30000; + } + } + """.trimIndent() + ) + } + } + } + } +} + +tasks.withType().configureEach { + finalizedBy(updateTestReportCss) +} + +tasks.withType().configureEach { + finalizedBy(updateTestReportCss) +} + +tasks.matching { it.name == "validatePlugins" }.configureEach { + // prevent warning + // Task ':validatePlugins' uses this output of task ':updateTestReportCss' without declaring an explicit or implicit dependency. + mustRunAfter(updateTestReportCss) +} diff --git a/dokka-runners/dokkatoo/buildSrc/src/main/kotlin/buildsrc/conventions/dokka-source-downloader.gradle.kts b/dokka-runners/dokkatoo/buildSrc/src/main/kotlin/buildsrc/conventions/dokka-source-downloader.gradle.kts new file mode 100644 index 00000000..69e384e1 --- /dev/null +++ b/dokka-runners/dokkatoo/buildSrc/src/main/kotlin/buildsrc/conventions/dokka-source-downloader.gradle.kts @@ -0,0 +1,68 @@ +package buildsrc.conventions + +import buildsrc.settings.DokkaSourceDownloaderSettings +import buildsrc.utils.asConsumer +import buildsrc.utils.asProvider +import buildsrc.utils.dropDirectories +import org.gradle.api.attributes.Usage.USAGE_ATTRIBUTE +import org.gradle.kotlin.dsl.support.serviceOf + +plugins { + id("buildsrc.conventions.base") +} + +val dsdExt: DokkaSourceDownloaderSettings = extensions.create( + DokkaSourceDownloaderSettings.EXTENSION_NAME +) + +val kotlinDokkaSource by configurations.creating { + asConsumer() + attributes { + attribute(USAGE_ATTRIBUTE, objects.named("externals-dokka-src")) + } +} + +val kotlinDokkaSourceElements by configurations.registering { + asProvider() + attributes { + attribute(USAGE_ATTRIBUTE, objects.named("externals-dokka-src")) + } +} + +dependencies { + kotlinDokkaSource(dsdExt.dokkaVersion.map { "kotlin:dokka:$it@zip" }) +} + +val prepareDokkaSource by tasks.registering(Sync::class) { + group = "dokka setup" + description = "Download & unpack Kotlin Dokka source code" + + inputs.property("dokkaVersion", dsdExt.dokkaVersion).optional(false) + + val archives = serviceOf() + + from( + kotlinDokkaSource.incoming + .artifacts + .resolvedArtifacts + .map { artifacts -> + artifacts.map { archives.zipTree(it.file) } + } + ) { + // drop the first dir (dokka-$version) + eachFile { + relativePath = relativePath.dropDirectories(1) + } + } + + into(temporaryDir) + + exclude( + "*.github", + "*.gradle", + "**/gradlew", + "**/gradlew.bat", + "**/gradle/wrapper/gradle-wrapper.jar", + "**/gradle/wrapper/gradle-wrapper.properties", + ) +} diff --git a/dokka-runners/dokkatoo/buildSrc/src/main/kotlin/buildsrc/conventions/dokkatoo-example-projects-base.gradle.kts b/dokka-runners/dokkatoo/buildSrc/src/main/kotlin/buildsrc/conventions/dokkatoo-example-projects-base.gradle.kts new file mode 100644 index 00000000..5c2c45fa --- /dev/null +++ b/dokka-runners/dokkatoo/buildSrc/src/main/kotlin/buildsrc/conventions/dokkatoo-example-projects-base.gradle.kts @@ -0,0 +1,27 @@ +package buildsrc.conventions + +import buildsrc.utils.asConsumer +import buildsrc.utils.asProvider + +plugins { + id("buildsrc.conventions.base") +} + + +val exampleProjectsAttribute: Attribute = + Attribute.of("example-projects", String::class.java) + +dependencies.attributesSchema { + attribute(exampleProjectsAttribute) +} + + +val exampleProjects by configurations.registering { + asConsumer() + attributes { attribute(exampleProjectsAttribute, "dokka") } +} + +val exampleProjectsElements by configurations.registering { + asProvider() + attributes { attribute(exampleProjectsAttribute, "dokka") } +} diff --git a/dokka-runners/dokkatoo/buildSrc/src/main/kotlin/buildsrc/conventions/dokkatoo-example-projects.gradle.kts b/dokka-runners/dokkatoo/buildSrc/src/main/kotlin/buildsrc/conventions/dokkatoo-example-projects.gradle.kts new file mode 100644 index 00000000..c6994a83 --- /dev/null +++ b/dokka-runners/dokkatoo/buildSrc/src/main/kotlin/buildsrc/conventions/dokkatoo-example-projects.gradle.kts @@ -0,0 +1,160 @@ +package buildsrc.conventions + +import buildsrc.settings.* +import buildsrc.tasks.* +import buildsrc.utils.* + +plugins { + id("buildsrc.conventions.base") + id("buildsrc.conventions.dokka-source-downloader") + id("buildsrc.conventions.maven-publish-test") + id("buildsrc.conventions.dokkatoo-example-projects-base") +} + +val mavenPublishTestExtension = extensions.getByType() +val dokkaTemplateProjectSettings = + extensions.create( + DokkaTemplateProjectSettings.EXTENSION_NAME, + { project.copySpec() } + ).apply { + this.destinationBaseDir.convention(layout.projectDirectory) + } + +val prepareDokkaSource by tasks.existing(Sync::class) + +dokkaTemplateProjectSettings.dokkaSourceDir.convention( + prepareDokkaSource.flatMap { + layout.dir(providers.provider { + it.destinationDir + }) + } +) + +tasks.withType().configureEach { + dependsOn(prepareDokkaSource) + + dokkaSourceDir.convention(dokkaTemplateProjectSettings.dokkaSourceDir) + destinationBaseDir.convention(dokkaTemplateProjectSettings.destinationBaseDir) + + templateProjects.addAllLater(provider { + dokkaTemplateProjectSettings.templateProjects + }) +} + +val setupDokkaTemplateProjects by tasks.registering(SetupDokkaProjects::class) + +fun createDokkatooExampleProjectsSettings( + projectDir: Directory = project.layout.projectDirectory +): DokkatooExampleProjectsSettings { + return extensions.create( + DokkatooExampleProjectsSettings.EXTENSION_NAME + ).apply { + + // find all Gradle settings files + val settingsFiles = projectDir.asFileTree + .matching { + include( + "**/*dokkatoo*/**/settings.gradle.kts", + "**/*dokkatoo*/**/settings.gradle", + ) + }.files + + // for each settings file, create a DokkatooExampleProjectSpec + settingsFiles.forEach { + val destinationDir = it.parentFile + val name = destinationDir.toRelativeString(projectDir.asFile).toAlphaNumericCamelCase() + exampleProjects.register(name) { + this.exampleProjectDir.set(destinationDir) + } + } + + exampleProjects.configureEach { + gradlePropertiesContent.add( + mavenPublishTestExtension.testMavenRepoPath.map { testMavenRepoPath -> + "testMavenRepo=$testMavenRepoPath" + } + ) + } + } +} + +val dokkatooExampleProjectsSettings = createDokkatooExampleProjectsSettings() + +val updateDokkatooExamplesGradleProperties by tasks.registering( + UpdateDokkatooExampleProjects::class +) { + group = DokkatooExampleProjectsSettings.TASK_GROUP + + mustRunAfter(tasks.withType()) + + exampleProjects.addAllLater(providers.provider { + dokkatooExampleProjectsSettings.exampleProjects + }) +} + +val dokkatooVersion = provider { project.version.toString() } + +val updateDokkatooExamplesBuildFiles by tasks.registering { + group = DokkatooExampleProjectsSettings.TASK_GROUP + description = "Update the Gradle build files in the Dokkatoo examples" + + outputs.upToDateWhen { false } + + mustRunAfter(tasks.withType()) + shouldRunAfter(updateDokkatooExamplesGradleProperties) + + val dokkatooVersion = dokkatooVersion + + val dokkatooDependencyVersionMatcher = """ + \"dev\.adamko\.dokkatoo\:dokkatoo\-plugin\:([^"]+?)\" + """.trimIndent().toRegex() + + val dokkatooPluginVersionMatcher = """ + id[^"]+?"dev\.adamko\.dokkatoo".+?version "([^"]+?)" + """.trimIndent().toRegex() + + val gradleBuildFiles = + layout.projectDirectory.asFileTree + .matching { + include( + "**/*dokkatoo*/**/build.gradle.kts", + "**/*dokkatoo*/**/build.gradle", + ) + }.elements + outputs.files(gradleBuildFiles) + + doLast { + gradleBuildFiles.get().forEach { fileLocation -> + val file = fileLocation.asFile + if (file.exists()) { + file.writeText( + file.readText() + .replace(dokkatooPluginVersionMatcher) { + val oldVersion = it.groupValues[1] + it.value.replace(oldVersion, dokkatooVersion.get()) + } + .replace(dokkatooDependencyVersionMatcher) { + val oldVersion = it.groupValues[1] + it.value.replace(oldVersion, dokkatooVersion.get()) + } + ) + } + } + } +} + + +val updateDokkatooExamples by tasks.registering { + group = DokkatooExampleProjectsSettings.TASK_GROUP + description = "lifecycle task for all '${DokkatooExampleProjectsSettings.TASK_GROUP}' tasks" + dependsOn( + setupDokkaTemplateProjects, + updateDokkatooExamplesGradleProperties, + updateDokkatooExamplesBuildFiles, + ) +} + +tasks.assemble { + dependsOn(updateDokkatooExamples) + dependsOn(setupDokkaTemplateProjects) +} diff --git a/dokka-runners/dokkatoo/buildSrc/src/main/kotlin/buildsrc/conventions/gradle-plugin-variants.gradle.kts b/dokka-runners/dokkatoo/buildSrc/src/main/kotlin/buildsrc/conventions/gradle-plugin-variants.gradle.kts new file mode 100644 index 00000000..1d9fc43b --- /dev/null +++ b/dokka-runners/dokkatoo/buildSrc/src/main/kotlin/buildsrc/conventions/gradle-plugin-variants.gradle.kts @@ -0,0 +1,44 @@ +package buildsrc.conventions + +import org.gradle.api.attributes.plugin.GradlePluginApiVersion.GRADLE_PLUGIN_API_VERSION_ATTRIBUTE + +plugins { + id("buildsrc.conventions.base") + `java-gradle-plugin` +} + +fun registerGradleVariant(name: String, gradleVersion: String) { + val variantSources = sourceSets.create(name) + + java { + registerFeature(variantSources.name) { + usingSourceSet(variantSources) + capability("${project.group}", "${project.name}", "${project.version}") + + withJavadocJar() + withSourcesJar() + } + } + + configurations + .matching { it.isCanBeConsumed && it.name.startsWith(variantSources.name) } + .configureEach { + attributes { + attribute(GRADLE_PLUGIN_API_VERSION_ATTRIBUTE, objects.named(gradleVersion)) + } + } + + tasks.named(variantSources.processResourcesTaskName) { + val copyPluginDescriptors = rootSpec.addChild() + copyPluginDescriptors.into("META-INF/gradle-plugins") +// copyPluginDescriptors.into(tasks.pluginDescriptors.flatMap { it.outputDirectory }) + copyPluginDescriptors.from(tasks.pluginDescriptors) + } + + dependencies { + add(variantSources.compileOnlyConfigurationName, gradleApi()) + } +} + +registerGradleVariant("gradle7", "7.6") +registerGradleVariant("gradle8", "8.0") diff --git a/dokka-runners/dokkatoo/buildSrc/src/main/kotlin/buildsrc/conventions/java-base.gradle.kts b/dokka-runners/dokkatoo/buildSrc/src/main/kotlin/buildsrc/conventions/java-base.gradle.kts new file mode 100644 index 00000000..203b80f2 --- /dev/null +++ b/dokka-runners/dokkatoo/buildSrc/src/main/kotlin/buildsrc/conventions/java-base.gradle.kts @@ -0,0 +1,19 @@ +package buildsrc.conventions + +import org.gradle.api.JavaVersion +import org.gradle.api.plugins.JavaPluginExtension +import org.gradle.jvm.toolchain.JavaLanguageVersion +import org.gradle.kotlin.dsl.getByType +import org.gradle.kotlin.dsl.`java-base` + +plugins { + id("buildsrc.conventions.base") + `java` +} + +extensions.getByType().apply { + toolchain { + languageVersion.set(JavaLanguageVersion.of(11)) + } + withSourcesJar() +} diff --git a/dokka-runners/dokkatoo/buildSrc/src/main/kotlin/buildsrc/conventions/kotlin-gradle-plugin.gradle.kts b/dokka-runners/dokkatoo/buildSrc/src/main/kotlin/buildsrc/conventions/kotlin-gradle-plugin.gradle.kts new file mode 100644 index 00000000..4174088a --- /dev/null +++ b/dokka-runners/dokkatoo/buildSrc/src/main/kotlin/buildsrc/conventions/kotlin-gradle-plugin.gradle.kts @@ -0,0 +1,37 @@ +package buildsrc.conventions + +plugins { + id("buildsrc.conventions.base") + id("buildsrc.conventions.java-base") + id("org.gradle.kotlin.kotlin-dsl") + id("com.gradle.plugin-publish") +} + +tasks.validatePlugins { + enableStricterValidation.set(true) +} + +val createJavadocJarReadme by tasks.registering(Sync::class) { + description = "generate a readme.txt for the Javadoc JAR" + from( + resources.text.fromString( + """ + This Javadoc JAR is intentionally empty. + + For documentation, see the sources JAR or https://github.com/adamko-dev/dokkatoo/ + + """.trimIndent() + ) + ) { + rename { "readme.txt" } + } + into(temporaryDir) +} + + +// The Gradle Publish Plugin enables the Javadoc JAR in afterEvaluate, so find it lazily +tasks.withType() + .matching { it.name == "javadocJar" } + .configureEach { + from(createJavadocJarReadme) + } diff --git a/dokka-runners/dokkatoo/buildSrc/src/main/kotlin/buildsrc/conventions/maven-publish-test.gradle.kts b/dokka-runners/dokkatoo/buildSrc/src/main/kotlin/buildsrc/conventions/maven-publish-test.gradle.kts new file mode 100644 index 00000000..38678b5b --- /dev/null +++ b/dokka-runners/dokkatoo/buildSrc/src/main/kotlin/buildsrc/conventions/maven-publish-test.gradle.kts @@ -0,0 +1,93 @@ +package buildsrc.conventions + +import buildsrc.settings.MavenPublishTestSettings +import buildsrc.utils.* + + +/** Utility for publishing a project to a local Maven directory for use in integration tests. */ + +plugins { + base +} + +val Gradle.rootGradle: Gradle get() = generateSequence(gradle) { it.parent }.last() + +val mavenPublishTestExtension = extensions.create( + "mavenPublishTest", + gradle.rootGradle.rootProject.layout.buildDirectory.dir("test-maven-repo"), +) + + +val publishToTestMavenRepo by tasks.registering { + group = PublishingPlugin.PUBLISH_TASK_GROUP + description = "Publishes all Maven publications to the test Maven repository." +} + + +plugins.withType().all { + extensions + .getByType() + .publications + .withType().all publication@{ + val publicationName = this@publication.name + val installTaskName = "publish${publicationName.uppercaseFirstChar()}PublicationToTestMavenRepo" + + // Register a publication task for each publication. + // Use PublishToMavenLocal, because the PublishToMavenRepository task will *always* create + // a new jar, even if nothing has changed, and append a timestamp, which results in a large + // directory and tasks are never up-to-date. + // PublishToMavenLocal does not append a timestamp, so the target directory is smaller, and + // up-to-date checks work. + val installTask = tasks.register(installTaskName) { + description = "Publishes Maven publication '$publicationName' to the test Maven repository." + group = PublishingPlugin.PUBLISH_TASK_GROUP + outputs.cacheIf { true } + publication = this@publication + val destinationDir = mavenPublishTestExtension.testMavenRepo.get().asFile + inputs.property("testMavenRepoTempDir", destinationDir.invariantSeparatorsPath) + doFirst { + /** + * `maven.repo.local` will set the destination directory for this [PublishToMavenLocal] task. + * + * @see org.gradle.api.internal.artifacts.mvnsettings.DefaultLocalMavenRepositoryLocator.getLocalMavenRepository + */ + System.setProperty("maven.repo.local", destinationDir.absolutePath) + } + } + + publishToTestMavenRepo.configure { + dependsOn(installTask) + } + + tasks.check { + mustRunAfter(installTask) + } + } +} + + +val testMavenPublication by configurations.registering { + asConsumer() + attributes { + attribute(MavenPublishTestSettings.attribute, "testMavenRepo") + } +} + +val testMavenPublicationElements by configurations.registering { + asProvider() + extendsFrom(testMavenPublication.get()) + attributes { + attribute(MavenPublishTestSettings.attribute, "testMavenRepo") + } + outgoing { + artifact(mavenPublishTestExtension.testMavenRepo) { + builtBy(publishToTestMavenRepo) + } + } +} + +dependencies { + attributesSchema { + attribute(MavenPublishTestSettings.attribute) + } +} diff --git a/dokka-runners/dokkatoo/buildSrc/src/main/kotlin/buildsrc/conventions/maven-publishing.gradle.kts b/dokka-runners/dokkatoo/buildSrc/src/main/kotlin/buildsrc/conventions/maven-publishing.gradle.kts new file mode 100644 index 00000000..7af7b69f --- /dev/null +++ b/dokka-runners/dokkatoo/buildSrc/src/main/kotlin/buildsrc/conventions/maven-publishing.gradle.kts @@ -0,0 +1,137 @@ +package buildsrc.conventions + +import buildsrc.settings.MavenPublishingSettings + +plugins { + `maven-publish` + signing +} + +val mavenPublishing = + extensions.create(MavenPublishingSettings.EXTENSION_NAME, project) + + +//region POM convention +publishing { + publications.withType().configureEach { + pom { + name.convention("Dokkatoo") + description.convention("Dokkatoo is a Gradle plugin that generates documentation for your Kotlin projects") + url.convention("https://github.com/adamko-dev/dokkatoo") + + scm { + connection.convention("scm:git:https://github.com/adamko-dev/dokkatoo") + developerConnection.convention("scm:git:https://github.com/adamko-dev/dokkatoo") + url.convention("https://github.com/adamko-dev/dokkatoo") + } + + licenses { + license { + name.convention("Apache-2.0") + url.convention("https://www.apache.org/licenses/LICENSE-2.0.txt") + } + } + + developers { + developer { + email.set("adam@adamko.dev") + } + } + } + } +} +//endregion + + +//region GitHub branch publishing +publishing { + repositories { + maven(mavenPublishing.githubPublishDir) { + name = "GitHubPublish" + } + } +} +//endregion + + +//region Maven Central publishing/signing +publishing { + repositories { + val mavenCentralUsername = mavenPublishing.mavenCentralUsername.orNull + val mavenCentralPassword = mavenPublishing.mavenCentralPassword.orNull + if (!mavenCentralUsername.isNullOrBlank() && !mavenCentralPassword.isNullOrBlank()) { + maven(mavenPublishing.sonatypeReleaseUrl) { + name = "SonatypeRelease" + credentials { + username = mavenCentralUsername + password = mavenCentralPassword + } + } + } + } + + // com.gradle.plugin-publish automatically adds a Javadoc jar +} + +signing { + logger.info("maven-publishing.gradle.kts enabled signing for ${project.path}") + + val keyId = mavenPublishing.signingKeyId.orNull + val key = mavenPublishing.signingKey.orNull + val password = mavenPublishing.signingPassword.orNull + + if (!keyId.isNullOrBlank() && !key.isNullOrBlank() && !password.isNullOrBlank()) { + useInMemoryPgpKeys(keyId, key, password) + } + + setRequired({ + gradle.taskGraph.allTasks.filterIsInstance().any { + it.repository.name == "SonatypeRelease" + } + }) +} + +//afterEvaluate { +// com.gradle.plugin-publish automatically signs tasks in a weird way, that stops this from working: +// signing { +// sign(publishing.publications) +// } +//} +//endregion + + +//region Fix Gradle warning about signing tasks using publishing task outputs without explicit dependencies +// https://youtrack.jetbrains.com/issue/KT-46466 https://github.com/gradle/gradle/issues/26091 +tasks.withType().configureEach { + val signingTasks = tasks.withType() + mustRunAfter(signingTasks) +} +//endregion + + +//region publishing logging +tasks.withType().configureEach { + val publicationGAV = provider { publication?.run { "$group:$artifactId:$version" } } + doLast("log publication GAV") { + if (publicationGAV.isPresent) { + logger.lifecycle("[task: ${path}] ${publicationGAV.get()}") + } + } +} +//endregion + + +//region IJ workarounds +// manually define the Kotlin DSL accessors because IntelliJ _still_ doesn't load them properly +fun Project.publishing(configure: PublishingExtension.() -> Unit): Unit = + extensions.configure(configure) + +val Project.publishing: PublishingExtension + get() = extensions.getByType() + +fun Project.signing(configure: SigningExtension.() -> Unit): Unit = + extensions.configure(configure) + +val Project.signing: SigningExtension + get() = extensions.getByType() +//endregion diff --git a/dokka-runners/dokkatoo/buildSrc/src/main/kotlin/buildsrc/settings/DokkaSourceDownloaderSettings.kt b/dokka-runners/dokkatoo/buildSrc/src/main/kotlin/buildsrc/settings/DokkaSourceDownloaderSettings.kt new file mode 100644 index 00000000..c3f9906c --- /dev/null +++ b/dokka-runners/dokkatoo/buildSrc/src/main/kotlin/buildsrc/settings/DokkaSourceDownloaderSettings.kt @@ -0,0 +1,13 @@ +package buildsrc.settings + +import org.gradle.api.plugins.ExtensionAware +import org.gradle.api.provider.Property + +abstract class DokkaSourceDownloaderSettings : ExtensionAware { + + abstract val dokkaVersion: Property + + companion object { + const val EXTENSION_NAME = "dokkaSourceDownload" + } +} diff --git a/dokka-runners/dokkatoo/buildSrc/src/main/kotlin/buildsrc/settings/DokkaTemplateProjectSettings.kt b/dokka-runners/dokkatoo/buildSrc/src/main/kotlin/buildsrc/settings/DokkaTemplateProjectSettings.kt new file mode 100644 index 00000000..7bacafb9 --- /dev/null +++ b/dokka-runners/dokkatoo/buildSrc/src/main/kotlin/buildsrc/settings/DokkaTemplateProjectSettings.kt @@ -0,0 +1,96 @@ +package buildsrc.settings + +import buildsrc.utils.adding +import buildsrc.utils.domainObjectContainer +import buildsrc.utils.toAlphaNumericCamelCase +import javax.inject.Inject +import org.gradle.api.Named +import org.gradle.api.NamedDomainObjectContainer +import org.gradle.api.file.ConfigurableFileCollection +import org.gradle.api.file.CopySpec +import org.gradle.api.file.DirectoryProperty +import org.gradle.api.model.ObjectFactory +import org.gradle.api.plugins.ExtensionAware +import org.gradle.api.provider.Property +import org.gradle.api.provider.SetProperty +import org.gradle.api.tasks.Input +import org.gradle.api.tasks.InputFiles +import org.gradle.api.tasks.Internal +import org.gradle.api.tasks.Optional +import org.gradle.kotlin.dsl.* + +private typealias TemplateProjectsContainer = NamedDomainObjectContainer + +abstract class DokkaTemplateProjectSettings @Inject constructor( + private val objects: ObjectFactory, + private val copySpecs: () -> CopySpec +) : ExtensionAware { + + /** Directory that will contain the projects downloaded from the Dokka source code. */ + abstract val dokkaSourceDir: DirectoryProperty + + abstract val destinationBaseDir: DirectoryProperty + + internal val templateProjects: TemplateProjectsContainer = + // create an extension so Gradle will generate DSL accessors + extensions.adding("templateProjects", objects.domainObjectContainer { name -> + objects.newInstance(name, copySpecs()) + }) + + /** + * Copy a directory from the Dokka source project into a local directory. + * + * @param[source] Source dir, relative to [templateProjectsDir] + * @param[destination] Destination dir, relative to [destinationBaseDir] + */ + fun register( + source: String, + destination: String, + configure: DokkaTemplateProjectSpec.() -> Unit = {}, + ) { + val name = source.toAlphaNumericCamelCase() + templateProjects.register(name) { + this.sourcePath.set(source) + this.destinationPath.set(destination) + configure() + } + } + + fun configureEach(configure: DokkaTemplateProjectSpec.() -> Unit) { + templateProjects.configureEach(configure) + } + + /** + * Details for how to copy a Dokka template project from the Dokka project to a local directory. + */ + abstract class DokkaTemplateProjectSpec @Inject constructor( + private val named: String, + @get:Internal + internal val copySpec: CopySpec, + ) : Named { + + @get:Input + abstract val sourcePath: Property + + @get:Input + @get:Optional + abstract val destinationPath: Property + + @get:Input + abstract val additionalPaths: SetProperty + + @get:InputFiles + abstract val additionalFiles: ConfigurableFileCollection + + fun configureCopy(configure: CopySpec.() -> Unit) { + copySpec.configure() + } + + @Input + override fun getName(): String = named + } + + companion object { + const val EXTENSION_NAME = "dokkaTemplateProjects" + } +} diff --git a/dokka-runners/dokkatoo/buildSrc/src/main/kotlin/buildsrc/settings/DokkatooExampleProjectsSettings.kt b/dokka-runners/dokkatoo/buildSrc/src/main/kotlin/buildsrc/settings/DokkatooExampleProjectsSettings.kt new file mode 100644 index 00000000..a3124904 --- /dev/null +++ b/dokka-runners/dokkatoo/buildSrc/src/main/kotlin/buildsrc/settings/DokkatooExampleProjectsSettings.kt @@ -0,0 +1,62 @@ +package buildsrc.settings + +import buildsrc.utils.adding +import buildsrc.utils.domainObjectContainer +import javax.inject.Inject +import org.gradle.api.Named +import org.gradle.api.NamedDomainObjectContainer +import org.gradle.api.file.DirectoryProperty +import org.gradle.api.file.RegularFile +import org.gradle.api.model.ObjectFactory +import org.gradle.api.plugins.ExtensionAware +import org.gradle.api.provider.ListProperty +import org.gradle.api.provider.Provider +import org.gradle.api.tasks.Input +import org.gradle.api.tasks.Internal +import org.gradle.api.tasks.Optional +import org.gradle.api.tasks.OutputFile + +/** + * Settings for the [buildsrc.conventions.Dokkatoo_example_projects_gradle] convention plugin + */ +abstract class DokkatooExampleProjectsSettings @Inject constructor( + objects: ObjectFactory, +) : ExtensionAware { + + val exampleProjects: NamedDomainObjectContainer = + // create an extension so Gradle will generate DSL accessors + extensions.adding("exampleProjects", objects.domainObjectContainer()) + + abstract class DokkatooExampleProjectSpec( + private val name: String + ): Named { + + /** The `gradle.properties` file of the example project */ + @get:OutputFile + val gradlePropertiesFile: Provider + get() = exampleProjectDir.file("gradle.properties") + + /** The directory that contains the example project */ + @get:Internal + abstract val exampleProjectDir: DirectoryProperty + + /** + * Content to add to the `gradle.properties` file. + * + * Elements may span multiple lines. + * + * Elements will be sorted before appending to the file (to improve caching & reproducibility). + */ + @get:Input + @get:Optional + abstract val gradlePropertiesContent: ListProperty + + @Input + override fun getName(): String = name + } + + companion object { + const val TASK_GROUP = "dokkatoo examples" + const val EXTENSION_NAME = "dokkatooExampleProjects" + } +} diff --git a/dokka-runners/dokkatoo/buildSrc/src/main/kotlin/buildsrc/settings/MavenPublishTestSettings.kt b/dokka-runners/dokkatoo/buildSrc/src/main/kotlin/buildsrc/settings/MavenPublishTestSettings.kt new file mode 100644 index 00000000..0a701986 --- /dev/null +++ b/dokka-runners/dokkatoo/buildSrc/src/main/kotlin/buildsrc/settings/MavenPublishTestSettings.kt @@ -0,0 +1,19 @@ +package buildsrc.settings + +import org.gradle.api.attributes.Attribute +import org.gradle.api.file.Directory +import org.gradle.api.plugins.ExtensionAware +import org.gradle.api.provider.Provider + +/** + * Settings for the [buildsrc.conventions.Maven_publish_test_gradle] convention plugin. + */ +abstract class MavenPublishTestSettings( + val testMavenRepo: Provider +) : ExtensionAware { + val testMavenRepoPath: Provider = testMavenRepo.map { it.asFile.invariantSeparatorsPath } + + companion object { + val attribute = Attribute.of("maven-publish-test", String::class.java) + } +} diff --git a/dokka-runners/dokkatoo/buildSrc/src/main/kotlin/buildsrc/settings/MavenPublishingSettings.kt b/dokka-runners/dokkatoo/buildSrc/src/main/kotlin/buildsrc/settings/MavenPublishingSettings.kt new file mode 100644 index 00000000..9ec28faa --- /dev/null +++ b/dokka-runners/dokkatoo/buildSrc/src/main/kotlin/buildsrc/settings/MavenPublishingSettings.kt @@ -0,0 +1,68 @@ +package buildsrc.settings + +import java.io.File +import javax.inject.Inject +import org.gradle.api.Project +import org.gradle.api.provider.Provider +import org.gradle.api.provider.ProviderFactory +import org.gradle.kotlin.dsl.* + + +/** + * Settings for the [buildsrc.conventions.Maven_publish_test_gradle] convention plugin. + */ +abstract class MavenPublishingSettings @Inject constructor( + private val project: Project, + private val providers: ProviderFactory, +) { + + private val isReleaseVersion: Provider = + providers.provider { !project.version.toString().endsWith("-SNAPSHOT") } + + val sonatypeReleaseUrl: Provider = + isReleaseVersion.map { isRelease -> + if (isRelease) { + "https://s01.oss.sonatype.org/service/local/staging/deploy/maven2/" + } else { + "https://s01.oss.sonatype.org/content/repositories/snapshots/" + } + } + + val mavenCentralUsername: Provider = + d2Prop("mavenCentralUsername") + .orElse(providers.environmentVariable("MAVEN_SONATYPE_USERNAME")) + val mavenCentralPassword: Provider = + d2Prop("mavenCentralPassword") + .orElse(providers.environmentVariable("MAVEN_SONATYPE_PASSWORD")) + + val signingKeyId: Provider = + d2Prop("signing.keyId") + .orElse(providers.environmentVariable("MAVEN_SONATYPE_SIGNING_KEY_ID")) + val signingKey: Provider = + d2Prop("signing.key") + .orElse(providers.environmentVariable("MAVEN_SONATYPE_SIGNING_KEY")) + val signingPassword: Provider = + d2Prop("signing.password") + .orElse(providers.environmentVariable("MAVEN_SONATYPE_SIGNING_PASSWORD")) + + val githubPublishDir: Provider = + providers.environmentVariable("GITHUB_PUBLISH_DIR").map { File(it) } + + private fun d2Prop(name: String): Provider = + providers.gradleProperty("org.jetbrains.dokka.dokkatoo.$name") + + private fun d2Prop(name: String, convert: (String) -> T): Provider = + d2Prop(name).map(convert) + + companion object { + const val EXTENSION_NAME = "mavenPublishing" + + /** Retrieve the [KayrayBuildProperties] extension. */ + internal val Project.mavenPublishing: MavenPublishingSettings + get() = extensions.getByType() + + /** Configure the [KayrayBuildProperties] extension. */ + internal fun Project.mavenPublishing(configure: MavenPublishingSettings.() -> Unit) = + extensions.configure(configure) + } +} diff --git a/dokka-runners/dokkatoo/buildSrc/src/main/kotlin/buildsrc/tasks/SetupDokkaProjects.kt b/dokka-runners/dokkatoo/buildSrc/src/main/kotlin/buildsrc/tasks/SetupDokkaProjects.kt new file mode 100644 index 00000000..d473d287 --- /dev/null +++ b/dokka-runners/dokkatoo/buildSrc/src/main/kotlin/buildsrc/tasks/SetupDokkaProjects.kt @@ -0,0 +1,73 @@ +package buildsrc.tasks + +import buildsrc.settings.DokkaTemplateProjectSettings.DokkaTemplateProjectSpec +import javax.inject.Inject +import org.gradle.api.DefaultTask +import org.gradle.api.NamedDomainObjectContainer +import org.gradle.api.file.DirectoryProperty +import org.gradle.api.file.FileCollection +import org.gradle.api.file.FileSystemOperations +import org.gradle.api.file.ProjectLayout +import org.gradle.api.provider.ProviderFactory +import org.gradle.api.tasks.* + +abstract class SetupDokkaProjects @Inject constructor( + private val fs: FileSystemOperations, + private val layout: ProjectLayout, + private val providers: ProviderFactory, +) : DefaultTask() { + + @get:OutputDirectories + val destinationDirs: FileCollection + get() = layout.files( + destinationBaseDir.map { base -> + templateProjects.map { spec -> base.dir(spec.destinationPath) } + } + ) + + @get:Internal // tracked by destinationDirs + abstract val destinationBaseDir: DirectoryProperty + + @get:Nested + abstract val templateProjects: NamedDomainObjectContainer + + @get:InputDirectory + abstract val dokkaSourceDir: DirectoryProperty + + @get:InputFiles + val additionalFiles: FileCollection + get() = layout.files( + providers.provider { + templateProjects.map { it.additionalFiles } + } + ) + + init { + group = "dokka examples" + } + + @TaskAction + internal fun action() { + val dokkaSourceDir = dokkaSourceDir.get() + val destinationBaseDir = destinationBaseDir.get() + val templateProjects = templateProjects.filter { it.destinationPath.isPresent } + + templateProjects.forEach { spec -> + fs.sync { + with(spec.copySpec) + + from(dokkaSourceDir.dir(spec.sourcePath)) + + from( + spec.additionalPaths.get().map { additionalPath -> + dokkaSourceDir.asFile.resolve(additionalPath) + } + ) + + from(spec.additionalFiles) + + into(destinationBaseDir.dir(spec.destinationPath)) + } + } + } +} diff --git a/dokka-runners/dokkatoo/buildSrc/src/main/kotlin/buildsrc/tasks/UpdateDokkatooExampleProjects.kt b/dokka-runners/dokkatoo/buildSrc/src/main/kotlin/buildsrc/tasks/UpdateDokkatooExampleProjects.kt new file mode 100644 index 00000000..7737e098 --- /dev/null +++ b/dokka-runners/dokkatoo/buildSrc/src/main/kotlin/buildsrc/tasks/UpdateDokkatooExampleProjects.kt @@ -0,0 +1,49 @@ +package buildsrc.tasks + +import buildsrc.settings.DokkatooExampleProjectsSettings.DokkatooExampleProjectSpec +import javax.inject.Inject +import org.gradle.api.DefaultTask +import org.gradle.api.NamedDomainObjectContainer +import org.gradle.api.model.ObjectFactory +import org.gradle.api.tasks.CacheableTask +import org.gradle.api.tasks.Internal +import org.gradle.api.tasks.Nested +import org.gradle.api.tasks.TaskAction + +/** + * Utility for updating the `gradle.properties` of projects used in automated tests. + */ +@CacheableTask +abstract class UpdateDokkatooExampleProjects @Inject constructor( + @get:Internal + val objects: ObjectFactory +) : DefaultTask() { + + @get:Nested + abstract val exampleProjects: NamedDomainObjectContainer + + private val taskPath: String = path // renamed for clarity + + @TaskAction + fun update() { + exampleProjects.forEach { exampleProject -> + updateGradleProperties(exampleProject) + } + } + + private fun updateGradleProperties(exampleProject: DokkatooExampleProjectSpec) { + + val gradlePropertiesContent = exampleProject.gradlePropertiesContent.orNull?.sorted() ?: return + + val content = buildString { + appendLine("# DO NOT EDIT - Generated by $taskPath") + appendLine() + + gradlePropertiesContent.forEach { + appendLine(it) + } + } + + exampleProject.gradlePropertiesFile.get().asFile.writeText(content) + } +} diff --git a/dokka-runners/dokkatoo/buildSrc/src/main/kotlin/buildsrc/utils/gradle.kt b/dokka-runners/dokkatoo/buildSrc/src/main/kotlin/buildsrc/utils/gradle.kt new file mode 100644 index 00000000..0af662d4 --- /dev/null +++ b/dokka-runners/dokkatoo/buildSrc/src/main/kotlin/buildsrc/utils/gradle.kt @@ -0,0 +1,118 @@ +package buildsrc.utils + +import java.io.File +import org.gradle.api.NamedDomainObjectContainer +import org.gradle.api.NamedDomainObjectFactory +import org.gradle.api.Project +import org.gradle.api.artifacts.Configuration +import org.gradle.api.component.AdhocComponentWithVariants +import org.gradle.api.file.RelativePath +import org.gradle.api.model.ObjectFactory +import org.gradle.api.plugins.ExtensionContainer +import org.gradle.kotlin.dsl.* + +/** + * Mark this [Configuration] as one that will be consumed by other subprojects. + * + * ``` + * isCanBeResolved = false + * isCanBeConsumed = true + * ``` + */ +fun Configuration.asProvider( + visible: Boolean = true +) { + isVisible = visible + isCanBeResolved = false + isCanBeConsumed = true +} + +/** + * Mark this [Configuration] as one that will consume artifacts from other subprojects (also known as 'resolving') + * + * ``` + * isCanBeResolved = true + * isCanBeConsumed = false + * ``` + * */ +fun Configuration.asConsumer( + visible: Boolean = false +) { + isVisible = visible + isCanBeResolved = true + isCanBeConsumed = false +} + + +/** Drop the first [count] directories from the path */ +fun RelativePath.dropDirectories(count: Int): RelativePath = + RelativePath(true, *segments.drop(count).toTypedArray()) + + +/** Drop the first directory from the path */ +fun RelativePath.dropDirectory(): RelativePath = + dropDirectories(1) + + +/** Drop the first directory from the path */ +fun RelativePath.dropDirectoriesWhile( + segmentPrediate: (segment: String) -> Boolean +): RelativePath = + RelativePath( + true, + *segments.dropWhile(segmentPrediate).toTypedArray(), + ) + + +/** + * Don't publish test fixtures (which causes warnings when publishing) + * + * https://docs.gradle.org/current/userguide/java_testing.html#publishing_test_fixtures + */ +fun Project.skipTestFixturesPublications() { + val javaComponent = components["java"] as AdhocComponentWithVariants + javaComponent.withVariantsFromConfiguration(configurations["testFixturesApiElements"]) { skip() } + javaComponent.withVariantsFromConfiguration(configurations["testFixturesRuntimeElements"]) { skip() } +} + + +/** + * Add an extension to the [ExtensionContainer], and return the value. + * + * Adding an extension is especially useful for improving the DSL in build scripts when [T] is a + * [NamedDomainObjectContainer]. + * Using an extension will allow Gradle to generate + * [type-safe model accessors](https://docs.gradle.org/current/userguide/kotlin_dsl.html#kotdsl:accessor_applicability) + * for added types. + * + * ([name] should match the property name. This has to be done manually. I tried using a + * delegated-property provider but then Gradle can't introspect the types properly, so it fails to + * create accessors). + */ +internal inline fun ExtensionContainer.adding( + name: String, + value: T, +): T { + add(name, value) + return value +} + +/** + * Create a new [NamedDomainObjectContainer], using + * [org.gradle.kotlin.dsl.domainObjectContainer] + * (but [T] is `reified`). + * + * @param[factory] an optional factory for creating elements + * @see org.gradle.kotlin.dsl.domainObjectContainer + */ +internal inline fun ObjectFactory.domainObjectContainer( + factory: NamedDomainObjectFactory? = null +): NamedDomainObjectContainer = + if (factory == null) { + domainObjectContainer(T::class) + } else { + domainObjectContainer(T::class, factory) + } + +/** workaround for the overly verbose replacement for the deprecated [Project.getBuildDir] property */ +val Project.buildDir_: File get() = layout.buildDirectory.get().asFile diff --git a/dokka-runners/dokkatoo/buildSrc/src/main/kotlin/buildsrc/utils/intellij.kt b/dokka-runners/dokkatoo/buildSrc/src/main/kotlin/buildsrc/utils/intellij.kt new file mode 100644 index 00000000..f93e7683 --- /dev/null +++ b/dokka-runners/dokkatoo/buildSrc/src/main/kotlin/buildsrc/utils/intellij.kt @@ -0,0 +1,45 @@ +package buildsrc.utils + +import org.gradle.api.Project +import org.gradle.api.file.ProjectLayout +import org.gradle.plugins.ide.idea.model.IdeaModule + + +/** exclude generated Gradle code, so it doesn't clog up search results */ +fun IdeaModule.excludeGeneratedGradleDsl(layout: ProjectLayout) { + + val generatedSrcDirs = listOf( + "kotlin-dsl-accessors", + "kotlin-dsl-external-plugin-spec-builders", + "kotlin-dsl-plugins", + ) + + excludeDirs.addAll( + layout.projectDirectory.asFile.walk() + .filter { it.isDirectory && it.parentFile.name in generatedSrcDirs } + .flatMap { file -> + file.walk().maxDepth(1).filter { it.isDirectory }.toList() + } + ) +} + + +/** Sets a logo for project IDEs */ +fun Project.initIdeProjectLogo( + svgLogoPath: String +) { + val logoSvg = rootProject.layout.projectDirectory.file(svgLogoPath) + val ideaDir = rootProject.layout.projectDirectory.dir(".idea") + + if ( + logoSvg.asFile.exists() + && ideaDir.asFile.exists() + && !ideaDir.file("icon.png").asFile.exists() + && !ideaDir.file("icon.svg").asFile.exists() + ) { + copy { + from(logoSvg) { rename { "icon.svg" } } + into(ideaDir) + } + } +} diff --git a/dokka-runners/dokkatoo/buildSrc/src/main/kotlin/buildsrc/utils/strings.kt b/dokka-runners/dokkatoo/buildSrc/src/main/kotlin/buildsrc/utils/strings.kt new file mode 100644 index 00000000..6a0749ce --- /dev/null +++ b/dokka-runners/dokkatoo/buildSrc/src/main/kotlin/buildsrc/utils/strings.kt @@ -0,0 +1,26 @@ +package buildsrc.utils + + +/** Title case the first char of a string */ +internal fun String.uppercaseFirstChar(): String = mapFirstChar(Character::toTitleCase) + + +/** Lowercase the first char of a string */ +internal fun String.lowercaseFirstChar(): String = mapFirstChar(Character::toLowerCase) + + +private inline fun String.mapFirstChar( + transform: (Char) -> Char +): String = if (isNotEmpty()) transform(this[0]) + substring(1) else this + + +/** + * Exclude all non-alphanumeric characters and converts the result into a camelCase string. + */ +internal fun String.toAlphaNumericCamelCase(): String = + map { if (it.isLetterOrDigit()) it else ' ' } + .joinToString("") + .split(" ") + .filter { it.isNotBlank() } + .joinToString("") { it.uppercaseFirstChar() } + .lowercaseFirstChar() diff --git a/dokka-runners/dokkatoo/devOps/release.main.kts b/dokka-runners/dokkatoo/devOps/release.main.kts new file mode 100644 index 00000000..a7555719 --- /dev/null +++ b/dokka-runners/dokkatoo/devOps/release.main.kts @@ -0,0 +1,415 @@ +#!/usr/bin/env kotlin +@file:DependsOn("com.github.ajalt.clikt:clikt-jvm:3.5.2") +@file:DependsOn("me.alllex.parsus:parsus-jvm:0.4.0") +@file:DependsOn("org.jetbrains.kotlinx:kotlinx-coroutines-core-jvm:1.7.3") + +import Release_main.SemVer.Companion.SemVer +import com.github.ajalt.clikt.core.CliktCommand +import com.github.ajalt.clikt.parameters.options.flag +import com.github.ajalt.clikt.parameters.options.option +import java.io.File +import java.util.concurrent.TimeUnit.MINUTES +import kotlin.system.exitProcess +import kotlin.time.Duration.Companion.seconds +import kotlinx.coroutines.delay +import kotlinx.coroutines.runBlocking +import me.alllex.parsus.parser.* +import me.alllex.parsus.token.literalToken +import me.alllex.parsus.token.regexToken + +try { + Release.main(args) + exitProcess(0) +} catch (ex: Exception) { + println("${ex::class.simpleName}: ${ex.message}") + exitProcess(1) +} + +/** + * Release a new version. + * + * Requires: + * * [gh cli](https://cli.github.com/manual/gh) + * * [kotlin](https://kotlinlang.org/docs/command-line.html) + * * [git](https://git-scm.com/) + */ +// based on https://github.com/apollographql/apollo-kotlin/blob/v4.0.0-dev.2/scripts/release.main.kts +object Release : CliktCommand() { + private val skipGitValidation by option( + "--skip-git-validation", + help = "skips git status validation" + ).flag(default = false) + + override fun run() { + echo("Current Dokkatoo version is $dokkatooVersion") + echo("git dir is ${Git.rootDir}") + + val startBranch = Git.currentBranch() + + validateGitStatus(startBranch) + + val releaseVersion = semverPrompt( + text = "version to release?", + default = dokkatooVersion.copy(snapshot = false), + ) { + if (it.snapshot) { + echo("versionToRelease must not be a snapshot version, but was $it") + } + !it.snapshot + } + val nextVersion = semverPrompt( + text = "post-release version?", + default = releaseVersion.incrementMinor(snapshot = true), + ) + updateVersionCreatePR(releaseVersion) + + // switch back to the main branch + Git.switch(startBranch) + Git.pull(startBranch) + + // Tag the release + createAndPushTag(releaseVersion) + + confirm("Publish plugins to Gradle Plugin Portal?", abort = true) + Gradle.publishPlugins() + + // Bump the version to the next snapshot + updateVersionCreatePR(nextVersion) + + // Go back and pull the changes + Git.switch(startBranch) + Git.pull(startBranch) + + echo("Released version $releaseVersion") + } + + private fun validateGitStatus(startBranch: String) { + if (skipGitValidation) { + echo("skipping git status validation") + return + } + check(Git.status().isEmpty()) { + "git repo is not clean. Stash or commit changes before making a release." + } + check(dokkatooVersion.snapshot) { + "Current version must be a SNAPSHOT, but was $dokkatooVersion" + } + check(startBranch == "main") { + "Must be on the main branch to make a release, but current branch is $startBranch" + } + } + + /** + * @param[validate] returns `null` if the provided SemVer is valid, or else an error message + * explaining why it is invalid. + */ + private tailrec fun semverPrompt( + text: String, + default: SemVer, + validate: (candidate: SemVer) -> Boolean = { true }, + ): SemVer { + val response = prompt( + text = text, + default = default.toString(), + requireConfirmation = true, + ) { + SemVer.of(it) + } + + return if (response == null || !validate(response)) { + if (response == null) echo("invalid SemVer") + semverPrompt(text, default, validate) + } else { + response + } + } + + private fun updateVersionCreatePR(version: SemVer) { + // checkout a release branch + val releaseBranch = "release/v$version" + echo("checkout out new branch...") + Git.switch(releaseBranch, create = true) + + // update the version & run tests + dokkatooVersion = version + echo("running Gradle check...") + Gradle.check() + + // commit and push + echo("committing...") + Git.commit("release $version") + echo("pushing...") + Git.push(releaseBranch) + + // create a new PR + echo("creating PR...") + GitHub.createPr(releaseBranch) + + confirm("Merge the PR for branch $releaseBranch?", abort = true) + mergeAndWait(releaseBranch) + echo("$releaseBranch PR merged") + } + + private fun createAndPushTag(version: SemVer) { + // Tag the release + require(dokkatooVersion == version) { + "tried to create a tag, but project version does not match provided version. Expected $version but got $dokkatooVersion" + } + val tagName = "v$version" + Git.tag(tagName) + confirm("Push tag $tagName?", abort = true) + Git.push(tagName) + echo("Tag pushed") + + confirm("Publish plugins to Gradle Plugin Portal?", abort = true) + Gradle.publishPlugins() + } + + private val buildGradleKts: File by lazy { + val rootDir = Git.rootDir + File("$rootDir/build.gradle.kts").apply { + require(exists()) { "could not find build.gradle.kts in $rootDir" } + } + } + + /** Read/write the version set in the root `build.gradle.kts` file */ + private var dokkatooVersion: SemVer + get() { + val rawVersion = Gradle.dokkatooVersion() + return SemVer(rawVersion) + } + set(value) { + val updatedFile = buildGradleKts.useLines { lines -> + lines.joinToString(separator = "\n", postfix = "\n") { line -> + if (line.startsWith("version = ")) { + "version = \"${value}\"" + } else { + line + } + } + } + buildGradleKts.writeText(updatedFile) + } + + private fun mergeAndWait(branchName: String): Unit = runBlocking { + GitHub.autoMergePr(branchName) + echo("Waiting for the PR to be merged...") + while (GitHub.prState(branchName) != "MERGED") { + delay(1.seconds) + echo(".", trailingNewline = false) + } + } +} + +private abstract class CliTool { + + protected fun runCommand( + cmd: String, + dir: File? = Git.rootDir, + logOutput: Boolean = true, + ): String { + val args = parseSpaceSeparatedArgs(cmd) + + val process = ProcessBuilder(args).apply { + redirectOutput(ProcessBuilder.Redirect.PIPE) + redirectInput(ProcessBuilder.Redirect.PIPE) + redirectErrorStream(true) + if (dir != null) directory(dir) + }.start() + + val processOutput = process.inputStream + .bufferedReader() + .lineSequence() + .onEach { if (logOutput) println("\t$it") } + .joinToString("\n") + .trim() + + process.waitFor(10, MINUTES) + + val exitCode = process.exitValue() + + if (exitCode != 0) { + error("command '$cmd' failed:\n${processOutput}") + } + + return processOutput + } + + private data class ProcessResult( + val exitCode: Int, + val output: String, + ) + + companion object { + private fun parseSpaceSeparatedArgs(argsString: String): List { + val parsedArgs = mutableListOf() + var inQuotes = false + var currentCharSequence = StringBuilder() + fun saveArg(wasInQuotes: Boolean) { + if (wasInQuotes || currentCharSequence.isNotBlank()) { + parsedArgs.add(currentCharSequence.toString()) + currentCharSequence = StringBuilder() + } + } + argsString.forEach { char -> + if (char == '"') { + inQuotes = !inQuotes + // Save value which was in quotes. + if (!inQuotes) { + saveArg(true) + } + } else if (char.isWhitespace() && !inQuotes) { + // Space is separator + saveArg(false) + } else { + currentCharSequence.append(char) + } + } + if (inQuotes) { + error("No close-quote was found in $currentCharSequence.") + } + saveArg(false) + return parsedArgs + } + } +} + +/** git commands */ +private object Git : CliTool() { + val rootDir = File(runCommand("git rev-parse --show-toplevel", dir = null)) + + init { + require(rootDir.exists()) { "could not determine root git directory" } + } + + fun switch(branch: String, create: Boolean = false): String { + return runCommand( + buildString { + append("git switch ") + if (create) append("--create ") + append(branch) + } + ) + } + + fun commit(message: String): String = runCommand("git commit -a -m \"$message\"") + fun currentBranch(): String = runCommand("git symbolic-ref --short HEAD") + fun pull(ref: String): String = runCommand("git pull origin $ref") + fun push(ref: String): String = runCommand("git push origin $ref") + fun status(): String { + runCommand("git fetch --all") + return runCommand("git status --porcelain=v2") + } + + fun tag(tag: String): String { + return runCommand("git tag $tag") + } +} + +/** GitHub commands */ +private object GitHub : CliTool() { + + init { + setRepo("adamko-dev/dokkatoo") + } + + fun setRepo(repo: String): String = + runCommand("gh repo set-default $repo") + + fun prState(branchName: String): String = + runCommand("gh pr view $branchName --json state --jq .state", logOutput = false) + + fun createPr(branch: String): String = + runCommand("gh pr create --head $branch --fill") + + fun autoMergePr(branch: String): String = + runCommand("gh pr merge $branch --squash --auto --delete-branch") + + fun waitForPrChecks(branch: String): String = + runCommand("gh pr checks $branch --watch --interval 30") +} + +/** GitHub commands */ +private object Gradle : CliTool() { + + val gradlew: String + + init { + val osName = System.getProperty("os.name").lowercase() + gradlew = if ("win" in osName) "./gradlew.bat" else "./gradlew" + } + + fun stopDaemons(): String = runCommand("$gradlew --stop") + + fun dokkatooVersion(): String { + stopDaemons() + return runCommand("$gradlew :dokkatooVersion --quiet --no-daemon") + } + + fun check(): String { + stopDaemons() + return runCommand("$gradlew check --no-daemon") + } + + fun publishPlugins(): String { + stopDaemons() + return runCommand("$gradlew publishPlugins --no-daemon --no-configuration-cache") + } +} + +private data class SemVer( + val major: Int, + val minor: Int, + val patch: Int, + val snapshot: Boolean, +) { + + fun incrementMinor(snapshot: Boolean): SemVer = + copy(minor = minor + 1, snapshot = snapshot) + + override fun toString(): String = + "$major.$minor.$patch" + if (snapshot) "-SNAPSHOT" else "" + + companion object { + fun SemVer(input: String): SemVer = + SemVerParser.parseEntire(input).getOrElse { error -> + error("provided version to release must be SemVer X.Y.Z, but got error while parsing: $error") + } + + fun of(input: String): SemVer? = + SemVerParser.parseEntire(input).getOrElse { return null } + + fun isValid(input: String): Boolean = + try { + SemVerParser.parseEntireOrThrow(input) + true + } catch (ex: ParseException) { + false + } + } + + private object SemVerParser : Grammar() { + private val dotSeparator by literalToken(".") + private val dashSeparator by literalToken("-") + + /** Non-negative number that is either 0, or does not start with 0 */ + private val number: Parser by regexToken("""0|[1-9]\d*""").map { it.text.toInt() } + + private val snapshot by -dashSeparator * literalToken("SNAPSHOT") + + override val root: Parser by parser { + val major = number() + dotSeparator() + val minor = number() + dotSeparator() + val patch = number() + val snapshot = checkPresent(snapshot) + SemVer( + major = major, + minor = minor, + patch = patch, + snapshot = snapshot, + ) + } + } +} diff --git a/dokka-runners/dokkatoo/examples/.gitignore b/dokka-runners/dokkatoo/examples/.gitignore new file mode 100644 index 00000000..4a1da3f8 --- /dev/null +++ b/dokka-runners/dokkatoo/examples/.gitignore @@ -0,0 +1,10 @@ +.idea +**/gradle/wrapper/** +gradlew.bat +gradlew +gradle.properties + +versioning-multimodule-example/dokka/previousDocVersions + +# these are test projects, so don't commit the lock file +**/kotlin-js-store/yarn.lock diff --git a/dokka-runners/dokkatoo/examples/README.md b/dokka-runners/dokkatoo/examples/README.md new file mode 100644 index 00000000..f39abb5b --- /dev/null +++ b/dokka-runners/dokkatoo/examples/README.md @@ -0,0 +1,18 @@ +# Dokkatoo Examples + +Examples of how to use Dokkatoo. + +The examples are copied from the Dokka project. + +### Set up + +The Dokka examples are synced automatically from the Dokka source code. + +### Tests + +The projects are tested in the +[`:modules:dokkatoo-plugin-integration-tests`](./../modules/dokkatoo-plugin-integration-tests/) +project. + +The Dokka Publications generated by the Dokka examples are compared against the Dokka +Publications generated by the Dokkatoo projects. diff --git a/dokka-runners/dokkatoo/examples/build.gradle.kts b/dokka-runners/dokkatoo/examples/build.gradle.kts new file mode 100644 index 00000000..da366c88 --- /dev/null +++ b/dokka-runners/dokkatoo/examples/build.gradle.kts @@ -0,0 +1,48 @@ +plugins { + buildsrc.conventions.`maven-publish-test` + buildsrc.conventions.`dokkatoo-example-projects` +} + +dokkaTemplateProjects { + register( + source = "examples/gradle/dokka-customFormat-example", + destination = "custom-format-example/dokka" + ) + register( + source = "examples/gradle/dokka-gradle-example", + destination = "gradle-example/dokka" + ) + register( + source = "examples/gradle/dokka-kotlinAsJava-example", + destination = "kotlin-as-java-example/dokka" + ) + register( + source = "examples/gradle/dokka-library-publishing-example", + destination = "library-publishing-example/dokka" + ) + register( + source = "examples/gradle/dokka-multimodule-example", + destination = "multimodule-example/dokka" + ) + register( + source = "examples/gradle/dokka-multiplatform-example", + destination = "multiplatform-example/dokka" + ) + register( + source = "examples/gradle/dokka-versioning-multimodule-example", + destination = "versioning-multimodule-example/dokka" + ) +} + +configurations.exampleProjectsElements.configure { + outgoing { + artifact(projectDir) { + builtBy(tasks.updateDokkatooExamples) + type = "directory" + } + } +} + +dokkaSourceDownload { + dokkaVersion.set(libs.versions.kotlin.dokka) +} diff --git a/dokka-runners/dokkatoo/examples/custom-format-example/dokka/README.md b/dokka-runners/dokkatoo/examples/custom-format-example/dokka/README.md new file mode 100644 index 00000000..a25cd80e --- /dev/null +++ b/dokka-runners/dokkatoo/examples/custom-format-example/dokka/README.md @@ -0,0 +1,17 @@ +## Dokka custom format example + +This example demonstrates how to override `.css` styles and add custom images as assets, allowing +you to change the logo used in the header. + +You can see up-to-date documentation generated for this example on +[GitHub Pages](https://kotlin.github.io/dokka/examples/dokka-customFormat-example/html/index.html). + +![screenshot demonstration of output](demo.png) + +### Running + +Run `dokkaHtml` task to generate documentation with the custom logo in place: + +```bash +./gradlew dokkaHtml +``` diff --git a/dokka-runners/dokkatoo/examples/custom-format-example/dokka/build.gradle.kts b/dokka-runners/dokkatoo/examples/custom-format-example/dokka/build.gradle.kts new file mode 100644 index 00000000..27540ee6 --- /dev/null +++ b/dokka-runners/dokkatoo/examples/custom-format-example/dokka/build.gradle.kts @@ -0,0 +1,35 @@ +import org.jetbrains.dokka.gradle.DokkaTask +import org.jetbrains.dokka.base.DokkaBase +import org.jetbrains.dokka.base.DokkaBaseConfiguration + +plugins { + kotlin("jvm") version "1.9.0" + id("org.jetbrains.dokka") version "1.9.0" +} + +buildscript { + dependencies { + classpath("org.jetbrains.dokka:dokka-base:1.9.0") + } +} + +repositories { + mavenCentral() +} + +tasks.dokkaHtml { + pluginConfiguration { + // Dokka's stylesheets and assets with conflicting names will be overriden. + // In this particular case, logo-styles.css will be overriden and ktor-logo.png will + // be added as an additional image asset + customStyleSheets = listOf(file("logo-styles.css")) + customAssets = listOf(file("ktor-logo.png")) + + // Text used in the footer + footerMessage = "(c) Custom Format Dokka example" + } +} + +dependencies { + testImplementation(kotlin("test-junit")) +} diff --git a/dokka-runners/dokkatoo/examples/custom-format-example/dokka/demo.png b/dokka-runners/dokkatoo/examples/custom-format-example/dokka/demo.png new file mode 100644 index 00000000..8f9b88b0 Binary files /dev/null and b/dokka-runners/dokkatoo/examples/custom-format-example/dokka/demo.png differ diff --git a/dokka-runners/dokkatoo/examples/custom-format-example/dokka/ktor-logo.png b/dokka-runners/dokkatoo/examples/custom-format-example/dokka/ktor-logo.png new file mode 100644 index 00000000..ef943896 Binary files /dev/null and b/dokka-runners/dokkatoo/examples/custom-format-example/dokka/ktor-logo.png differ diff --git a/dokka-runners/dokkatoo/examples/custom-format-example/dokka/logo-styles.css b/dokka-runners/dokkatoo/examples/custom-format-example/dokka/logo-styles.css new file mode 100644 index 00000000..ffe4d503 --- /dev/null +++ b/dokka-runners/dokkatoo/examples/custom-format-example/dokka/logo-styles.css @@ -0,0 +1,20 @@ +/* + * All Margins and sizes are custom for the ktor-logo.png file. + * You may need to override it and find what works best for your case. + */ +:root { + --dokka-logo-image-url: url('../images/ktor-logo.png'); + --dokka-logo-height: 125px; + --dokka-logo-width: 50px; +} + +/* link custom rules styles */ +.library-name--link { + /* ... */ +} + +/* logo custom rules styles */ +.library-name--link::before { + background-position: left; + width: 52px; +} \ No newline at end of file diff --git a/dokka-runners/dokkatoo/examples/custom-format-example/dokka/settings.gradle.kts b/dokka-runners/dokkatoo/examples/custom-format-example/dokka/settings.gradle.kts new file mode 100644 index 00000000..9855e823 --- /dev/null +++ b/dokka-runners/dokkatoo/examples/custom-format-example/dokka/settings.gradle.kts @@ -0,0 +1 @@ +rootProject.name = "dokka-customFormat-example" diff --git a/dokka-runners/dokkatoo/examples/custom-format-example/dokka/src/main/kotlin/demo/HelloWorld.kt b/dokka-runners/dokkatoo/examples/custom-format-example/dokka/src/main/kotlin/demo/HelloWorld.kt new file mode 100644 index 00000000..172e18f7 --- /dev/null +++ b/dokka-runners/dokkatoo/examples/custom-format-example/dokka/src/main/kotlin/demo/HelloWorld.kt @@ -0,0 +1,20 @@ +package demo + +/** + * This class supports greeting people by name. + * + * @property name The name of the person to be greeted. + */ +class Greeter(val name: String) { + + /** + * Prints the greeting to the standard output. + */ + fun greet() { + println("Hello $name!") + } +} + +fun main(args: Array) { + Greeter(args[0]).greet() +} diff --git a/dokka-runners/dokkatoo/examples/custom-format-example/dokkatoo/build.gradle.kts b/dokka-runners/dokkatoo/examples/custom-format-example/dokkatoo/build.gradle.kts new file mode 100644 index 00000000..7832a8f9 --- /dev/null +++ b/dokka-runners/dokkatoo/examples/custom-format-example/dokkatoo/build.gradle.kts @@ -0,0 +1,18 @@ +plugins { + kotlin("jvm") version "1.9.0" + id("org.jetbrains.dokka.dokkatoo") version "2.1.0-SNAPSHOT" +} + +dokkatoo { + moduleName.set("customFormat-example") + pluginsConfiguration.html { + // Dokka's stylesheets and assets with conflicting names will be overridden. + // In this particular case, logo-styles.css will be overridden + // and ktor-logo.png will be added as an additional image asset + customStyleSheets.from("logo-styles.css") + customAssets.from("ktor-logo.png") + + // Text used in the footer + footerMessage.set("(c) Custom Format Dokka example") + } +} diff --git a/dokka-runners/dokkatoo/examples/custom-format-example/dokkatoo/ktor-logo.png b/dokka-runners/dokkatoo/examples/custom-format-example/dokkatoo/ktor-logo.png new file mode 100644 index 00000000..ef943896 Binary files /dev/null and b/dokka-runners/dokkatoo/examples/custom-format-example/dokkatoo/ktor-logo.png differ diff --git a/dokka-runners/dokkatoo/examples/custom-format-example/dokkatoo/logo-styles.css b/dokka-runners/dokkatoo/examples/custom-format-example/dokkatoo/logo-styles.css new file mode 100644 index 00000000..ffe4d503 --- /dev/null +++ b/dokka-runners/dokkatoo/examples/custom-format-example/dokkatoo/logo-styles.css @@ -0,0 +1,20 @@ +/* + * All Margins and sizes are custom for the ktor-logo.png file. + * You may need to override it and find what works best for your case. + */ +:root { + --dokka-logo-image-url: url('../images/ktor-logo.png'); + --dokka-logo-height: 125px; + --dokka-logo-width: 50px; +} + +/* link custom rules styles */ +.library-name--link { + /* ... */ +} + +/* logo custom rules styles */ +.library-name--link::before { + background-position: left; + width: 52px; +} \ No newline at end of file diff --git a/dokka-runners/dokkatoo/examples/custom-format-example/dokkatoo/settings.gradle.kts b/dokka-runners/dokkatoo/examples/custom-format-example/dokkatoo/settings.gradle.kts new file mode 100644 index 00000000..31ad8c91 --- /dev/null +++ b/dokka-runners/dokkatoo/examples/custom-format-example/dokkatoo/settings.gradle.kts @@ -0,0 +1,17 @@ +rootProject.name = "custom-format-example" + +pluginManagement { + repositories { + mavenCentral() + gradlePluginPortal() + maven(providers.gradleProperty("testMavenRepo")) + } +} + +@Suppress("UnstableApiUsage") +dependencyResolutionManagement { + repositories { + mavenCentral() + maven(providers.gradleProperty("testMavenRepo")) + } +} diff --git a/dokka-runners/dokkatoo/examples/custom-format-example/dokkatoo/src/main/kotlin/demo/HelloWorld.kt b/dokka-runners/dokkatoo/examples/custom-format-example/dokkatoo/src/main/kotlin/demo/HelloWorld.kt new file mode 100644 index 00000000..172e18f7 --- /dev/null +++ b/dokka-runners/dokkatoo/examples/custom-format-example/dokkatoo/src/main/kotlin/demo/HelloWorld.kt @@ -0,0 +1,20 @@ +package demo + +/** + * This class supports greeting people by name. + * + * @property name The name of the person to be greeted. + */ +class Greeter(val name: String) { + + /** + * Prints the greeting to the standard output. + */ + fun greet() { + println("Hello $name!") + } +} + +fun main(args: Array) { + Greeter(args[0]).greet() +} diff --git a/dokka-runners/dokkatoo/examples/gradle-example/dokka/Module.md b/dokka-runners/dokkatoo/examples/gradle-example/dokka/Module.md new file mode 100644 index 00000000..0d051cb1 --- /dev/null +++ b/dokka-runners/dokkatoo/examples/gradle-example/dokka/Module.md @@ -0,0 +1,7 @@ +# Module Dokka Gradle Example + +This is an example of how you can write module documentation with Dokka. + +# Package demo + +This package contains a few examples of Dokka usage. diff --git a/dokka-runners/dokkatoo/examples/gradle-example/dokka/README.md b/dokka-runners/dokkatoo/examples/gradle-example/dokka/README.md new file mode 100644 index 00000000..3401e8e9 --- /dev/null +++ b/dokka-runners/dokkatoo/examples/gradle-example/dokka/README.md @@ -0,0 +1,22 @@ +# Dokka Gradle example + +This example demonstrates how to apply Dokka in a simple single-project Gradle build, as well as how to configure it. + +Configuration changes: + +* Custom project name used in the header, `Dokka Gradle Example`. +* Description for the project and the packages taken from [Module.md](Module.md). +* Documentation contains source links that lead to declarations in this GitHub repository. + +You can see up-to-date documentation generated for this example on +[GitHub Pages](https://kotlin.github.io/dokka/examples/dokka-gradle-example/html/index.html). + +![screenshot demonstration of output](demo.png) + +### Running + +Run `dokkaHtml` task to generate documentation for this example: + +```bash +./gradlew dokkaHtml +``` diff --git a/dokka-runners/dokkatoo/examples/gradle-example/dokka/build.gradle.kts b/dokka-runners/dokkatoo/examples/gradle-example/dokka/build.gradle.kts new file mode 100644 index 00000000..5f54ad9d --- /dev/null +++ b/dokka-runners/dokkatoo/examples/gradle-example/dokka/build.gradle.kts @@ -0,0 +1,37 @@ +import org.jetbrains.dokka.gradle.DokkaTask +import java.net.URL + +plugins { + kotlin("jvm") version "1.9.0" + id("org.jetbrains.dokka") version "1.9.0" +} + +repositories { + mavenCentral() +} + +dependencies { + testImplementation(kotlin("test-junit")) +} + +tasks.withType().configureEach { + dokkaSourceSets { + named("main") { + // used as project name in the header + moduleName.set("Dokka Gradle Example") + + // contains descriptions for the module and the packages + includes.from("Module.md") + + // adds source links that lead to this repository, allowing readers + // to easily find source code for inspected declarations + sourceLink { + localDirectory.set(file("src/main/kotlin")) + remoteUrl.set(URL("https://github.com/Kotlin/dokka/tree/master/" + + "examples/gradle/dokka-gradle-example/src/main/kotlin" + )) + remoteLineSuffix.set("#L") + } + } + } +} diff --git a/dokka-runners/dokkatoo/examples/gradle-example/dokka/demo.png b/dokka-runners/dokkatoo/examples/gradle-example/dokka/demo.png new file mode 100644 index 00000000..4462f3b5 Binary files /dev/null and b/dokka-runners/dokkatoo/examples/gradle-example/dokka/demo.png differ diff --git a/dokka-runners/dokkatoo/examples/gradle-example/dokka/settings.gradle.kts b/dokka-runners/dokkatoo/examples/gradle-example/dokka/settings.gradle.kts new file mode 100644 index 00000000..5b8c3c92 --- /dev/null +++ b/dokka-runners/dokkatoo/examples/gradle-example/dokka/settings.gradle.kts @@ -0,0 +1 @@ +rootProject.name = "dokka-gradle-example" diff --git a/dokka-runners/dokkatoo/examples/gradle-example/dokka/src/main/kotlin/demo/HelloWorld.kt b/dokka-runners/dokkatoo/examples/gradle-example/dokka/src/main/kotlin/demo/HelloWorld.kt new file mode 100644 index 00000000..172e18f7 --- /dev/null +++ b/dokka-runners/dokkatoo/examples/gradle-example/dokka/src/main/kotlin/demo/HelloWorld.kt @@ -0,0 +1,20 @@ +package demo + +/** + * This class supports greeting people by name. + * + * @property name The name of the person to be greeted. + */ +class Greeter(val name: String) { + + /** + * Prints the greeting to the standard output. + */ + fun greet() { + println("Hello $name!") + } +} + +fun main(args: Array) { + Greeter(args[0]).greet() +} diff --git a/dokka-runners/dokkatoo/examples/gradle-example/dokkatoo/Module.md b/dokka-runners/dokkatoo/examples/gradle-example/dokkatoo/Module.md new file mode 100644 index 00000000..0d051cb1 --- /dev/null +++ b/dokka-runners/dokkatoo/examples/gradle-example/dokkatoo/Module.md @@ -0,0 +1,7 @@ +# Module Dokka Gradle Example + +This is an example of how you can write module documentation with Dokka. + +# Package demo + +This package contains a few examples of Dokka usage. diff --git a/dokka-runners/dokkatoo/examples/gradle-example/dokkatoo/build.gradle.kts b/dokka-runners/dokkatoo/examples/gradle-example/dokkatoo/build.gradle.kts new file mode 100644 index 00000000..2cfc30bd --- /dev/null +++ b/dokka-runners/dokkatoo/examples/gradle-example/dokkatoo/build.gradle.kts @@ -0,0 +1,23 @@ +plugins { + kotlin("jvm") version "1.9.0" + id("org.jetbrains.dokka.dokkatoo") version "2.1.0-SNAPSHOT" +} + +dokkatoo { + // used as project name in the header + moduleName.set("Dokka Gradle Example") + + dokkatooSourceSets.main { + + // contains descriptions for the module and the packages + includes.from("Module.md") + + // adds source links that lead to this repository, allowing readers + // to easily find source code for inspected declarations + sourceLink { + localDirectory.set(file("src/main/kotlin")) + remoteUrl("https://github.com/Kotlin/dokka/tree/master/examples/gradle/dokka-gradle-example/src/main/kotlin") + remoteLineSuffix.set("#L") + } + } +} diff --git a/dokka-runners/dokkatoo/examples/gradle-example/dokkatoo/settings.gradle.kts b/dokka-runners/dokkatoo/examples/gradle-example/dokkatoo/settings.gradle.kts new file mode 100644 index 00000000..02c75bfb --- /dev/null +++ b/dokka-runners/dokkatoo/examples/gradle-example/dokkatoo/settings.gradle.kts @@ -0,0 +1,17 @@ +rootProject.name = "gradle-example" + +pluginManagement { + repositories { + gradlePluginPortal() + mavenCentral() + maven(providers.gradleProperty("testMavenRepo")) + } +} + +@Suppress("UnstableApiUsage") +dependencyResolutionManagement { + repositories { + mavenCentral() + maven(providers.gradleProperty("testMavenRepo")) + } +} diff --git a/dokka-runners/dokkatoo/examples/gradle-example/dokkatoo/src/main/kotlin/demo/HelloWorld.kt b/dokka-runners/dokkatoo/examples/gradle-example/dokkatoo/src/main/kotlin/demo/HelloWorld.kt new file mode 100644 index 00000000..172e18f7 --- /dev/null +++ b/dokka-runners/dokkatoo/examples/gradle-example/dokkatoo/src/main/kotlin/demo/HelloWorld.kt @@ -0,0 +1,20 @@ +package demo + +/** + * This class supports greeting people by name. + * + * @property name The name of the person to be greeted. + */ +class Greeter(val name: String) { + + /** + * Prints the greeting to the standard output. + */ + fun greet() { + println("Hello $name!") + } +} + +fun main(args: Array) { + Greeter(args[0]).greet() +} diff --git a/dokka-runners/dokkatoo/examples/kotlin-as-java-example/dokka/README.md b/dokka-runners/dokkatoo/examples/kotlin-as-java-example/dokka/README.md new file mode 100644 index 00000000..647b0e6d --- /dev/null +++ b/dokka-runners/dokkatoo/examples/kotlin-as-java-example/dokka/README.md @@ -0,0 +1,19 @@ +# Dokka Kotlin-as-Java plugin example + +This example demonstrates how you can apply a Dokka plugin in a simple Gradle project. + +In particular, it applies [Kotlin as Java](../../../plugins/kotlin-as-java) Dokka plugin that renders all +Kotlin signatures as Java signatures. + +You can see up-to-date documentation generated for this example on +[GitHub Pages](https://kotlin.github.io/dokka/examples/dokka-kotlinAsJava-example/html/index.html). + +![screenshot demonstration of output](demo.png) + +### Running + +Run `dokkaHtml` task to generate documentation for this example: + +```bash +./gradlew dokkaHtml +``` diff --git a/dokka-runners/dokkatoo/examples/kotlin-as-java-example/dokka/build.gradle.kts b/dokka-runners/dokkatoo/examples/kotlin-as-java-example/dokka/build.gradle.kts new file mode 100644 index 00000000..b339cec3 --- /dev/null +++ b/dokka-runners/dokkatoo/examples/kotlin-as-java-example/dokka/build.gradle.kts @@ -0,0 +1,21 @@ +plugins { + kotlin("jvm") version "1.9.0" + id("org.jetbrains.dokka") version "1.9.0" +} + +repositories { + mavenCentral() +} + +dependencies { + testImplementation(kotlin("test-junit")) + + // Will apply the plugin to all Dokka tasks + dokkaPlugin("org.jetbrains.dokka:kotlin-as-java-plugin:1.9.0") + + // Will apply the plugin only to the `:dokkaHtml` task + //dokkaHtmlPlugin("org.jetbrains.dokka:kotlin-as-java-plugin:1.9.0") + + // Will apply the plugin only to the `:dokkaGfm` task + //dokkaGfmPlugin("org.jetbrains.dokka:kotlin-as-java-plugin:1.9.0") +} diff --git a/dokka-runners/dokkatoo/examples/kotlin-as-java-example/dokka/demo.png b/dokka-runners/dokkatoo/examples/kotlin-as-java-example/dokka/demo.png new file mode 100644 index 00000000..92f1170f Binary files /dev/null and b/dokka-runners/dokkatoo/examples/kotlin-as-java-example/dokka/demo.png differ diff --git a/dokka-runners/dokkatoo/examples/kotlin-as-java-example/dokka/settings.gradle.kts b/dokka-runners/dokkatoo/examples/kotlin-as-java-example/dokka/settings.gradle.kts new file mode 100644 index 00000000..0a0b8c0e --- /dev/null +++ b/dokka-runners/dokkatoo/examples/kotlin-as-java-example/dokka/settings.gradle.kts @@ -0,0 +1 @@ +rootProject.name = "dokka-kotlinAsJava-example" diff --git a/dokka-runners/dokkatoo/examples/kotlin-as-java-example/dokka/src/main/kotlin/demo/HelloWorld.kt b/dokka-runners/dokkatoo/examples/kotlin-as-java-example/dokka/src/main/kotlin/demo/HelloWorld.kt new file mode 100644 index 00000000..172e18f7 --- /dev/null +++ b/dokka-runners/dokkatoo/examples/kotlin-as-java-example/dokka/src/main/kotlin/demo/HelloWorld.kt @@ -0,0 +1,20 @@ +package demo + +/** + * This class supports greeting people by name. + * + * @property name The name of the person to be greeted. + */ +class Greeter(val name: String) { + + /** + * Prints the greeting to the standard output. + */ + fun greet() { + println("Hello $name!") + } +} + +fun main(args: Array) { + Greeter(args[0]).greet() +} diff --git a/dokka-runners/dokkatoo/examples/kotlin-as-java-example/dokkatoo/settings.gradle.kts b/dokka-runners/dokkatoo/examples/kotlin-as-java-example/dokkatoo/settings.gradle.kts new file mode 100644 index 00000000..019ac938 --- /dev/null +++ b/dokka-runners/dokkatoo/examples/kotlin-as-java-example/dokkatoo/settings.gradle.kts @@ -0,0 +1,17 @@ +rootProject.name = "kotlin-as-java-example" + +pluginManagement { + repositories { + gradlePluginPortal() + mavenCentral() + maven(providers.gradleProperty("testMavenRepo")) + } +} + +@Suppress("UnstableApiUsage") +dependencyResolutionManagement { + repositories { + mavenCentral() + maven(providers.gradleProperty("testMavenRepo")) + } +} diff --git a/dokka-runners/dokkatoo/examples/library-publishing-example/dokka/README.md b/dokka-runners/dokkatoo/examples/library-publishing-example/dokka/README.md new file mode 100644 index 00000000..60d967b8 --- /dev/null +++ b/dokka-runners/dokkatoo/examples/library-publishing-example/dokka/README.md @@ -0,0 +1,41 @@ +# Dokka Library publishing example + +This example demonstrates how you can integrate Dokka into the publishing process of your library, adding +documentation generated by Dokka as artifacts. + +This is useful because some repositories, like Maven Central, require documentation (`javadoc.jar`) to be published +alongside library artifacts. + +You can also use services like [javadoc.io](https://javadoc.io/) to host of your library's API documentation for free +and without any additional setup - it will take documentation pages straight from the published artifact. It works with +both HTML and Javadoc formats as demonstrated by +[com.trib3's Javadocs](https://javadoc.io/doc/com.trib3/server/latest/index.html). + +## Running + +Run `dokkaHtml` task to generate documentation for this example: + +```bash +./gradlew dokkaHtml +``` + +### Javadoc jar + +Run `dokkaJavadocJar` task to create a jar file that contains documentation generated in Dokka's Javadoc format. + +```Bash +./gradlew dokkaJavadocJar +``` + +After that, you can find the jar under `build/libs/dokka-library-publishing-example-javadoc.jar` + +### HTML jar + + +Run `dokkaHtmlJar` task to create a jar file that contains documentation generated in Dokka's HTML format. + +```Bash +./gradlew dokkaHtmlJar +``` + +After that, you can find the jar under `build/libs/dokka-library-publishing-example-html.jar` diff --git a/dokka-runners/dokkatoo/examples/library-publishing-example/dokka/build.gradle.kts b/dokka-runners/dokkatoo/examples/library-publishing-example/dokka/build.gradle.kts new file mode 100644 index 00000000..731de85b --- /dev/null +++ b/dokka-runners/dokkatoo/examples/library-publishing-example/dokka/build.gradle.kts @@ -0,0 +1,39 @@ +plugins { + kotlin("jvm") version "1.9.0" + id("org.jetbrains.dokka") version "1.9.0" + `java-library` + `maven-publish` +} + +repositories { + mavenCentral() +} + +dependencies { + testImplementation(kotlin("test-junit")) +} + +val dokkaJavadocJar by tasks.register("dokkaJavadocJar") { + dependsOn(tasks.dokkaJavadoc) + from(tasks.dokkaJavadoc.flatMap { it.outputDirectory }) + archiveClassifier.set("javadoc") +} + +val dokkaHtmlJar by tasks.register("dokkaHtmlJar") { + dependsOn(tasks.dokkaHtml) + from(tasks.dokkaHtml.flatMap { it.outputDirectory }) + archiveClassifier.set("html-doc") +} + +publishing { + publications { + register("library") { + from(components["java"]) + version = "1.0.0" + groupId = "demo" + artifactId = "dokka-library-publishing-example" + artifact(dokkaJavadocJar) + artifact(dokkaHtmlJar) + } + } +} diff --git a/dokka-runners/dokkatoo/examples/library-publishing-example/dokka/settings.gradle.kts b/dokka-runners/dokkatoo/examples/library-publishing-example/dokka/settings.gradle.kts new file mode 100644 index 00000000..e0847ac9 --- /dev/null +++ b/dokka-runners/dokkatoo/examples/library-publishing-example/dokka/settings.gradle.kts @@ -0,0 +1 @@ +rootProject.name = "dokka-library-publishing-example" diff --git a/dokka-runners/dokkatoo/examples/library-publishing-example/dokka/src/main/kotlin/demo/HelloWorld.kt b/dokka-runners/dokkatoo/examples/library-publishing-example/dokka/src/main/kotlin/demo/HelloWorld.kt new file mode 100644 index 00000000..172e18f7 --- /dev/null +++ b/dokka-runners/dokkatoo/examples/library-publishing-example/dokka/src/main/kotlin/demo/HelloWorld.kt @@ -0,0 +1,20 @@ +package demo + +/** + * This class supports greeting people by name. + * + * @property name The name of the person to be greeted. + */ +class Greeter(val name: String) { + + /** + * Prints the greeting to the standard output. + */ + fun greet() { + println("Hello $name!") + } +} + +fun main(args: Array) { + Greeter(args[0]).greet() +} diff --git a/dokka-runners/dokkatoo/examples/library-publishing-example/dokkatoo/settings.gradle.kts b/dokka-runners/dokkatoo/examples/library-publishing-example/dokkatoo/settings.gradle.kts new file mode 100644 index 00000000..198cfbdf --- /dev/null +++ b/dokka-runners/dokkatoo/examples/library-publishing-example/dokkatoo/settings.gradle.kts @@ -0,0 +1,17 @@ +rootProject.name = "library-publishing-example" + +pluginManagement { + repositories { + gradlePluginPortal() + mavenCentral() + maven(providers.gradleProperty("testMavenRepo")) + } +} + +@Suppress("UnstableApiUsage") +dependencyResolutionManagement { + repositories { + mavenCentral() + maven(providers.gradleProperty("testMavenRepo")) + } +} diff --git a/dokka-runners/dokkatoo/examples/multimodule-example/dokka/README.md b/dokka-runners/dokkatoo/examples/multimodule-example/dokka/README.md new file mode 100644 index 00000000..c8b224ec --- /dev/null +++ b/dokka-runners/dokkatoo/examples/multimodule-example/dokka/README.md @@ -0,0 +1,25 @@ +# Dokka MultiModule example + +This example demonstrates how to apply and configure Dokka in a +[multi-project build](https://docs.gradle.org/current/userguide/multi_project_builds.html). + +You can also learn how to set Dokka's version in [gradle.properties](gradle.properties) using `pluginManagement` +configuration block in [settings.gradle.kts](settings.gradle.kts). + +____ + +You can see up-to-date documentation generated for this example on +[GitHub Pages](https://kotlin.github.io/dokka/examples/dokka-multimodule-example/htmlMultiModule/index.html). + +![screenshot demonstration of output](demo.png) + +### Running + +Run `dokkaHtmlMultiModule` task to generate documentation for this example: + +```bash +./gradlew dokkaHtmlMultiModule +``` + +It will generate complete documentation for the root project and its subprojects, with a common +Table of Contents. diff --git a/dokka-runners/dokkatoo/examples/multimodule-example/dokka/build.gradle.kts b/dokka-runners/dokkatoo/examples/multimodule-example/dokka/build.gradle.kts new file mode 100644 index 00000000..6b416abc --- /dev/null +++ b/dokka-runners/dokkatoo/examples/multimodule-example/dokka/build.gradle.kts @@ -0,0 +1,5 @@ +subprojects { + repositories { + mavenCentral() + } +} diff --git a/dokka-runners/dokkatoo/examples/multimodule-example/dokka/demo.png b/dokka-runners/dokkatoo/examples/multimodule-example/dokka/demo.png new file mode 100644 index 00000000..d25576b8 Binary files /dev/null and b/dokka-runners/dokkatoo/examples/multimodule-example/dokka/demo.png differ diff --git a/dokka-runners/dokkatoo/examples/multimodule-example/dokka/parentProject/build.gradle.kts b/dokka-runners/dokkatoo/examples/multimodule-example/dokka/parentProject/build.gradle.kts new file mode 100644 index 00000000..3563ecca --- /dev/null +++ b/dokka-runners/dokkatoo/examples/multimodule-example/dokka/parentProject/build.gradle.kts @@ -0,0 +1,38 @@ +import org.jetbrains.dokka.DokkaConfiguration.Visibility +import org.jetbrains.dokka.gradle.DokkaTaskPartial +import java.net.URL + +plugins { + kotlin("jvm") + id("org.jetbrains.dokka") +} + +// You can apply and configure Dokka in each subproject +// individially or configure all subprojects at once +subprojects { + apply(plugin = "org.jetbrains.dokka") + + tasks.withType().configureEach { + dokkaSourceSets.configureEach { + documentedVisibilities.set(setOf( + Visibility.PUBLIC, + Visibility.PROTECTED + )) + + // Read docs for more details: https://kotlinlang.org/docs/dokka-gradle.html#source-link-configuration + sourceLink { + val exampleDir = "https://github.com/Kotlin/dokka/tree/master/examples/gradle/dokka-multimodule-example" + + localDirectory.set(rootProject.projectDir) + remoteUrl.set(URL("$exampleDir")) + remoteLineSuffix.set("#L") + } + } + } +} + +// Configures only the parent MultiModule task, +// this will not affect subprojects +tasks.dokkaHtmlMultiModule { + moduleName.set("Dokka MultiModule Example") +} diff --git a/dokka-runners/dokkatoo/examples/multimodule-example/dokka/parentProject/childProjectA/ModuleA.md b/dokka-runners/dokkatoo/examples/multimodule-example/dokka/parentProject/childProjectA/ModuleA.md new file mode 100644 index 00000000..12712d97 --- /dev/null +++ b/dokka-runners/dokkatoo/examples/multimodule-example/dokka/parentProject/childProjectA/ModuleA.md @@ -0,0 +1,5 @@ +# Module childProjectA +This is the child module A + +# Package demo +This package contains a few examples of Dokka usage. diff --git a/dokka-runners/dokkatoo/examples/multimodule-example/dokka/parentProject/childProjectA/build.gradle.kts b/dokka-runners/dokkatoo/examples/multimodule-example/dokka/parentProject/childProjectA/build.gradle.kts new file mode 100644 index 00000000..7b3b1e23 --- /dev/null +++ b/dokka-runners/dokkatoo/examples/multimodule-example/dokka/parentProject/childProjectA/build.gradle.kts @@ -0,0 +1,16 @@ +import org.jetbrains.dokka.gradle.DokkaTaskPartial + +plugins { + kotlin("jvm") + id("org.jetbrains.dokka") +} + +// configuration specific to this subproject. +// notice the use of Partial task +tasks.withType().configureEach { + dokkaSourceSets { + configureEach { + includes.from("ModuleA.md") + } + } +} diff --git a/dokka-runners/dokkatoo/examples/multimodule-example/dokka/parentProject/childProjectA/src/main/kotlin/demo/ChildProjectAClass.kt b/dokka-runners/dokkatoo/examples/multimodule-example/dokka/parentProject/childProjectA/src/main/kotlin/demo/ChildProjectAClass.kt new file mode 100644 index 00000000..533b305c --- /dev/null +++ b/dokka-runners/dokkatoo/examples/multimodule-example/dokka/parentProject/childProjectA/src/main/kotlin/demo/ChildProjectAClass.kt @@ -0,0 +1,8 @@ +@file:Suppress("unused") + +package demo + +/** + * Class defined in child project a + */ +class ChildProjectAClass diff --git a/dokka-runners/dokkatoo/examples/multimodule-example/dokka/parentProject/childProjectB/ModuleB.md b/dokka-runners/dokkatoo/examples/multimodule-example/dokka/parentProject/childProjectB/ModuleB.md new file mode 100644 index 00000000..18a92a33 --- /dev/null +++ b/dokka-runners/dokkatoo/examples/multimodule-example/dokka/parentProject/childProjectB/ModuleB.md @@ -0,0 +1,5 @@ +# Module childProjectB +This is the child module B + +# Package demo +This package contains a few examples of Dokka usage. diff --git a/dokka-runners/dokkatoo/examples/multimodule-example/dokka/parentProject/childProjectB/build.gradle.kts b/dokka-runners/dokkatoo/examples/multimodule-example/dokka/parentProject/childProjectB/build.gradle.kts new file mode 100644 index 00000000..e8b40d4a --- /dev/null +++ b/dokka-runners/dokkatoo/examples/multimodule-example/dokka/parentProject/childProjectB/build.gradle.kts @@ -0,0 +1,16 @@ +import org.jetbrains.dokka.gradle.DokkaTaskPartial + +plugins { + kotlin("jvm") + id("org.jetbrains.dokka") +} + +// configuration specific to this subproject. +// notice the use of Partial task +tasks.withType().configureEach { + dokkaSourceSets { + configureEach { + includes.from("ModuleB.md") + } + } +} diff --git a/dokka-runners/dokkatoo/examples/multimodule-example/dokka/parentProject/childProjectB/src/main/kotlin/demo/ChildProjectBClass.kt b/dokka-runners/dokkatoo/examples/multimodule-example/dokka/parentProject/childProjectB/src/main/kotlin/demo/ChildProjectBClass.kt new file mode 100644 index 00000000..6bfd22eb --- /dev/null +++ b/dokka-runners/dokkatoo/examples/multimodule-example/dokka/parentProject/childProjectB/src/main/kotlin/demo/ChildProjectBClass.kt @@ -0,0 +1,8 @@ +@file:Suppress("unused") + +package demo + +/** + * Class defined in child module b + */ +class ChildProjectBClass diff --git a/dokka-runners/dokkatoo/examples/multimodule-example/dokka/settings.gradle.kts b/dokka-runners/dokkatoo/examples/multimodule-example/dokka/settings.gradle.kts new file mode 100644 index 00000000..9844b3cc --- /dev/null +++ b/dokka-runners/dokkatoo/examples/multimodule-example/dokka/settings.gradle.kts @@ -0,0 +1,15 @@ +pluginManagement { + val kotlinVersion: String by settings + val dokkaVersion: String by settings + + plugins { + kotlin("jvm") version kotlinVersion + id("org.jetbrains.dokka") version dokkaVersion + } +} + +include(":parentProject") +include(":parentProject:childProjectA") +include(":parentProject:childProjectB") + +rootProject.name = "dokka-multimodule-example" diff --git a/dokka-runners/dokkatoo/examples/multimodule-example/dokkatoo/buildSrc/build.gradle.kts b/dokka-runners/dokkatoo/examples/multimodule-example/dokkatoo/buildSrc/build.gradle.kts new file mode 100644 index 00000000..4ee5b079 --- /dev/null +++ b/dokka-runners/dokkatoo/examples/multimodule-example/dokkatoo/buildSrc/build.gradle.kts @@ -0,0 +1,8 @@ +plugins { + `kotlin-dsl` +} + +dependencies { + implementation("org.jetbrains.kotlin:kotlin-gradle-plugin:1.9.0") + implementation("org.jetbrains.dokka.dokkatoo:dokkatoo-plugin:2.1.0-SNAPSHOT") +} diff --git a/dokka-runners/dokkatoo/examples/multimodule-example/dokkatoo/buildSrc/settings.gradle.kts b/dokka-runners/dokkatoo/examples/multimodule-example/dokkatoo/buildSrc/settings.gradle.kts new file mode 100644 index 00000000..b7510ccf --- /dev/null +++ b/dokka-runners/dokkatoo/examples/multimodule-example/dokkatoo/buildSrc/settings.gradle.kts @@ -0,0 +1,21 @@ +rootProject.name = "buildSrc" + +pluginManagement { + repositories { + mavenCentral() + gradlePluginPortal() + maven(providers.gradleProperty("testMavenRepo")) + } +} + +@Suppress("UnstableApiUsage") +dependencyResolutionManagement { + + repositoriesMode.set(RepositoriesMode.PREFER_SETTINGS) + + repositories { + mavenCentral() + gradlePluginPortal() + maven(providers.gradleProperty("testMavenRepo")) + } +} diff --git a/dokka-runners/dokkatoo/examples/multimodule-example/dokkatoo/buildSrc/src/main/kotlin/dokka-convention.gradle.kts b/dokka-runners/dokkatoo/examples/multimodule-example/dokkatoo/buildSrc/src/main/kotlin/dokka-convention.gradle.kts new file mode 100644 index 00000000..04970e8a --- /dev/null +++ b/dokka-runners/dokkatoo/examples/multimodule-example/dokkatoo/buildSrc/src/main/kotlin/dokka-convention.gradle.kts @@ -0,0 +1,17 @@ +/** + * Common conventions for generating documentation with Dokkatoo. + */ + +plugins { + id("org.jetbrains.dokka.dokkatoo") +} + +dokkatoo { + dokkatooSourceSets.configureEach { + sourceLink { + // Read docs for more details: https://kotlinlang.org/docs/dokka-gradle.html#source-link-configuration + remoteUrl("https://github.com/Kotlin/dokka/tree/master/examples/gradle/dokka-multimodule-example") + localDirectory.set(rootDir) + } + } +} diff --git a/dokka-runners/dokkatoo/examples/multimodule-example/dokkatoo/parentProject/build.gradle.kts b/dokka-runners/dokkatoo/examples/multimodule-example/dokkatoo/parentProject/build.gradle.kts new file mode 100644 index 00000000..2a698a7b --- /dev/null +++ b/dokka-runners/dokkatoo/examples/multimodule-example/dokkatoo/parentProject/build.gradle.kts @@ -0,0 +1,23 @@ +plugins { + kotlin("jvm") apply false + `dokka-convention` +} + +dependencies { + dokkatoo(project(":parentProject:childProjectA")) + dokkatoo(project(":parentProject:childProjectB")) + dokkatooPluginHtml( + dokkatoo.versions.jetbrainsDokka.map { dokkaVersion -> + "org.jetbrains.dokka:all-modules-page-plugin:$dokkaVersion" + } + ) + dokkatooPluginHtml( + dokkatoo.versions.jetbrainsDokka.map { dokkaVersion -> + "org.jetbrains.dokka:templating-plugin:$dokkaVersion" + } + ) +} + +dokkatoo { + moduleName.set("Dokka MultiModule Example") +} diff --git a/dokka-runners/dokkatoo/examples/multimodule-example/dokkatoo/parentProject/childProjectA/ModuleA.md b/dokka-runners/dokkatoo/examples/multimodule-example/dokkatoo/parentProject/childProjectA/ModuleA.md new file mode 100644 index 00000000..12712d97 --- /dev/null +++ b/dokka-runners/dokkatoo/examples/multimodule-example/dokkatoo/parentProject/childProjectA/ModuleA.md @@ -0,0 +1,5 @@ +# Module childProjectA +This is the child module A + +# Package demo +This package contains a few examples of Dokka usage. diff --git a/dokka-runners/dokkatoo/examples/multimodule-example/dokkatoo/parentProject/childProjectA/build.gradle.kts b/dokka-runners/dokkatoo/examples/multimodule-example/dokkatoo/parentProject/childProjectA/build.gradle.kts new file mode 100644 index 00000000..51c17118 --- /dev/null +++ b/dokka-runners/dokkatoo/examples/multimodule-example/dokkatoo/parentProject/childProjectA/build.gradle.kts @@ -0,0 +1,21 @@ +plugins { + kotlin("jvm") + `dokka-convention` +} + +dokkatoo { + dokkatooSourceSets.configureEach { + includes.from("ModuleA.md") + } +} + +//region DON'T COPY - this is only needed for internal Dokkatoo integration tests +dokkatoo { + modulePath.set("childProjectA") // match the original dokka default +} +tasks.withType().configureEach { + generator.dokkaSourceSets.configureEach { + sourceSetScope.set(":parentProject:childProjectA:dokkaHtmlPartial") + } +} +//endregion diff --git a/dokka-runners/dokkatoo/examples/multimodule-example/dokkatoo/parentProject/childProjectA/src/main/kotlin/demo/ChildProjectAClass.kt b/dokka-runners/dokkatoo/examples/multimodule-example/dokkatoo/parentProject/childProjectA/src/main/kotlin/demo/ChildProjectAClass.kt new file mode 100644 index 00000000..533b305c --- /dev/null +++ b/dokka-runners/dokkatoo/examples/multimodule-example/dokkatoo/parentProject/childProjectA/src/main/kotlin/demo/ChildProjectAClass.kt @@ -0,0 +1,8 @@ +@file:Suppress("unused") + +package demo + +/** + * Class defined in child project a + */ +class ChildProjectAClass diff --git a/dokka-runners/dokkatoo/examples/multimodule-example/dokkatoo/parentProject/childProjectB/ModuleB.md b/dokka-runners/dokkatoo/examples/multimodule-example/dokkatoo/parentProject/childProjectB/ModuleB.md new file mode 100644 index 00000000..18a92a33 --- /dev/null +++ b/dokka-runners/dokkatoo/examples/multimodule-example/dokkatoo/parentProject/childProjectB/ModuleB.md @@ -0,0 +1,5 @@ +# Module childProjectB +This is the child module B + +# Package demo +This package contains a few examples of Dokka usage. diff --git a/dokka-runners/dokkatoo/examples/multimodule-example/dokkatoo/parentProject/childProjectB/build.gradle.kts b/dokka-runners/dokkatoo/examples/multimodule-example/dokkatoo/parentProject/childProjectB/build.gradle.kts new file mode 100644 index 00000000..69e066bb --- /dev/null +++ b/dokka-runners/dokkatoo/examples/multimodule-example/dokkatoo/parentProject/childProjectB/build.gradle.kts @@ -0,0 +1,21 @@ +plugins { + kotlin("jvm") + `dokka-convention` +} + +dokkatoo { + dokkatooSourceSets.configureEach { + includes.from("ModuleB.md") + } +} + +//region DON'T COPY - this is only needed for internal Dokkatoo integration tests +dokkatoo { + modulePath.set("childProjectB") // match the original dokka default +} +tasks.withType().configureEach { + generator.dokkaSourceSets.configureEach { + sourceSetScope.set(":parentProject:childProjectB:dokkaHtmlPartial") + } +} +//endregion diff --git a/dokka-runners/dokkatoo/examples/multimodule-example/dokkatoo/parentProject/childProjectB/src/main/kotlin/demo/ChildProjectBClass.kt b/dokka-runners/dokkatoo/examples/multimodule-example/dokkatoo/parentProject/childProjectB/src/main/kotlin/demo/ChildProjectBClass.kt new file mode 100644 index 00000000..6bfd22eb --- /dev/null +++ b/dokka-runners/dokkatoo/examples/multimodule-example/dokkatoo/parentProject/childProjectB/src/main/kotlin/demo/ChildProjectBClass.kt @@ -0,0 +1,8 @@ +@file:Suppress("unused") + +package demo + +/** + * Class defined in child module b + */ +class ChildProjectBClass diff --git a/dokka-runners/dokkatoo/examples/multimodule-example/dokkatoo/settings.gradle.kts b/dokka-runners/dokkatoo/examples/multimodule-example/dokkatoo/settings.gradle.kts new file mode 100644 index 00000000..a091e8cc --- /dev/null +++ b/dokka-runners/dokkatoo/examples/multimodule-example/dokkatoo/settings.gradle.kts @@ -0,0 +1,21 @@ +rootProject.name = "dokkatoo-multimodule-example" + +pluginManagement { + repositories { + mavenCentral() + gradlePluginPortal() + maven(providers.gradleProperty("testMavenRepo")) + } +} + +@Suppress("UnstableApiUsage") +dependencyResolutionManagement { + repositories { + mavenCentral() + maven(providers.gradleProperty("testMavenRepo")) + } +} + +include(":parentProject") +include(":parentProject:childProjectA") +include(":parentProject:childProjectB") diff --git a/dokka-runners/dokkatoo/examples/multiplatform-example/dokka/README.md b/dokka-runners/dokkatoo/examples/multiplatform-example/dokka/README.md new file mode 100644 index 00000000..9b8a85e6 --- /dev/null +++ b/dokka-runners/dokkatoo/examples/multiplatform-example/dokka/README.md @@ -0,0 +1,29 @@ +# Dokka Multiplatform example + +This example demonstrates Dokka's configuration and output for a simple +[Kotlin Multiplatform](https://kotlinlang.org/docs/multiplatform.html) project. + +It contains [Kotlin source sets](https://kotlinlang.org/docs/multiplatform-discover-project.html#source-sets) for different +platforms that are automatically picked up by Dokka from the Kotlin Gradle Plugin, and an additional custom source +set known to Dokka only. + +The example demonstrates the following things: + +* Documentation for common code +* Documentation for expect/actual declarations available via tabs +* Documentation for platform-specific declarations, including functions from different source sets, but + with clashing names +* Use of Platform-specific API, such as `CPointer` from `kotlinx.cinterop` + +You can see up-to-date documentation generated for this example on +[GitHub Pages](https://kotlin.github.io/dokka/examples/dokka-multiplatform-example/html/index.html). + +![screenshot demonstration of output](demo.png) + +### Running + +Run `dokkaHtml` task in order to generate documentation for this example: + +```bash +./gradlew dokkaHtml +``` diff --git a/dokka-runners/dokkatoo/examples/multiplatform-example/dokka/build.gradle.kts b/dokka-runners/dokkatoo/examples/multiplatform-example/dokka/build.gradle.kts new file mode 100644 index 00000000..7c5f11cf --- /dev/null +++ b/dokka-runners/dokkatoo/examples/multiplatform-example/dokka/build.gradle.kts @@ -0,0 +1,42 @@ +@file:Suppress("UNUSED_VARIABLE") + +import org.jetbrains.dokka.gradle.DokkaTask +import org.jetbrains.dokka.Platform + +plugins { + kotlin("multiplatform") version "1.9.0" + id("org.jetbrains.dokka") version "1.9.0" +} + +repositories { + mavenCentral() +} + +group = "org.dokka.example" +version = "1.0-SNAPSHOT" + +kotlin { + jvm() // Creates a JVM target with the default name "jvm" + linuxX64("linux") + macosX64("macos") + js() + sourceSets { + val commonMain by getting { + dependencies { + implementation(kotlin("stdlib-common")) + implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.5.1") + } + } + } +} + +tasks.withType().configureEach { + dokkaSourceSets { + // Create a custom source set not known to the Kotlin Gradle Plugin + register("customSourceSet") { + this.jdkVersion.set(9) + this.displayName.set("custom") + this.sourceRoots.from(file("src/customJdk9/kotlin")) + } + } +} diff --git a/dokka-runners/dokkatoo/examples/multiplatform-example/dokka/demo.png b/dokka-runners/dokkatoo/examples/multiplatform-example/dokka/demo.png new file mode 100644 index 00000000..58798ccf Binary files /dev/null and b/dokka-runners/dokkatoo/examples/multiplatform-example/dokka/demo.png differ diff --git a/dokka-runners/dokkatoo/examples/multiplatform-example/dokka/settings.gradle.kts b/dokka-runners/dokkatoo/examples/multiplatform-example/dokka/settings.gradle.kts new file mode 100644 index 00000000..e9daf094 --- /dev/null +++ b/dokka-runners/dokkatoo/examples/multiplatform-example/dokka/settings.gradle.kts @@ -0,0 +1,2 @@ +rootProject.name = "dokka-multiplatform-example" + diff --git a/dokka-runners/dokkatoo/examples/multiplatform-example/dokka/src/commonMain/kotlin/org/kotlintestmpp/CommonCoroutineExtensions.kt b/dokka-runners/dokkatoo/examples/multiplatform-example/dokka/src/commonMain/kotlin/org/kotlintestmpp/CommonCoroutineExtensions.kt new file mode 100644 index 00000000..30bea657 --- /dev/null +++ b/dokka-runners/dokkatoo/examples/multiplatform-example/dokka/src/commonMain/kotlin/org/kotlintestmpp/CommonCoroutineExtensions.kt @@ -0,0 +1,15 @@ +package org.kotlintestmpp.coroutines + +import kotlinx.coroutines.CoroutineScope +import kotlinx.coroutines.CoroutineDispatcher +import kotlinx.coroutines.Deferred + +/** + * Common `expect` declaration + */ +expect fun CoroutineScope.asyncWithDealy(delay: Long, block: suspend () -> T): Deferred + +/** + * Common coroutine extension + */ +fun CoroutineDispatcher.name(): String = TODO("Not implemented") diff --git a/dokka-runners/dokkatoo/examples/multiplatform-example/dokka/src/commonMain/kotlin/org/kotlintestmpp/CommonDateUtils.kt b/dokka-runners/dokkatoo/examples/multiplatform-example/dokka/src/commonMain/kotlin/org/kotlintestmpp/CommonDateUtils.kt new file mode 100644 index 00000000..b241f5ea --- /dev/null +++ b/dokka-runners/dokkatoo/examples/multiplatform-example/dokka/src/commonMain/kotlin/org/kotlintestmpp/CommonDateUtils.kt @@ -0,0 +1,14 @@ +package org.kotlintestmpp.date + +/** + * Common `expect` declaration + */ +expect fun getCurrentDate(): String + +/** + * Common date util function + */ +fun getDate(): String { + return "Today's Date is ${getCurrentDate()}" +} + diff --git a/dokka-runners/dokkatoo/examples/multiplatform-example/dokka/src/commonMain/kotlin/org/kotlintestmpp/common/Foo.kt b/dokka-runners/dokkatoo/examples/multiplatform-example/dokka/src/commonMain/kotlin/org/kotlintestmpp/common/Foo.kt new file mode 100644 index 00000000..96c825c5 --- /dev/null +++ b/dokka-runners/dokkatoo/examples/multiplatform-example/dokka/src/commonMain/kotlin/org/kotlintestmpp/common/Foo.kt @@ -0,0 +1,7 @@ +package org.kotlintestmpp.common + +/** + * Common Foo class + */ +class Foo {} + diff --git a/dokka-runners/dokkatoo/examples/multiplatform-example/dokka/src/customJdk9/kotlin/org/kotlintest/jdk9/CustomSourceSetFile.kt b/dokka-runners/dokkatoo/examples/multiplatform-example/dokka/src/customJdk9/kotlin/org/kotlintest/jdk9/CustomSourceSetFile.kt new file mode 100644 index 00000000..d77b959b --- /dev/null +++ b/dokka-runners/dokkatoo/examples/multiplatform-example/dokka/src/customJdk9/kotlin/org/kotlintest/jdk9/CustomSourceSetFile.kt @@ -0,0 +1,11 @@ +package org.kotlintest.jdk9 + +/** + * This class demonstrates custom dokka source sets + */ +class CustomSourceSetFile { + /** + * This function will not do anything + */ + fun thisIsAFunction() {} +} diff --git a/dokka-runners/dokkatoo/examples/multiplatform-example/dokka/src/jsMain/kotlin/org/kotlintestmpp/JsCoroutineExtensions.kt b/dokka-runners/dokkatoo/examples/multiplatform-example/dokka/src/jsMain/kotlin/org/kotlintestmpp/JsCoroutineExtensions.kt new file mode 100644 index 00000000..85d6beb0 --- /dev/null +++ b/dokka-runners/dokkatoo/examples/multiplatform-example/dokka/src/jsMain/kotlin/org/kotlintestmpp/JsCoroutineExtensions.kt @@ -0,0 +1,11 @@ +package org.kotlintestmpp.coroutines + +import kotlinx.coroutines.CoroutineScope +import kotlinx.coroutines.Deferred + +/** + * JS actual implementation for `asyncWithDelay` + */ +actual fun CoroutineScope.asyncWithDealy(delay: Long, block: suspend () -> T): Deferred { + TODO("Not yet implemented") +} diff --git a/dokka-runners/dokkatoo/examples/multiplatform-example/dokka/src/jsMain/kotlin/org/kotlintestmpp/JsDateUtils.kt b/dokka-runners/dokkatoo/examples/multiplatform-example/dokka/src/jsMain/kotlin/org/kotlintestmpp/JsDateUtils.kt new file mode 100644 index 00000000..2f4f3c45 --- /dev/null +++ b/dokka-runners/dokkatoo/examples/multiplatform-example/dokka/src/jsMain/kotlin/org/kotlintestmpp/JsDateUtils.kt @@ -0,0 +1,8 @@ +package org.kotlintestmpp.date + +/** + * JS actual implementation for `getCurrentDate` + */ +actual fun getCurrentDate(): String { + return "test" +} diff --git a/dokka-runners/dokkatoo/examples/multiplatform-example/dokka/src/jsMain/kotlin/org/kotlintestmpp/JsFunctions.kt b/dokka-runners/dokkatoo/examples/multiplatform-example/dokka/src/jsMain/kotlin/org/kotlintestmpp/JsFunctions.kt new file mode 100644 index 00000000..76757359 --- /dev/null +++ b/dokka-runners/dokkatoo/examples/multiplatform-example/dokka/src/jsMain/kotlin/org/kotlintestmpp/JsFunctions.kt @@ -0,0 +1,18 @@ +package org.kotlintestmpp + +/** + * Function declares in JS source set + */ +fun js() {} + +/** + * Function declared in JS source set. + * + * Function with the same name exists in another source set as well. + */ +fun shared() {} + +/** + * Extension declared in JS source set + */ +fun String.myExtension() = println("test") diff --git a/dokka-runners/dokkatoo/examples/multiplatform-example/dokka/src/jvmMain/kotlin/org/kotlintestmpp/JavaAnnotation.java b/dokka-runners/dokkatoo/examples/multiplatform-example/dokka/src/jvmMain/kotlin/org/kotlintestmpp/JavaAnnotation.java new file mode 100644 index 00000000..8b11ca09 --- /dev/null +++ b/dokka-runners/dokkatoo/examples/multiplatform-example/dokka/src/jvmMain/kotlin/org/kotlintestmpp/JavaAnnotation.java @@ -0,0 +1,19 @@ +package org.kotlintestmpp; + +import java.lang.annotation.ElementType; +import java.lang.annotation.Retention; +import java.lang.annotation.RetentionPolicy; +import java.lang.annotation.Target; + +/** + * This is a Java annotation + */ +@Target(ElementType.TYPE) +@Retention(RetentionPolicy.RUNTIME) +public @interface JavaAnnotation { + String usage(); + + String[] aliases(); + + String description(); +} diff --git a/dokka-runners/dokkatoo/examples/multiplatform-example/dokka/src/jvmMain/kotlin/org/kotlintestmpp/JvmCoroutineExtensions.kt b/dokka-runners/dokkatoo/examples/multiplatform-example/dokka/src/jvmMain/kotlin/org/kotlintestmpp/JvmCoroutineExtensions.kt new file mode 100644 index 00000000..8f7fda49 --- /dev/null +++ b/dokka-runners/dokkatoo/examples/multiplatform-example/dokka/src/jvmMain/kotlin/org/kotlintestmpp/JvmCoroutineExtensions.kt @@ -0,0 +1,11 @@ +package org.kotlintestmpp.coroutines + +import kotlinx.coroutines.CoroutineScope +import kotlinx.coroutines.Deferred + +/** + * JVM actual implementation for `asyncWithDelay` + */ +actual fun CoroutineScope.asyncWithDealy(delay: Long, block: suspend () -> T): Deferred { + TODO("Not yet implemented") +} diff --git a/dokka-runners/dokkatoo/examples/multiplatform-example/dokka/src/jvmMain/kotlin/org/kotlintestmpp/JvmDateUtils.kt b/dokka-runners/dokkatoo/examples/multiplatform-example/dokka/src/jvmMain/kotlin/org/kotlintestmpp/JvmDateUtils.kt new file mode 100644 index 00000000..db7f2d74 --- /dev/null +++ b/dokka-runners/dokkatoo/examples/multiplatform-example/dokka/src/jvmMain/kotlin/org/kotlintestmpp/JvmDateUtils.kt @@ -0,0 +1,8 @@ +package org.kotlintestmpp.date + +/** + * JVM actual implementation for `getCurrentDate` + */ +actual fun getCurrentDate(): String { + return "test" +} diff --git a/dokka-runners/dokkatoo/examples/multiplatform-example/dokka/src/jvmMain/kotlin/org/kotlintestmpp/JvmFunctions.kt b/dokka-runners/dokkatoo/examples/multiplatform-example/dokka/src/jvmMain/kotlin/org/kotlintestmpp/JvmFunctions.kt new file mode 100644 index 00000000..0ef8a99d --- /dev/null +++ b/dokka-runners/dokkatoo/examples/multiplatform-example/dokka/src/jvmMain/kotlin/org/kotlintestmpp/JvmFunctions.kt @@ -0,0 +1,35 @@ +package org.kotlintestmpp + +import kotlinx.coroutines.CoroutineScope +import kotlinx.coroutines.Job +import kotlinx.coroutines.launch +import org.kotlintestmpp.common.Foo + +/** + * Function declared in JVM source set + * + * also see the [Foo] class + * @see org.kotlintestmpp.common.Foo + */ +fun jvm() {} + +/** + * Function declared in JVM source set + * + * Function with the same name exists in another source set as well. + */ +fun shared() {} + +/** + * Extension declared in JVM source set + */ +fun CoroutineScope.startConnectionPipeline( + input: String +): Job = launch { TODO() } + +/** + * Extension declared in JVM source set + */ +fun String.myExtension() = println("test2") + + diff --git a/dokka-runners/dokkatoo/examples/multiplatform-example/dokka/src/linuxMain/kotlin/org/kotlintestmpp/CInterop.kt b/dokka-runners/dokkatoo/examples/multiplatform-example/dokka/src/linuxMain/kotlin/org/kotlintestmpp/CInterop.kt new file mode 100644 index 00000000..5c84780b --- /dev/null +++ b/dokka-runners/dokkatoo/examples/multiplatform-example/dokka/src/linuxMain/kotlin/org/kotlintestmpp/CInterop.kt @@ -0,0 +1,15 @@ +@file:Suppress("unused") + +package org.kotlintestmpp + +import kotlinx.cinterop.CPointed +import kotlinx.cinterop.CPointer +import kotlinx.cinterop.ExperimentalForeignApi + +/** + * Low-level Linux function + */ +@OptIn(ExperimentalForeignApi::class) +fun printPointerRawValue(pointer: CPointer) { + println(pointer.rawValue) +} diff --git a/dokka-runners/dokkatoo/examples/multiplatform-example/dokka/src/linuxMain/kotlin/org/kotlintestmpp/LinuxCoroutineExtensions.kt b/dokka-runners/dokkatoo/examples/multiplatform-example/dokka/src/linuxMain/kotlin/org/kotlintestmpp/LinuxCoroutineExtensions.kt new file mode 100644 index 00000000..b561272d --- /dev/null +++ b/dokka-runners/dokkatoo/examples/multiplatform-example/dokka/src/linuxMain/kotlin/org/kotlintestmpp/LinuxCoroutineExtensions.kt @@ -0,0 +1,11 @@ +package org.kotlintestmpp.coroutines + +import kotlinx.coroutines.CoroutineScope +import kotlinx.coroutines.Deferred + +/** + * Linux actual implementation for `asyncWithDelay` + */ +actual fun CoroutineScope.asyncWithDealy(delay: Long, block: suspend () -> T): Deferred { + TODO("Not yet implemented") +} diff --git a/dokka-runners/dokkatoo/examples/multiplatform-example/dokka/src/linuxMain/kotlin/org/kotlintestmpp/LinuxDateUtils.kt b/dokka-runners/dokkatoo/examples/multiplatform-example/dokka/src/linuxMain/kotlin/org/kotlintestmpp/LinuxDateUtils.kt new file mode 100644 index 00000000..8900f87b --- /dev/null +++ b/dokka-runners/dokkatoo/examples/multiplatform-example/dokka/src/linuxMain/kotlin/org/kotlintestmpp/LinuxDateUtils.kt @@ -0,0 +1,8 @@ +package org.kotlintestmpp.date + +/** + * Linux actual implementation for `getCurrentDate` + */ +actual fun getCurrentDate(): String { + TODO("Not yet implemented") +} diff --git a/dokka-runners/dokkatoo/examples/multiplatform-example/dokka/src/macosMain/kotlin/org/kotlintestmpp/MacOsCoroutineExtensions.kt b/dokka-runners/dokkatoo/examples/multiplatform-example/dokka/src/macosMain/kotlin/org/kotlintestmpp/MacOsCoroutineExtensions.kt new file mode 100644 index 00000000..8576982c --- /dev/null +++ b/dokka-runners/dokkatoo/examples/multiplatform-example/dokka/src/macosMain/kotlin/org/kotlintestmpp/MacOsCoroutineExtensions.kt @@ -0,0 +1,11 @@ +package org.kotlintestmpp.coroutines + +import kotlinx.coroutines.CoroutineScope +import kotlinx.coroutines.Deferred + +/** + * MacOS actual implementation for `asyncWithDelay` + */ +actual fun CoroutineScope.asyncWithDealy(delay: Long, block: suspend () -> T): Deferred { + TODO("Not yet implemented") +} diff --git a/dokka-runners/dokkatoo/examples/multiplatform-example/dokka/src/macosMain/kotlin/org/kotlintestmpp/MacOsDateUtils.kt b/dokka-runners/dokkatoo/examples/multiplatform-example/dokka/src/macosMain/kotlin/org/kotlintestmpp/MacOsDateUtils.kt new file mode 100644 index 00000000..accf98a9 --- /dev/null +++ b/dokka-runners/dokkatoo/examples/multiplatform-example/dokka/src/macosMain/kotlin/org/kotlintestmpp/MacOsDateUtils.kt @@ -0,0 +1,8 @@ +package org.kotlintestmpp.date + +/** + * MacOS actual implementation for `getCurrentDate` + */ +actual fun getCurrentDate(): String { + TODO("Not yet implemented") +} diff --git a/dokka-runners/dokkatoo/examples/multiplatform-example/dokkatoo/build.gradle.kts b/dokka-runners/dokkatoo/examples/multiplatform-example/dokkatoo/build.gradle.kts new file mode 100644 index 00000000..3d5a9e0d --- /dev/null +++ b/dokka-runners/dokkatoo/examples/multiplatform-example/dokkatoo/build.gradle.kts @@ -0,0 +1,39 @@ +plugins { + kotlin("multiplatform") version "1.9.0" + id("org.jetbrains.dokka.dokkatoo") version "2.1.0-SNAPSHOT" +} + +group = "org.dokka.example" +version = "1.0-SNAPSHOT" + +kotlin { + jvm() // Creates a JVM target with the default name "jvm" + linuxX64("linux") + macosX64("macos") + js(IR) { + browser() + } + sourceSets { + commonMain { + dependencies { + implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.5.1") + } + } + } +} + +dokkatoo { + // Create a custom source set not known to the Kotlin Gradle Plugin + dokkatooSourceSets.register("customSourceSet") { + jdkVersion.set(9) + displayName.set("custom") + sourceRoots.from("src/customJdk9/kotlin") + } +} + + +//region DON'T COPY - this is only needed for internal Dokkatoo integration tests +dokkatoo { + sourceSetScopeDefault.set(":dokkaHtml") +} +//endregion diff --git a/dokka-runners/dokkatoo/examples/multiplatform-example/dokkatoo/settings.gradle.kts b/dokka-runners/dokkatoo/examples/multiplatform-example/dokkatoo/settings.gradle.kts new file mode 100644 index 00000000..014a7584 --- /dev/null +++ b/dokka-runners/dokkatoo/examples/multiplatform-example/dokkatoo/settings.gradle.kts @@ -0,0 +1,17 @@ +rootProject.name = "dokka-multiplatform-example" + +pluginManagement { + repositories { + gradlePluginPortal() + mavenCentral() + maven(providers.gradleProperty("testMavenRepo")) + } +} + +@Suppress("UnstableApiUsage") +dependencyResolutionManagement { + repositories { + mavenCentral() + maven(providers.gradleProperty("testMavenRepo")) + } +} diff --git a/dokka-runners/dokkatoo/examples/multiplatform-example/dokkatoo/src/commonMain/kotlin/org/kotlintestmpp/CommonCoroutineExtensions.kt b/dokka-runners/dokkatoo/examples/multiplatform-example/dokkatoo/src/commonMain/kotlin/org/kotlintestmpp/CommonCoroutineExtensions.kt new file mode 100644 index 00000000..30bea657 --- /dev/null +++ b/dokka-runners/dokkatoo/examples/multiplatform-example/dokkatoo/src/commonMain/kotlin/org/kotlintestmpp/CommonCoroutineExtensions.kt @@ -0,0 +1,15 @@ +package org.kotlintestmpp.coroutines + +import kotlinx.coroutines.CoroutineScope +import kotlinx.coroutines.CoroutineDispatcher +import kotlinx.coroutines.Deferred + +/** + * Common `expect` declaration + */ +expect fun CoroutineScope.asyncWithDealy(delay: Long, block: suspend () -> T): Deferred + +/** + * Common coroutine extension + */ +fun CoroutineDispatcher.name(): String = TODO("Not implemented") diff --git a/dokka-runners/dokkatoo/examples/multiplatform-example/dokkatoo/src/commonMain/kotlin/org/kotlintestmpp/CommonDateUtils.kt b/dokka-runners/dokkatoo/examples/multiplatform-example/dokkatoo/src/commonMain/kotlin/org/kotlintestmpp/CommonDateUtils.kt new file mode 100644 index 00000000..b241f5ea --- /dev/null +++ b/dokka-runners/dokkatoo/examples/multiplatform-example/dokkatoo/src/commonMain/kotlin/org/kotlintestmpp/CommonDateUtils.kt @@ -0,0 +1,14 @@ +package org.kotlintestmpp.date + +/** + * Common `expect` declaration + */ +expect fun getCurrentDate(): String + +/** + * Common date util function + */ +fun getDate(): String { + return "Today's Date is ${getCurrentDate()}" +} + diff --git a/dokka-runners/dokkatoo/examples/multiplatform-example/dokkatoo/src/commonMain/kotlin/org/kotlintestmpp/common/Foo.kt b/dokka-runners/dokkatoo/examples/multiplatform-example/dokkatoo/src/commonMain/kotlin/org/kotlintestmpp/common/Foo.kt new file mode 100644 index 00000000..96c825c5 --- /dev/null +++ b/dokka-runners/dokkatoo/examples/multiplatform-example/dokkatoo/src/commonMain/kotlin/org/kotlintestmpp/common/Foo.kt @@ -0,0 +1,7 @@ +package org.kotlintestmpp.common + +/** + * Common Foo class + */ +class Foo {} + diff --git a/dokka-runners/dokkatoo/examples/multiplatform-example/dokkatoo/src/customJdk9/kotlin/org/kotlintest/jdk9/CustomSourceSetFile.kt b/dokka-runners/dokkatoo/examples/multiplatform-example/dokkatoo/src/customJdk9/kotlin/org/kotlintest/jdk9/CustomSourceSetFile.kt new file mode 100644 index 00000000..d77b959b --- /dev/null +++ b/dokka-runners/dokkatoo/examples/multiplatform-example/dokkatoo/src/customJdk9/kotlin/org/kotlintest/jdk9/CustomSourceSetFile.kt @@ -0,0 +1,11 @@ +package org.kotlintest.jdk9 + +/** + * This class demonstrates custom dokka source sets + */ +class CustomSourceSetFile { + /** + * This function will not do anything + */ + fun thisIsAFunction() {} +} diff --git a/dokka-runners/dokkatoo/examples/multiplatform-example/dokkatoo/src/jsMain/kotlin/org/kotlintestmpp/JsCoroutineExtensions.kt b/dokka-runners/dokkatoo/examples/multiplatform-example/dokkatoo/src/jsMain/kotlin/org/kotlintestmpp/JsCoroutineExtensions.kt new file mode 100644 index 00000000..85d6beb0 --- /dev/null +++ b/dokka-runners/dokkatoo/examples/multiplatform-example/dokkatoo/src/jsMain/kotlin/org/kotlintestmpp/JsCoroutineExtensions.kt @@ -0,0 +1,11 @@ +package org.kotlintestmpp.coroutines + +import kotlinx.coroutines.CoroutineScope +import kotlinx.coroutines.Deferred + +/** + * JS actual implementation for `asyncWithDelay` + */ +actual fun CoroutineScope.asyncWithDealy(delay: Long, block: suspend () -> T): Deferred { + TODO("Not yet implemented") +} diff --git a/dokka-runners/dokkatoo/examples/multiplatform-example/dokkatoo/src/jsMain/kotlin/org/kotlintestmpp/JsDateUtils.kt b/dokka-runners/dokkatoo/examples/multiplatform-example/dokkatoo/src/jsMain/kotlin/org/kotlintestmpp/JsDateUtils.kt new file mode 100644 index 00000000..2f4f3c45 --- /dev/null +++ b/dokka-runners/dokkatoo/examples/multiplatform-example/dokkatoo/src/jsMain/kotlin/org/kotlintestmpp/JsDateUtils.kt @@ -0,0 +1,8 @@ +package org.kotlintestmpp.date + +/** + * JS actual implementation for `getCurrentDate` + */ +actual fun getCurrentDate(): String { + return "test" +} diff --git a/dokka-runners/dokkatoo/examples/multiplatform-example/dokkatoo/src/jsMain/kotlin/org/kotlintestmpp/JsFunctions.kt b/dokka-runners/dokkatoo/examples/multiplatform-example/dokkatoo/src/jsMain/kotlin/org/kotlintestmpp/JsFunctions.kt new file mode 100644 index 00000000..76757359 --- /dev/null +++ b/dokka-runners/dokkatoo/examples/multiplatform-example/dokkatoo/src/jsMain/kotlin/org/kotlintestmpp/JsFunctions.kt @@ -0,0 +1,18 @@ +package org.kotlintestmpp + +/** + * Function declares in JS source set + */ +fun js() {} + +/** + * Function declared in JS source set. + * + * Function with the same name exists in another source set as well. + */ +fun shared() {} + +/** + * Extension declared in JS source set + */ +fun String.myExtension() = println("test") diff --git a/dokka-runners/dokkatoo/examples/multiplatform-example/dokkatoo/src/jvmMain/kotlin/org/kotlintestmpp/JavaAnnotation.java b/dokka-runners/dokkatoo/examples/multiplatform-example/dokkatoo/src/jvmMain/kotlin/org/kotlintestmpp/JavaAnnotation.java new file mode 100644 index 00000000..8b11ca09 --- /dev/null +++ b/dokka-runners/dokkatoo/examples/multiplatform-example/dokkatoo/src/jvmMain/kotlin/org/kotlintestmpp/JavaAnnotation.java @@ -0,0 +1,19 @@ +package org.kotlintestmpp; + +import java.lang.annotation.ElementType; +import java.lang.annotation.Retention; +import java.lang.annotation.RetentionPolicy; +import java.lang.annotation.Target; + +/** + * This is a Java annotation + */ +@Target(ElementType.TYPE) +@Retention(RetentionPolicy.RUNTIME) +public @interface JavaAnnotation { + String usage(); + + String[] aliases(); + + String description(); +} diff --git a/dokka-runners/dokkatoo/examples/multiplatform-example/dokkatoo/src/jvmMain/kotlin/org/kotlintestmpp/JvmCoroutineExtensions.kt b/dokka-runners/dokkatoo/examples/multiplatform-example/dokkatoo/src/jvmMain/kotlin/org/kotlintestmpp/JvmCoroutineExtensions.kt new file mode 100644 index 00000000..8f7fda49 --- /dev/null +++ b/dokka-runners/dokkatoo/examples/multiplatform-example/dokkatoo/src/jvmMain/kotlin/org/kotlintestmpp/JvmCoroutineExtensions.kt @@ -0,0 +1,11 @@ +package org.kotlintestmpp.coroutines + +import kotlinx.coroutines.CoroutineScope +import kotlinx.coroutines.Deferred + +/** + * JVM actual implementation for `asyncWithDelay` + */ +actual fun CoroutineScope.asyncWithDealy(delay: Long, block: suspend () -> T): Deferred { + TODO("Not yet implemented") +} diff --git a/dokka-runners/dokkatoo/examples/multiplatform-example/dokkatoo/src/jvmMain/kotlin/org/kotlintestmpp/JvmDateUtils.kt b/dokka-runners/dokkatoo/examples/multiplatform-example/dokkatoo/src/jvmMain/kotlin/org/kotlintestmpp/JvmDateUtils.kt new file mode 100644 index 00000000..db7f2d74 --- /dev/null +++ b/dokka-runners/dokkatoo/examples/multiplatform-example/dokkatoo/src/jvmMain/kotlin/org/kotlintestmpp/JvmDateUtils.kt @@ -0,0 +1,8 @@ +package org.kotlintestmpp.date + +/** + * JVM actual implementation for `getCurrentDate` + */ +actual fun getCurrentDate(): String { + return "test" +} diff --git a/dokka-runners/dokkatoo/examples/multiplatform-example/dokkatoo/src/jvmMain/kotlin/org/kotlintestmpp/JvmFunctions.kt b/dokka-runners/dokkatoo/examples/multiplatform-example/dokkatoo/src/jvmMain/kotlin/org/kotlintestmpp/JvmFunctions.kt new file mode 100644 index 00000000..0ef8a99d --- /dev/null +++ b/dokka-runners/dokkatoo/examples/multiplatform-example/dokkatoo/src/jvmMain/kotlin/org/kotlintestmpp/JvmFunctions.kt @@ -0,0 +1,35 @@ +package org.kotlintestmpp + +import kotlinx.coroutines.CoroutineScope +import kotlinx.coroutines.Job +import kotlinx.coroutines.launch +import org.kotlintestmpp.common.Foo + +/** + * Function declared in JVM source set + * + * also see the [Foo] class + * @see org.kotlintestmpp.common.Foo + */ +fun jvm() {} + +/** + * Function declared in JVM source set + * + * Function with the same name exists in another source set as well. + */ +fun shared() {} + +/** + * Extension declared in JVM source set + */ +fun CoroutineScope.startConnectionPipeline( + input: String +): Job = launch { TODO() } + +/** + * Extension declared in JVM source set + */ +fun String.myExtension() = println("test2") + + diff --git a/dokka-runners/dokkatoo/examples/multiplatform-example/dokkatoo/src/linuxMain/kotlin/org/kotlintestmpp/CInterop.kt b/dokka-runners/dokkatoo/examples/multiplatform-example/dokkatoo/src/linuxMain/kotlin/org/kotlintestmpp/CInterop.kt new file mode 100644 index 00000000..5c84780b --- /dev/null +++ b/dokka-runners/dokkatoo/examples/multiplatform-example/dokkatoo/src/linuxMain/kotlin/org/kotlintestmpp/CInterop.kt @@ -0,0 +1,15 @@ +@file:Suppress("unused") + +package org.kotlintestmpp + +import kotlinx.cinterop.CPointed +import kotlinx.cinterop.CPointer +import kotlinx.cinterop.ExperimentalForeignApi + +/** + * Low-level Linux function + */ +@OptIn(ExperimentalForeignApi::class) +fun printPointerRawValue(pointer: CPointer) { + println(pointer.rawValue) +} diff --git a/dokka-runners/dokkatoo/examples/multiplatform-example/dokkatoo/src/linuxMain/kotlin/org/kotlintestmpp/LinuxCoroutineExtensions.kt b/dokka-runners/dokkatoo/examples/multiplatform-example/dokkatoo/src/linuxMain/kotlin/org/kotlintestmpp/LinuxCoroutineExtensions.kt new file mode 100644 index 00000000..b561272d --- /dev/null +++ b/dokka-runners/dokkatoo/examples/multiplatform-example/dokkatoo/src/linuxMain/kotlin/org/kotlintestmpp/LinuxCoroutineExtensions.kt @@ -0,0 +1,11 @@ +package org.kotlintestmpp.coroutines + +import kotlinx.coroutines.CoroutineScope +import kotlinx.coroutines.Deferred + +/** + * Linux actual implementation for `asyncWithDelay` + */ +actual fun CoroutineScope.asyncWithDealy(delay: Long, block: suspend () -> T): Deferred { + TODO("Not yet implemented") +} diff --git a/dokka-runners/dokkatoo/examples/multiplatform-example/dokkatoo/src/linuxMain/kotlin/org/kotlintestmpp/LinuxDateUtils.kt b/dokka-runners/dokkatoo/examples/multiplatform-example/dokkatoo/src/linuxMain/kotlin/org/kotlintestmpp/LinuxDateUtils.kt new file mode 100644 index 00000000..8900f87b --- /dev/null +++ b/dokka-runners/dokkatoo/examples/multiplatform-example/dokkatoo/src/linuxMain/kotlin/org/kotlintestmpp/LinuxDateUtils.kt @@ -0,0 +1,8 @@ +package org.kotlintestmpp.date + +/** + * Linux actual implementation for `getCurrentDate` + */ +actual fun getCurrentDate(): String { + TODO("Not yet implemented") +} diff --git a/dokka-runners/dokkatoo/examples/multiplatform-example/dokkatoo/src/macosMain/kotlin/org/kotlintestmpp/MacOsCoroutineExtensions.kt b/dokka-runners/dokkatoo/examples/multiplatform-example/dokkatoo/src/macosMain/kotlin/org/kotlintestmpp/MacOsCoroutineExtensions.kt new file mode 100644 index 00000000..8576982c --- /dev/null +++ b/dokka-runners/dokkatoo/examples/multiplatform-example/dokkatoo/src/macosMain/kotlin/org/kotlintestmpp/MacOsCoroutineExtensions.kt @@ -0,0 +1,11 @@ +package org.kotlintestmpp.coroutines + +import kotlinx.coroutines.CoroutineScope +import kotlinx.coroutines.Deferred + +/** + * MacOS actual implementation for `asyncWithDelay` + */ +actual fun CoroutineScope.asyncWithDealy(delay: Long, block: suspend () -> T): Deferred { + TODO("Not yet implemented") +} diff --git a/dokka-runners/dokkatoo/examples/multiplatform-example/dokkatoo/src/macosMain/kotlin/org/kotlintestmpp/MacOsDateUtils.kt b/dokka-runners/dokkatoo/examples/multiplatform-example/dokkatoo/src/macosMain/kotlin/org/kotlintestmpp/MacOsDateUtils.kt new file mode 100644 index 00000000..accf98a9 --- /dev/null +++ b/dokka-runners/dokkatoo/examples/multiplatform-example/dokkatoo/src/macosMain/kotlin/org/kotlintestmpp/MacOsDateUtils.kt @@ -0,0 +1,8 @@ +package org.kotlintestmpp.date + +/** + * MacOS actual implementation for `getCurrentDate` + */ +actual fun getCurrentDate(): String { + TODO("Not yet implemented") +} diff --git a/dokka-runners/dokkatoo/examples/versioning-multimodule-example/dokka/README.md b/dokka-runners/dokkatoo/examples/versioning-multimodule-example/dokka/README.md new file mode 100644 index 00000000..dd012003 --- /dev/null +++ b/dokka-runners/dokkatoo/examples/versioning-multimodule-example/dokka/README.md @@ -0,0 +1,25 @@ +# Dokka Versioning MultiModule example + +This example demonstrates configuration of Dokka's [versioning plugin](../../../plugins/versioning), which +allows readers to navigate through different versions of your API reference documentation. + +The example contains some code that exists only in the current documentation version `1.0`. You will not see +this code in the previous version `0.9`, which is located in the [previousDocVersions](previousDocVersions) directory. + +___ + +You can see up-to-date documentation generated for this example on +[GitHub Pages](https://kotlin.github.io/dokka/examples/dokka-versioning-multimodule-example/htmlMultiModule/index.html). + +![screenshot demonstration of output](demo.png) + +### Running + +Run `dokkaHtmlMultiModule` task to generate documentation for this example: + +```bash +./gradlew dokkaHtmlMultiModule +``` + +It will generate complete documentation for the root project and its subprojects, with the version navigation +dropdown menu. diff --git a/dokka-runners/dokkatoo/examples/versioning-multimodule-example/dokka/build.gradle.kts b/dokka-runners/dokkatoo/examples/versioning-multimodule-example/dokka/build.gradle.kts new file mode 100644 index 00000000..14aea2b4 --- /dev/null +++ b/dokka-runners/dokkatoo/examples/versioning-multimodule-example/dokka/build.gradle.kts @@ -0,0 +1,19 @@ +plugins { + kotlin("jvm") version "1.9.0" + id("org.jetbrains.dokka") version "1.9.0" apply false +} + +// The versioning plugin must be applied in all submodules +subprojects { + repositories { + mavenCentral() + } + apply { + plugin("org.jetbrains.kotlin.jvm") + plugin("org.jetbrains.dokka") + } + val dokkaPlugin by configurations + dependencies { + dokkaPlugin("org.jetbrains.dokka:versioning-plugin:1.9.0") + } +} diff --git a/dokka-runners/dokkatoo/examples/versioning-multimodule-example/dokka/demo.png b/dokka-runners/dokkatoo/examples/versioning-multimodule-example/dokka/demo.png new file mode 100644 index 00000000..9ac1d382 Binary files /dev/null and b/dokka-runners/dokkatoo/examples/versioning-multimodule-example/dokka/demo.png differ diff --git a/dokka-runners/dokkatoo/examples/versioning-multimodule-example/dokka/parentProject/build.gradle.kts b/dokka-runners/dokkatoo/examples/versioning-multimodule-example/dokka/parentProject/build.gradle.kts new file mode 100644 index 00000000..6d830079 --- /dev/null +++ b/dokka-runners/dokkatoo/examples/versioning-multimodule-example/dokka/parentProject/build.gradle.kts @@ -0,0 +1,27 @@ +import org.jetbrains.dokka.gradle.DokkaMultiModuleTask +import org.jetbrains.dokka.versioning.VersioningPlugin +import org.jetbrains.dokka.versioning.VersioningConfiguration + +buildscript { + dependencies { + classpath("org.jetbrains.dokka:versioning-plugin:1.9.0") + } + + repositories { + mavenCentral() + } +} + +val currentVersion = "1.0" +val previousVersionsDirectory = project.rootProject.projectDir.resolve("previousDocVersions").invariantSeparatorsPath + +// Main configuration for the versioning plugin. It will generate documentation for +// the current version of the application, and look for previous versions of docs +// in the directory defined in previousVersionsDirectory, allowing it to create +// the version navigation dropdown menu. +tasks.dokkaHtmlMultiModule { + pluginConfiguration { + version = currentVersion + olderVersionsDir = file(previousVersionsDirectory) + } +} diff --git a/dokka-runners/dokkatoo/examples/versioning-multimodule-example/dokka/parentProject/childProjectA/build.gradle.kts b/dokka-runners/dokkatoo/examples/versioning-multimodule-example/dokka/parentProject/childProjectA/build.gradle.kts new file mode 100644 index 00000000..bf1513f8 --- /dev/null +++ b/dokka-runners/dokkatoo/examples/versioning-multimodule-example/dokka/parentProject/childProjectA/build.gradle.kts @@ -0,0 +1 @@ +// intentionally empty - build config is set in the root build.gradle.kts diff --git a/dokka-runners/dokkatoo/examples/versioning-multimodule-example/dokka/parentProject/childProjectA/src/main/kotlin/demo/ChildProjectAClass.kt b/dokka-runners/dokkatoo/examples/versioning-multimodule-example/dokka/parentProject/childProjectA/src/main/kotlin/demo/ChildProjectAClass.kt new file mode 100644 index 00000000..e0f9e86a --- /dev/null +++ b/dokka-runners/dokkatoo/examples/versioning-multimodule-example/dokka/parentProject/childProjectA/src/main/kotlin/demo/ChildProjectAClass.kt @@ -0,0 +1,18 @@ +@file:Suppress("unused") + +package demo + +/** + * Class defined in child project A + * + * @since 0.9 + */ +class ChildProjectAClass { + + /** + * Function that extends [ChildProjectAClass] + * + * @since 1.0 + */ + fun extend() {} +} diff --git a/dokka-runners/dokkatoo/examples/versioning-multimodule-example/dokka/parentProject/childProjectA/src/main/kotlin/demo/FancyAPI.kt b/dokka-runners/dokkatoo/examples/versioning-multimodule-example/dokka/parentProject/childProjectA/src/main/kotlin/demo/FancyAPI.kt new file mode 100644 index 00000000..e691be03 --- /dev/null +++ b/dokka-runners/dokkatoo/examples/versioning-multimodule-example/dokka/parentProject/childProjectA/src/main/kotlin/demo/FancyAPI.kt @@ -0,0 +1,10 @@ +package demo + +/** + * New shiny fancy API + * + * @since 1.0 + */ +class FancyAPI { + fun doSomething() {} +} diff --git a/dokka-runners/dokkatoo/examples/versioning-multimodule-example/dokka/parentProject/childProjectB/build.gradle.kts b/dokka-runners/dokkatoo/examples/versioning-multimodule-example/dokka/parentProject/childProjectB/build.gradle.kts new file mode 100644 index 00000000..bf1513f8 --- /dev/null +++ b/dokka-runners/dokkatoo/examples/versioning-multimodule-example/dokka/parentProject/childProjectB/build.gradle.kts @@ -0,0 +1 @@ +// intentionally empty - build config is set in the root build.gradle.kts diff --git a/dokka-runners/dokkatoo/examples/versioning-multimodule-example/dokka/parentProject/childProjectB/src/main/kotlin/demo/ChildProjectBClass.kt b/dokka-runners/dokkatoo/examples/versioning-multimodule-example/dokka/parentProject/childProjectB/src/main/kotlin/demo/ChildProjectBClass.kt new file mode 100644 index 00000000..6978a176 --- /dev/null +++ b/dokka-runners/dokkatoo/examples/versioning-multimodule-example/dokka/parentProject/childProjectB/src/main/kotlin/demo/ChildProjectBClass.kt @@ -0,0 +1,10 @@ +@file:Suppress("unused") + +package demo + +/** + * Class defined in child module B + * + * @since 0.9 + */ +class ChildProjectBClass diff --git a/dokka-runners/dokkatoo/examples/versioning-multimodule-example/dokka/parentProject/childProjectB/src/main/kotlin/demo/Functions.kt b/dokka-runners/dokkatoo/examples/versioning-multimodule-example/dokka/parentProject/childProjectB/src/main/kotlin/demo/Functions.kt new file mode 100644 index 00000000..35a9275b --- /dev/null +++ b/dokka-runners/dokkatoo/examples/versioning-multimodule-example/dokka/parentProject/childProjectB/src/main/kotlin/demo/Functions.kt @@ -0,0 +1,8 @@ +package demo + +/** + * New super function that does everything + * + * @since 1.0 + */ +fun superFunction42() {} diff --git a/dokka-runners/dokkatoo/examples/versioning-multimodule-example/dokka/settings.gradle.kts b/dokka-runners/dokkatoo/examples/versioning-multimodule-example/dokka/settings.gradle.kts new file mode 100644 index 00000000..ec6614f0 --- /dev/null +++ b/dokka-runners/dokkatoo/examples/versioning-multimodule-example/dokka/settings.gradle.kts @@ -0,0 +1,5 @@ +include(":parentProject") +include(":parentProject:childProjectA") +include(":parentProject:childProjectB") + +rootProject.name = "dokka-versioning-multimodule-example" \ No newline at end of file diff --git a/dokka-runners/dokkatoo/examples/versioning-multimodule-example/dokkatoo/settings.gradle.kts b/dokka-runners/dokkatoo/examples/versioning-multimodule-example/dokkatoo/settings.gradle.kts new file mode 100644 index 00000000..850a82bf --- /dev/null +++ b/dokka-runners/dokkatoo/examples/versioning-multimodule-example/dokkatoo/settings.gradle.kts @@ -0,0 +1,17 @@ +rootProject.name = "versioning-multimodule-example" + +pluginManagement { + repositories { + gradlePluginPortal() + mavenCentral() + maven(providers.gradleProperty("testMavenRepo")) + } +} + +@Suppress("UnstableApiUsage") +dependencyResolutionManagement { + repositories { + mavenCentral() + maven(providers.gradleProperty("testMavenRepo")) + } +} diff --git a/dokka-runners/dokkatoo/gradle.properties b/dokka-runners/dokkatoo/gradle.properties new file mode 100644 index 00000000..cb5238c6 --- /dev/null +++ b/dokka-runners/dokkatoo/gradle.properties @@ -0,0 +1,12 @@ +# memory is set quite high because the tests launch a lot of processes +org.gradle.jvmargs=-Dfile.encoding=UTF-8 -Xmx4g -XX:MaxMetaspaceSize=2g -XX:+HeapDumpOnOutOfMemoryError -XX:+AlwaysPreTouch + +org.gradle.caching=true + +org.gradle.unsafe.configuration-cache=true +org.gradle.unsafe.configuration-cache-problems=warn + +org.gradle.parallel=true +org.gradle.welcome=never + +kotlin.mpp.import.enableKgpDependencyResolution=true diff --git a/dokka-runners/dokkatoo/gradle/libs.versions.toml b/dokka-runners/dokkatoo/gradle/libs.versions.toml new file mode 100644 index 00000000..4a6fa4ff --- /dev/null +++ b/dokka-runners/dokkatoo/gradle/libs.versions.toml @@ -0,0 +1,48 @@ +[versions] + +kotlin = "1.9.0" # should match Gradle's embedded Kotlin version https://docs.gradle.org/current/userguide/compatibility.html#kotlin +kotlin-dokka = "1.9.0" +kotlinx-serialization = "1.6.0" + +kotest = "5.6.2" + +gradlePlugin-android = "8.0.2" +gradlePlugin-dokkatoo = "1.6.0" +gradlePlugin-gradlePublishPlugin = "1.2.1" +gradlePlugin-bcvMu = "0.0.4" + + +[libraries] + +## Dokka +kotlin-dokkaCore = { module = "org.jetbrains.dokka:dokka-core", version.ref = "kotlin-dokka" } +kotlin-dokkaPlugin-allModulesPage = { module = "org.jetbrains.dokka:all-modules-page-plugin", version.ref = "kotlin-dokka" } +kotlin-dokkaPlugin-templating = { module = "org.jetbrains.dokka:templating-plugin", version.ref = "kotlin-dokka" } + +## Kotlinx Serialization +kotlinxSerialization-bom = { module = "org.jetbrains.kotlinx:kotlinx-serialization-bom", version.ref = "kotlinx-serialization" } +kotlinxSerialization-json = { module = "org.jetbrains.kotlinx:kotlinx-serialization-json" } +#kotlinxSerialization-json = { module = "org.jetbrains.kotlinx:kotlinx-serialization-json", version.ref = "kotlinx-serialization" } + + +### Test libraries ### + +kotlin-test = { module = "org.jetbrains.kotlin:kotlin-test", version.ref = "kotlin" } + +kotest-bom = { module = "io.kotest:kotest-bom", version.ref = "kotest" } +kotest-datatest = { module = "io.kotest:kotest-framework-datatest" } +kotest-junit5Runner = { module = "io.kotest:kotest-runner-junit5" } +kotest-assertionsCore = { module = "io.kotest:kotest-assertions-core" } +kotest-assertionsJson = { module = "io.kotest:kotest-assertions-json" } + +### Gradle plugins ### + +gradlePlugin-android = { module = "com.android.tools.build:gradle", version.ref = "gradlePlugin-android" } +gradlePlugin-androidApi = { module = "com.android.tools.build:gradle-api", version.ref = "gradlePlugin-android" } +gradlePlugin-dokkatoo = { module = "dev.adamko.dokkatoo:dokkatoo-plugin", version.ref = "gradlePlugin-dokkatoo" } +gradlePlugin-bcvMu = { module = "dev.adamko.kotlin.binary_compatibility_validator:bcv-gradle-plugin", version.ref = "gradlePlugin-bcvMu" } +gradlePlugin-gradlePublishPlugin = { module = "com.gradle.publish:plugin-publish-plugin", version.ref = "gradlePlugin-gradlePublishPlugin" } +gradlePlugin-kotlin = { module = "org.jetbrains.kotlin:kotlin-gradle-plugin", version.ref = "kotlin" } +gradlePlugin-kotlin-klibCommonizerApi = { module = "org.jetbrains.kotlin:kotlin-klib-commonizer-api", version.ref = "kotlin" } + +[plugins] diff --git a/dokka-runners/dokkatoo/modules/docs/build.gradle.kts b/dokka-runners/dokkatoo/modules/docs/build.gradle.kts new file mode 100644 index 00000000..a27b177c --- /dev/null +++ b/dokka-runners/dokkatoo/modules/docs/build.gradle.kts @@ -0,0 +1,58 @@ +import dev.adamko.dokkatoo.dokka.plugins.DokkaHtmlPluginParameters + +plugins { + buildsrc.conventions.base + dev.adamko.`dokkatoo-html` +} + +dependencies { + dokkatoo(projects.modules.dokkatooPlugin) + dokkatooPluginHtml(libs.kotlin.dokkaPlugin.allModulesPage) + dokkatooPluginHtml(libs.kotlin.dokkaPlugin.templating) +} + +dokkatoo { + moduleName.set("Dokkatoo Gradle Plugin") + + pluginsConfiguration.named("html") { + customStyleSheets.from( + "./style/logo-styles.css", + ) + customAssets.from( + "./images/logo-icon.svg", + ) + } +} + +tasks.dokkatooGeneratePublicationHtml { + doLast { + outputDirectory.get().asFile.walk() + .filter { it.isFile && it.extension == "html" } + .forEach { file -> + file.writeText( + file.readText() + .replace( + """""", + """""", + ) + .replace( + """ +