Get rid of gh-pages branch

.github/workflows/docs-ci.yml

@@ -1,25 +1,49 @@
-# This workflow will build and deploy docs to GitHub Pages whenever something is pushed to the default branch
+name: Build docs
 
-name: Docs
-
-on: push # but only to default branch, see if below
+on:
+  push:
+  release:
+    types:
+      - published
+  workflow_dispatch:
 
+# Gives the workflow permissions to clone the repo and create a page deployment
 permissions:
-  contents: write
+  id-token: write
+  pages: write
 
-jobs:
-  docs:
-    name: Build and deploy docs
-    runs-on: ubuntu-latest
-    if: github.ref == format('refs/heads/{0}', github.event.repository.default_branch)
-    concurrency: # Allow one concurrent deployment
+# Allow one concurrent deployment
+concurrency:
       group: pages
       cancel-in-progress: true
+
+# This workflow updates the versioned docs on dokka.kord.dev using the following strategy
+# 1) pull cache to docs-cache
+# 2) Call dokkaHtmlMultiModule for current version
+#   - if this is a release build move current docs into docs-cache/$version
+#   - otherwise move it into docs-cache/current
+# 3) Build GitHub Pages artifact
+#   - Move all folders not named "current" into docs/<folder>
+#   - Move current into docs/
+# 4) Trigger a deployment to GitHub Actions
+jobs:
+  build-job:
+    if: github.ref == format('refs/heads/{0}', github.event.repository.default_branch)
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
     env:
       GITHUB_TAG_NAME: ${{ github.event.release.tag_name }}
       GITHUB_BRANCH_NAME: ${{ github.ref }}
     steps:
-      - uses: actions/checkout@v3
+      - name: Checkout repository
+        uses: actions/checkout@v3
+      - name: Checkout cache
+        with:
+          ref: 'docs-cache'
+          path: 'docs-cache'
+        uses: actions/checkout@v3
       - name: Set up JDK
         uses: actions/setup-java@v3
         with:
@@ -28,12 +52,25 @@ jobs:
       - name: Build docs with Gradle
         uses: gradle/gradle-build-action@v2
         with:
-          arguments: --stacktrace --info dokkaHtmlMultiModule
-      - name: Deploy docs to GitHub Pages
-        uses: JamesIves/github-pages-deploy-action@v4
+          arguments: :produceDocs
+      - name: Commit files
+        working-directory: docs-cache
+        run: |
+          git config --local user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git config --local user.name "github-actions[bot]"
+          git commit -a -m "Add changes"
+      - name: Push changes
+        uses: ad-m/github-push-action@master
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          branch: docs-cache
+          directory: docs-cache
+      - name: Setup Pages
+        uses: actions/configure-pages@v2
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v1
         with:
-          folder: build/dokka/htmlMultiModule
-          branch: gh-pages
-          git-config-name: GitHub Actions
-          git-config-email: [email protected]
-          commit-message: Update docs
+          path: docs
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v1

.gitignore

@@ -3,6 +3,10 @@
 .idea/
 out/
 
+# Versioned docs structure
+docs/
+old-docs/
+
 **/build/*
 !**/build/generated/
 # re-exclude BuildConfigGenerated.kt

build.gradle.kts

@@ -8,3 +8,46 @@ repositories {
 
 group = Library.group
 version = Library.version
+
+dependencies {
+    dokkaHtmlMultiModulePlugin(libs.dokka.versioning.plugin)
+}
+
+tasks {
+    val oldDocsRoot = "docs-cache"
+    dokkaHtmlMultiModule {
+        applyVersioningPlugin()
+    }
+
+    val saveDocs = task<Copy>("saveVersionedDocs") {
+        fromDokkaMutliModule()
+        if (Library.isSnapshot) {
+            into("$oldDocsRoot/current")
+        } else {
+            into("$oldDocsRoot/${Library.version}")
+        }
+    }
+
+    task<Copy>("produceDocs") {
+        dependsOn(saveDocs)
+        // copy old versions
+        from(oldDocsRoot) {
+            exclude("current")
+        }
+        // copy up to date version
+        fromDokkaMutliModule {
+            if (Library.isRelease) {
+                into(Library.version)
+            }
+        }
+        into("docs")
+    }
+}
+
+// For some reason from(dokkaHtmlMultiModule) produces some really weird output
+inline fun Copy.fromDokkaMutliModule(crossinline configure: CopySpec.() -> Unit = {}) {
+    from("$buildDir/dokka/htmlMultiModule") {
+        configure()
+    }
+    dependsOn(tasks.dokkaHtmlMultiModule)
+}

buildSrc/build.gradle.kts

@@ -8,4 +8,5 @@ repositories {
 
 dependencies {
     implementation(libs.bundles.pluginsForBuildSrc)
+    implementation(libs.dokka.versioning.plugin)
 }

buildSrc/src/main/kotlin/Compiler.kt

@@ -1,5 +1,6 @@
 import kotlinx.atomicfu.plugin.gradle.AtomicFUPluginExtension
 import org.gradle.api.Project
+import org.gradle.api.artifacts.VersionCatalog
 import org.gradle.api.artifacts.VersionCatalogsExtension
 import org.gradle.kotlin.dsl.assign
 import org.gradle.kotlin.dsl.configure
@@ -41,7 +42,9 @@ fun KotlinSourceSet.applyKordOptIns() {
 fun Project.configureAtomicFU() {
     // https://github.com/Kotlin/kotlinx-atomicfu/issues/210
     configure<AtomicFUPluginExtension> {
-        val libs = extensions.getByType<VersionCatalogsExtension>().named("libs")
         dependenciesVersion = libs.findVersion("kotlinx-atomicfu").get().requiredVersion
     }
 }
+
+internal val Project.libs: VersionCatalog
+    get() = extensions.getByType<VersionCatalogsExtension>().named("libs")

buildSrc/src/main/kotlin/Documentation.kt

@@ -1,22 +1,25 @@
+import org.gradle.api.Project
 import org.gradle.kotlin.dsl.assign
 import org.jetbrains.dokka.gradle.AbstractDokkaLeafTask
+import org.jetbrains.dokka.gradle.AbstractDokkaTask
+import org.jetbrains.dokka.versioning.VersioningConfiguration
+import org.jetbrains.dokka.versioning.VersioningPlugin
+import java.io.FileFilter
 import java.net.URL
 
 fun AbstractDokkaLeafTask.applyKordDokkaOptions() {
-
     moduleName = "kord-${project.name}"
 
     failOnWarning = true
-
     dokkaSourceSets.configureEach {
-
         jdkVersion = Jvm.target
 
         suppressGeneratedFiles = false
 
         sourceLink {
             localDirectory = project.projectDir
-            remoteUrl = URL("https://github.com/kordlib/kord/blob/${Library.commitHashOrDefault("0.9.x")}/${project.name}")
+            remoteUrl =
+                URL("https://github.com/kordlib/kord/blob/${Library.commitHashOrDefault("0.9.x")}/${project.name}")
             remoteLineSuffix = "#L"
         }
 
@@ -34,4 +37,16 @@ fun AbstractDokkaLeafTask.applyKordDokkaOptions() {
             suppress = true
         }
     }
+    applyVersioningPlugin()
 }
+
+fun AbstractDokkaTask.applyVersioningPlugin() {
+    pluginConfiguration<VersioningPlugin, VersioningConfiguration> {
+        olderVersions = project.rootProject
+            .file("docs-cache").listFiles(FileFilter { it.isDirectory })?.toList() ?: emptyList()
+        renderVersionsNavigationOnAllPages = true
+    }
+}
+
+val Project.dokkaVersioningPlugin
+    get() = project.libs.findLibrary("dokka-versioning-plugin").get()

buildSrc/src/main/kotlin/kord-module.gradle.kts

@@ -17,6 +17,7 @@ repositories {
 
 dependencies {
     ksp(project(":ksp-processors"))
+    "dokkaHtmlPartialPlugin"(dokkaVersioningPlugin)
 }
 
 apiValidation {

buildSrc/src/main/kotlin/kord-multiplatform-module.gradle.kts

@@ -1,4 +1,5 @@
 import org.jetbrains.dokka.gradle.AbstractDokkaLeafTask
+import org.jetbrains.dokka.gradle.DokkaTask
 import org.jetbrains.kotlin.gradle.targets.js.testing.KotlinJsTest
 
 plugins {
@@ -16,6 +17,7 @@ repositories {
 
 dependencies {
     kspCommonMainMetadata(project(":ksp-processors"))
+    "dokkaHtmlPartialPlugin"(dokkaVersioningPlugin)
 }
 
 apiValidation {

gradle/libs.versions.toml

@@ -54,6 +54,7 @@ kotlinx-coroutines-test = { module = "org.jetbrains.kotlinx:kotlinx-coroutines-t
 kotlinx-serialization-json = { module = "org.jetbrains.kotlinx:kotlinx-serialization-json", version.ref = "kotlinx-serialization" }
 kotlinx-datetime = { module = "org.jetbrains.kotlinx:kotlinx-datetime", version.ref = "kotlinx-datetime" }
 kotlinx-nodejs = { module = "org.jetbrains.kotlin-wrappers:kotlin-node", version.ref = "kotlinx-nodejs" }
+dokka-versioning-plugin = { module = "org.jetbrains.dokka:versioning-plugin", version.ref = "dokka" }
 
 # other
 kotlin-logging = { module = "io.github.microutils:kotlin-logging", version.ref = "kotlin-logging" }