Documentation site

.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
+site/**         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,23 +1,66 @@
+pluginManagement {
+  repositories {
+    gradlePluginPortal()
+    mavenCentral()
+  }
+}
+
 @Suppress("UnstableApiUsage") // Central declaration of repositories is an incubating feature
 dependencyResolutionManagement {
 
   repositories {
     mavenCentral()
     gradlePluginPortal()
-    jitpack()
-  }
+    jetBrainsCompose()
+    jetBrainsKotlinxHtml()
 
-  pluginManagement {
-    repositories {
-      gradlePluginPortal()
-      mavenCentral()
-      jitpack()
+    // Declare the Node.js & Yarn download repositories
+    exclusiveContent {
+      forRepository {
+        ivy("https://nodejs.org/dist/") {
+          name = "Node Distributions at $url"
+          patternLayout { artifact("v[revision]/[artifact](-v[revision]-[classifier]).[ext]") }
+          metadataSources { artifact() }
+          content { includeModule("org.nodejs", "node") }
+        }
+      }
+      filter { includeGroup("org.nodejs") }
     }
-  }
 
+    exclusiveContent {
+      forRepository {
+        ivy("https://github.com/yarnpkg/yarn/releases/download") {
+          name = "Yarn Distributions at $url"
+          patternLayout { artifact("v[revision]/[artifact](-v[revision]).[ext]") }
+          metadataSources { artifact() }
+          content { includeModule("com.yarnpkg", "yarn") }
+        }
+      }
+      filter { includeGroup("com.yarnpkg") }
+    }
+  }
 }
 
 
 fun RepositoryHandler.jitpack() {
   maven("https://jitpack.io")
 }
+
+fun RepositoryHandler.jetBrainsCompose() {
+  maven("https://maven.pkg.jetbrains.space/public/p/compose/dev") {
+    mavenContent {
+      includeGroupByRegex("""androidx\..+""")
+      includeGroupByRegex("""org\.jetbrains\..+""")
+      includeGroup("web")
+      includeGroup("com.theapache64.composebird")
+    }
+  }
+}
+
+fun RepositoryHandler.jetBrainsKotlinxHtml() {
+  maven("https://maven.pkg.jetbrains.space/public/p/kotlinx-html/maven") {
+    mavenContent {
+      includeGroup("org.jetbrains.kotlinx")
+    }
+  }
+}

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

@@ -23,18 +23,18 @@ tasks.withType<Test>().configureEach {
 
   testLogging {
     // don't log console output - it's too noisy
-    showCauses = false
-    showExceptions = false
-    showStackTraces = false
-    showStandardStreams = false
+    showCauses = true
+    showExceptions = true
+    showStackTraces = true
+    showStandardStreams = true
     events(
       // only log test outcomes
       TestLogEvent.PASSED,
       TestLogEvent.FAILED,
       TestLogEvent.SKIPPED,
-      // TestLogEvent.STARTED,
-      // TestLogEvent.STANDARD_ERROR,
-      // TestLogEvent.STANDARD_OUT,
+      TestLogEvent.STARTED,
+      TestLogEvent.STANDARD_ERROR,
+      TestLogEvent.STANDARD_OUT,
     )
   }
 }

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,37 @@
+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 {
+  dokkatooPublications.configureEach {
+    pluginsConfiguration.create("org.jetbrains.dokka.base.DokkaBase") {
+      serializationFormat.set(org.jetbrains.dokka.DokkaConfiguration.SerializationFormat.JSON)
+      values.set(
+        """
+          { 
+            "customStyleSheets": [
+              "${file("./media/styles/logo-styles.css").invariantSeparatorsPath}" 
+            ], 
+            "customAssets": [
+              "${file("./media/images/logo-icon.svg").invariantSeparatorsPath}"
+            ] 
+          }
+        """.trimIndent()
+      )
+    }
+  }
+}
+
+tasks.dokkatooGeneratePublicationHtml {
+  inputs.dir("media/styles/")
+  inputs.dir("media/images/")
+}