Site (#51)

* create logo & banner

* bump gradle

* adjust libs / buildSrc after Gradle bump

* a bit of docs refactoring

* bump kotlin

* a bit of docs refactoring

* more docs refactoring (prepping for sites)

* bump gradleNodePlugin

* rename 'subproject' convention plugin to 'base'

* update EmptySerializersModule -> EmptySerializersModule()

* create conventions/configurations/tasks for sharing Knit md files

* create site with Docusaurus

* new GHA to deploy the site

* rm GitHub pages plugin

* create text-less icon

* reduce/amend log output in GHA and tests

* fix serializer import in test

* remove docusaurusBuild from build task

* random yarn.lock update

* always enable TS Compile tests in GHA (so the Actions run faster)

Author: aSemy

.github/workflows/deploy-site.yml

@@ -0,0 +1,53 @@
+name: Deploy Site
+
+on:
+  workflow_dispatch:
+  workflow_call:
+  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
+
+      - name: Run :site:build
+        run: ./gradlew :site:build
+
+      - uses: actions/upload-pages-artifact@v1
+        with:
+          path: $GITHUB_WORKSPACE/site/build
+
+  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

.github/workflows/tests.yml

@@ -21,10 +21,9 @@ jobs:
     strategy:
       matrix:
         os: [ ubuntu-latest, macos-11, windows-latest ]
-        tsCompileTests: [ true, false ]
       fail-fast: false
     uses: ./.github/workflows/gradle_task.yml
     with:
       runs-on: ${{ matrix.os }}
       gradle-task: >-
-        check -Pkxstsgen_enableTsCompileTests=${{ matrix.tsCompileTests }} --info --stacktrace
+        check -Pkxstsgen_enableTsCompileTests=true --stacktrace

build.gradle.kts

@@ -4,6 +4,7 @@ plugins {
   idea
   id("me.qoomon.git-versioning")
   id("org.jetbrains.kotlinx.kover")
+  buildsrc.convention.base
 }
 
 
@@ -22,8 +23,8 @@ gitVersioning.apply {
 
 
 tasks.wrapper {
-  gradleVersion = "7.5.1"
-  distributionType = Wrapper.DistributionType.ALL
+  gradleVersion = "7.6"
+  distributionType = Wrapper.DistributionType.BIN
 }
 
 
@@ -36,6 +37,7 @@ idea {
       ".idea",
       "gradle/kotlin-js-store",
       "gradle/wrapper",
+      "site/.docusaurus",
     )
   }
 }

buildSrc/build.gradle.kts

@@ -1,34 +1,28 @@
 import org.jetbrains.kotlin.gradle.tasks.KotlinCompile
 
 plugins {
-  idea
   `kotlin-dsl`
-  kotlin("jvm") version embeddedKotlinVersion
 }
 
 
 dependencies {
-  implementation(enforcedPlatform(libs.kotlin.bom))
-  implementation("org.jetbrains.kotlin:kotlin-serialization")
-//  implementation("org.jetbrains.kotlin:kotlin-reflect")
-
-  implementation(libs.kotlin.gradlePlugin)
-  implementation(libs.kotlinSymbolProcessing.gradlePlugin)
-
-  implementation(libs.kotest.gradlePlugin)
-
-  implementation(libs.kotlinx.kover.gradlePlugin)
-
-  implementation(libs.kotlinx.knit.gradlePlugin)
-
-  implementation(libs.gradleNodePlugin)
-
-  implementation(libs.gitVersioningPlugin)
+  implementation(platform(libs.kotlin.bom))
+
+  implementation(libs.gradlePlugin.kotlin)
+  implementation(libs.gradlePlugin.kotlinSerialization)
+  implementation(libs.gradlePlugin.gitVersioning)
+  implementation(libs.gradlePlugin.gradleNode)
+  implementation(libs.gradlePlugin.kotlinxKover)
+  implementation(libs.gradlePlugin.kotlinxKnit)
+  implementation(libs.gradlePlugin.kotest)
+  implementation(libs.gradlePlugin.kotlinSymbolProcessing)
+
+  implementation("org.jetbrains:markdown:0.3.5")
+  implementation("org.jetbrains.kotlinx:kotlinx-html:0.8.0")
 }
 
 
 tasks.withType<KotlinCompile>().configureEach {
-
   kotlinOptions {
     jvmTarget = libs.versions.jvmTarget.get()
     apiVersion = libs.versions.kotlinTarget.get()
@@ -42,25 +36,17 @@ tasks.withType<KotlinCompile>().configureEach {
   )
 }
 
+
 kotlin {
   jvmToolchain {
-    (this as JavaToolchainSpec).languageVersion.set(
+    languageVersion.set(
       libs.versions.jvmTarget.map {
-        JavaLanguageVersion.of(
-          it.substringAfter(".")
-        )
+        JavaLanguageVersion.of(it)
       }
     )
   }
-
-  kotlinDslPluginOptions {
-    jvmTarget.set(libs.versions.jvmTarget)
-  }
 }
 
-idea {
-  module {
-    isDownloadSources = true
-    isDownloadJavadoc = true
-  }
+kotlinDslPluginOptions {
+  jvmTarget.set(libs.versions.jvmTarget)
 }

buildSrc/src/main/kotlin/buildsrc/config/distributions.kt

@@ -0,0 +1,29 @@
+package buildsrc.config
+
+import org.gradle.api.artifacts.Configuration
+import org.gradle.api.attributes.AttributeContainer
+import org.gradle.api.attributes.Usage.USAGE_ATTRIBUTE
+import org.gradle.api.model.ObjectFactory
+import org.gradle.kotlin.dsl.named
+
+/** Mark this [Configuration] as one that will be consumed by other subprojects. */
+fun Configuration.asProvider(
+  visible: Boolean = false
+) {
+  isVisible = visible
+  isCanBeResolved = false
+  isCanBeConsumed = true
+}
+
+/** Mark this [Configuration] as one that will consume (also known as 'resolving') artifacts from other subprojects */
+fun Configuration.asConsumer(
+  visible: Boolean = false
+) {
+  isVisible = visible
+  isCanBeResolved = true
+  isCanBeConsumed = false
+}
+
+
+fun AttributeContainer.knitDocsAttributes(objects: ObjectFactory): AttributeContainer =
+  attribute(USAGE_ATTRIBUTE, objects.named("kxs-ts-gen.knit-docs"))

buildSrc/src/main/kotlin/buildsrc/config/kmm.kt

@@ -14,13 +14,11 @@ import org.jetbrains.kotlin.gradle.targets.js.yarn.YarnRootExtension
  * gradle dir, next to the version-catalog.
  */
 fun Project.relocateKotlinJsStore() {
-
   afterEvaluate {
     rootProject.extensions.findByType<YarnRootExtension>()?.apply {
       lockFileDirectory = project.rootDir.resolve("gradle/kotlin-js-store")
     }
   }
-
 }
 
 

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

@@ -0,0 +1,37 @@
+package buildsrc.convention
+
+import buildsrc.config.KxsTsGenBuildSettings
+import java.time.Duration
+import org.gradle.api.tasks.testing.logging.TestLogEvent
+
+plugins {
+  base
+}
+
+if (project != rootProject) {
+  project.group = rootProject.group
+  project.version = rootProject.version
+}
+
+extensions.create<KxsTsGenBuildSettings>(KxsTsGenBuildSettings.NAME)
+
+tasks.withType<Test>().configureEach {
+  timeout.set(Duration.ofMinutes(10))
+
+  testLogging {
+    // don't log console output - it's too noisy
+    showCauses = false
+    showExceptions = false
+    showStackTraces = false
+    showStandardStreams = false
+    events(
+      // only log test outcomes
+      TestLogEvent.PASSED,
+      TestLogEvent.FAILED,
+      TestLogEvent.SKIPPED,
+      // TestLogEvent.STARTED,
+      // TestLogEvent.STANDARD_ERROR,
+      // TestLogEvent.STANDARD_OUT,
+    )
+  }
+}

buildSrc/src/main/kotlin/buildsrc/convention/knit-files.gradle.kts

@@ -0,0 +1,22 @@
+package buildsrc.convention
+
+import buildsrc.config.asConsumer
+import buildsrc.config.asProvider
+import buildsrc.config.knitDocsAttributes
+import org.gradle.kotlin.dsl.getValue
+import org.gradle.kotlin.dsl.provideDelegate
+import org.gradle.kotlin.dsl.registering
+
+plugins {
+  id("buildsrc.convention.base")
+}
+
+val knitDocsElements by configurations.registering {
+  asProvider()
+  attributes { knitDocsAttributes(objects) }
+}
+
+val knitDocs by configurations.registering {
+  asConsumer()
+  attributes { knitDocsAttributes(objects) }
+}

buildSrc/src/main/kotlin/buildsrc/convention/knit-tests.gradle.kts

@@ -0,0 +1,16 @@
+package buildsrc.convention
+
+import buildsrc.config.knitDocsAttributes
+import buildsrc.config.asConsumer
+import org.gradle.kotlin.dsl.withType
+import org.jetbrains.kotlin.gradle.tasks.KotlinCompile
+
+plugins {
+  id("buildsrc.convention.base")
+  id("buildsrc.convention.knit-files")
+  id("org.jetbrains.kotlinx.knit")
+}
+
+tasks.withType<KotlinCompile>().configureEach {
+  mustRunAfter(tasks.knit)
+}

buildSrc/src/main/kotlin/buildsrc/convention/kotlin-jvm.gradle.kts

@@ -7,7 +7,7 @@ import org.gradle.kotlin.dsl.withType
 import org.jetbrains.kotlin.gradle.tasks.KotlinCompile
 
 plugins {
-  id("buildsrc.convention.subproject")
+  id("buildsrc.convention.base")
   kotlin("jvm")
   `java-library`
 }

buildSrc/src/main/kotlin/buildsrc/convention/kotlin-mpp.gradle.kts

@@ -7,7 +7,7 @@ import org.jetbrains.kotlin.gradle.targets.jvm.KotlinJvmTarget
 
 
 plugins {
-  id("buildsrc.convention.subproject")
+  id("buildsrc.convention.base")
   kotlin("multiplatform")
 }
 

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

@@ -2,7 +2,7 @@ package buildsrc.convention
 
 plugins {
   id("com.github.node-gradle.node")
-  id("buildsrc.convention.subproject")
+  id("buildsrc.convention.base")
 }
 
 val rootGradleDir: Directory by extra {

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

@@ -0,0 +1,7 @@
+import com.github.gradle.node.npm.task.NpmTask
+import org.gradle.api.provider.ListProperty
+import org.jetbrains.kotlin.util.parseSpaceSeparatedArgs
+
+fun NpmTask.args(values: String) {
+  args.set(parseSpaceSeparatedArgs(values))
+}