implement Dokkatoo docs (#30)

.gitattributes

@@ -16,3 +16,6 @@ text eol=lf
 # (binary is a macro for -text -diff)
 *.jar           binary
 *.war           binary
+
+# https://github.com/github/linguist/blob/v7.24.1/docs/overrides.md
+docs/**         linguist-documentation

.github/workflows/deploy-site.yml

@@ -0,0 +1,51 @@
+name: Deploy Site
+
+on:
+  workflow_dispatch:
+  push:
+    tags:
+      - "v[0-9]+.[0-9]+.[0-9]+"
+
+
+concurrency:
+  group: "${{ github.workflow }} @ ${{ github.event.pull_request.head.label || github.head_ref || github.ref }}"
+  cancel-in-progress: true
+
+
+jobs:
+
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout the repo
+        uses: actions/checkout@v3
+
+      - name: Setup JDK
+        uses: actions/setup-java@v3
+        with:
+          distribution: temurin
+          java-version: 11
+
+      - uses: gradle/gradle-build-action@v2
+        with:
+          gradle-home-cache-cleanup: true
+          arguments: |
+            :docs:dokkatooGenerate
+
+      - uses: actions/upload-pages-artifact@v1
+        with:
+          path: ./docs/build/dokka/html
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      pages: write      # to deploy to Pages
+      id-token: write   # to verify the deployment originates from an appropriate source
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v1

build.gradle.kts

@@ -1,14 +1,12 @@
 import buildsrc.ext.excludeGeneratedGradleDsl
+import buildsrc.ext.initIdeProjectLogo
 
 plugins {
   buildsrc.convention.`kotlin-jvm`
-
   buildsrc.convention.`maven-publish`
   me.qoomon.`git-versioning`
-
   `project-report`
   // `build-dashboard` // incompatible with Gradle CC
-
   idea
 }
 
@@ -19,7 +17,6 @@ gitVersioning.apply {
     branch(".+") { version = "\${ref}-SNAPSHOT" }
     tag("v(?<version>.*)") { version = "\${ref.version}" }
   }
-
   // optional fallback configuration in case of no matching ref configuration
   rev { version = "\${commit}" }
 }
@@ -39,13 +36,6 @@ kotkaPublishing {
   mavenPomDescription.set("Using Kotka means a more pleasant experience while using Kafka Streams")
 }
 
-
-tasks.wrapper {
-  gradleVersion = "7.6"
-  distributionType = Wrapper.DistributionType.ALL
-}
-
-
 idea {
   module {
     isDownloadSources = true
@@ -56,3 +46,5 @@ idea {
     )
   }
 }
+
+initIdeProjectLogo("site/src/jsMain/resources/ks-logo.svg")

buildSrc/build.gradle.kts

@@ -2,15 +2,19 @@ import org.jetbrains.kotlin.gradle.tasks.KotlinCompile
 
 plugins {
   `kotlin-dsl`
-  kotlin("jvm") version embeddedKotlinVersion
 }
 
 dependencies {
   implementation(libs.gradlePlugin.kotlin)
   implementation(libs.gradlePlugin.kotlinxSerialization)
 
   implementation(libs.gradlePlugin.gitVersioning)
-  // implementation(libs.gradlePlugin.dokka) // incompatible with Gradle CC
+
+  implementation(libs.kotlin.dokkaCore)
+  implementation(libs.gradlePlugin.dokkatoo)
+
+  // https://github.com/gradle/gradle/issues/15383#issuecomment-779893192
+  implementation(files(libs.javaClass.superclass.protectionDomain.codeSource.location))
 }
 
 val gradleJvmTarget = "11"

buildSrc/repositories.settings.gradle.kts

@@ -1,20 +1,17 @@
+pluginManagement {
+  repositories {
+    gradlePluginPortal()
+    mavenCentral()
+  }
+}
+
 @Suppress("UnstableApiUsage") // Central declaration of repositories is an incubating feature
 dependencyResolutionManagement {
 
   repositories {
     mavenCentral()
     gradlePluginPortal()
-    jitpack()
-  }
-
-  pluginManagement {
-    repositories {
-      gradlePluginPortal()
-      mavenCentral()
-      jitpack()
-    }
   }
-
 }
 
 

buildSrc/src/main/kotlin/buildsrc/convention/dokkatoo.gradle.kts

@@ -0,0 +1,54 @@
+package buildsrc.convention
+
+import buildsrc.ext.libs
+
+plugins {
+  id("buildsrc.convention.base")
+  id("dev.adamko.dokkatoo-html")
+}
+
+val kafkaJavadocUrl = libs.versions.kafka.map { v ->
+  val (major, minor) = v.split(".")
+  "https://kafka.apache.org/${major}${minor}/javadoc/"
+}
+
+dokkatoo {
+  dokkatooSourceSets.configureEach {
+    externalDocumentationLinks.create("kafka-streams") {
+      enabled.set(true)
+      url(kafkaJavadocUrl)
+    }
+  }
+}
+
+tasks.dokkatooGeneratePublicationHtml {
+  doLast {
+    outputDirectory.get().asFile.walk()
+      .filter { it.isFile && it.extension == "html" }
+      .forEach { file ->
+        file.writeText(
+          file.readText()
+            .replace(
+              """<html>""",
+              """<html lang="en">""",
+            )
+            .replace(
+              """
+                <button id="theme-toggle-button">
+              """.trimIndent(),
+              """
+                <div id="github-link"><a href="https://github.com/adamko-dev/kotka-streams/"></a></div>
+                <button id="theme-toggle-button">
+              """.trimIndent(),
+            ).replace(
+              """
+                href="https://github.com/Kotlin/dokka"><span>dokka</span>
+              """.trimIndent(),
+              """
+                href="https://github.com/adamko-dev/dokkatoo/"><span>Dokkatoo</span>
+              """.trimIndent(),
+            )
+        )
+      }
+  }
+}

buildSrc/src/main/kotlin/buildsrc/ext/gradle.kt

@@ -1,10 +1,14 @@
 package buildsrc.ext
 
+import org.gradle.accessors.dm.LibrariesForLibs
 import org.gradle.api.Action
+import org.gradle.api.Project
 import org.gradle.api.artifacts.repositories.PasswordCredentials
 import org.gradle.api.file.ProjectLayout
+import org.gradle.api.file.RegularFile
 import org.gradle.api.provider.Provider
 import org.gradle.api.provider.ProviderFactory
+import org.gradle.kotlin.dsl.*
 import org.gradle.plugins.ide.idea.model.IdeaModule
 
 
@@ -39,3 +43,35 @@ fun IdeaModule.excludeGeneratedGradleDsl(layout: ProjectLayout) {
       }
   )
 }
+
+
+/**
+ * Sets a logo for project IDEs
+ * @param[logoPath] Location of logo file. Evaluated as per [Project.file].
+ */
+fun Project.initIdeProjectLogo(
+  logoSvgPath: String,
+) {
+  val logoSvg: RegularFile = rootProject.layout.projectDirectory.file(logoSvgPath)
+  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)
+    }
+  }
+}
+
+/**
+ * Access the version catalog.
+ *
+ * https://github.com/gradle/gradle/issues/15383#issuecomment-779893192
+ */
+val Project.libs: LibrariesForLibs
+  get() = this.extensions.getByType()

docs/build.gradle.kts

@@ -0,0 +1,39 @@
+plugins {
+  buildsrc.convention.dokkatoo
+}
+
+dependencies {
+  dokkatoo(projects.modules.kotkaStreamsExtensions)
+  dokkatoo(projects.modules.kotkaStreamsFramework)
+  dokkatoo(projects.modules.kotkaStreamsKotlinxSerialization)
+
+  dokkatooPluginHtml(libs.kotlin.dokkaPlugin.allModulesPage)
+  dokkatooPluginHtml(libs.kotlin.dokkaPlugin.templating)
+}
+
+dokkatoo {
+  moduleName.set("Kotka Streams")
+
+  dokkatooPublications.configureEach {
+    pluginsConfiguration.create("org.jetbrains.dokka.base.DokkaBase") {
+      serializationFormat.set(org.jetbrains.dokka.DokkaConfiguration.SerializationFormat.JSON)
+      values.set(
+        """
+          { 
+            "customStyleSheets": [
+              "${file("./styles/logo-styles.css").invariantSeparatorsPath}" 
+            ], 
+            "customAssets": [
+              "${file("./images/logo-icon.svg").invariantSeparatorsPath}"
+            ] 
+          }
+        """.trimIndent()
+      )
+    }
+  }
+}
+
+tasks.dokkatooGeneratePublicationHtml {
+  inputs.dir("styles/")
+  inputs.dir("images/")
+}

docs/styles/logo-styles.css

@@ -0,0 +1,44 @@
+.library-name a {
+  position: center;
+  display: flex;
+  margin-left: 0.2em;
+  margin-right: 0.2em;
+  align-items: center;
+  justify-content: center;
+}
+
+.library-name a::before {
+  content: "";
+  background-image: url('../images/logo-icon.svg');
+  background-repeat: no-repeat;
+  background-size: 100% 100%;
+  position: center;
+  display: flex;
+  width: 3.5em;
+  height: 3.5em;
+  margin-right: 1em;
+}
+
+.navigation-wrapper {
+  padding-top: 0.5em;
+  padding-bottom: 0.5em;
+}
+
+div#github-link {
+  width: 36px;
+  height: 36px;
+  display: inline-flex;
+  border-radius: 24px;
+  align-items: center;
+  justify-content: center;
+  border: none;
+}
+
+div#github-link a {
+  background-image: url("data:image/svg+xml;utf8,<svg xmlns='http://www.w3.org/2000/svg' width='16' height='16' fill='white' class='bi bi-github' viewBox='0 0 16 16'><path d='M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.012 8.012 0 0 0 16 8c0-4.42-3.58-8-8-8z'/></svg>");
+  width: 24px;
+  height: 24px;
+  border-radius: 24px;
+  background-size: 100% 100%;
+  margin-left: 16px;
+}

gradle.properties

@@ -1,4 +1,4 @@
-org.gradle.jvmargs=-XX:MaxMetaspaceSize=1g -Dfile.encoding=UTF-8
+org.gradle.jvmargs=-Dfile.encoding=UTF-8 -Xmx2g
 
 org.gradle.parallel=true
 org.gradle.caching=true