update developer docs build config (#3493)

* update developer docs build config

- specify requirements.txt
- update site: add dark/light mode toggle
- use `com.pswidersk.python-plugin` (it's more compatible with Configuration Cache)
- define tasks for installing & building mkdocs
- log link to site using IntelliJ built-in server

* remove config-cache props

* refine mkdocs tasks, update task inputs, always log link (either using IJ or a plain file link)

* update task in GitHub Action

* add note to site_dir

* bump mkdocs-material version (prevents warning about `A plugin has set File.page to an instance of Page and it got overwritten`)

* update mkdocs site structure:

 - generate the site into `$dokkaVersion/` subdir
 - on non-SNAPSHOT versions generate a redirecting index.html

* update GHA with new MkDocs task name

* filter index.html in buildMkDocsSite task inputs

* fix Dokka version in logged link

* de-duplicate Gradle Configuration utils

.github/workflows/gh-pages-deploy-dev-docs.yml

@@ -30,7 +30,7 @@ jobs:
         run: echo "DOKKA_VERSION=`./gradlew :properties | grep '^version:.*' | cut -d ' ' -f 2`" >> $GITHUB_ENV
         working-directory: ./dokka
       - name: Build docs
-        run: ./gradlew mkdocsBuild -Pdokka_version=$DOKKA_VERSION --info
+        run: ./gradlew buildMkDocsSite -Pdokka_version=$DOKKA_VERSION --info
         working-directory: ./dokka
       - name: Deploy
         uses: peaceiris/actions-gh-pages@v3

build-logic/src/main/kotlin/dokkabuild.dev-maven-publish.gradle.kts

@@ -3,9 +3,9 @@
  */
 import dokkabuild.DevMavenPublishExtension
 import dokkabuild.DevMavenPublishExtension.Companion.DEV_MAVEN_PUBLISH_EXTENSION_NAME
-import dokkabuild.internal.consumable
-import dokkabuild.internal.declarable
-import dokkabuild.internal.resolvable
+import dokkabuild.utils.consumable
+import dokkabuild.utils.declarable
+import dokkabuild.utils.resolvable
 import org.gradle.kotlin.dsl.support.uppercaseFirstChar
 
 /**

docs-developer/README.md

@@ -1,16 +1,16 @@
 # Developer documentation
 
-This module contains developer documentation which is published to GitHub pages: 
+This module contains developer documentation which is published to GitHub pages:
 [kotlin.github.io/dokka](https://kotlin.github.io/dokka/).
 
 It is built using the [gradle-mkdocs-plugin](https://github.com/xvik/gradle-mkdocs-plugin).
 
 ## Building
 
-You can build the documentation locally:
+You can build the documentation:
 
 ```Bash
-./gradlew :docs-developer:mkdocsBuild
+./gradlew :docs-developer:mkDocsBuild
 ```
 
 The output directory is `build/mkdocs`.
@@ -23,18 +23,22 @@ Alternatively, you can use Docker:
 docker run --rm -it -p 8000:8000 -v ./docs-developer/src/doc:/docs squidfunk/mkdocs-material
 ```
 
-This will build the docs and start a web server under [localhost:8000/Kotlin/dokka](http://localhost:8000/Kotlin/dokka/).
+This will build the docs and start a web server under
+[localhost:8000/Kotlin/dokka](http://localhost:8000/Kotlin/dokka/).
 
-### Livereload server
+### Live-reload server
 
-Alternatively, you can run a livereload server that automatically rebuilds documentation on every change:
+If you are using IntelliJ then a link to the docs will be logged in the console:
 
-```Bash
-./gradlew :docs-developer:mkdocsServe
+```text
+Dokka Developer Docs: http://localhost:63342/dokka/docs-developer/build/mkdocs/index.html
 ```
 
-By default, it is run under [localhost:3001](http://localhost:3001/), but you can change it in 
-[mkdocs.yml](src/doc/mkdocs.yml) by setting the `dev_addr` option.
+To automatically rebuild the docs, run in continuous mode:
+
+```Bash
+./gradlew :docs-developer:mkDocsBuild --continuous --quiet
+```
 
 ## Publishing
 

docs-developer/build.gradle.kts

@@ -1,16 +1,179 @@
 /*
  * Copyright 2014-2024 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
  */
+import com.pswidersk.gradle.python.VenvTask
+import org.apache.tools.ant.filters.ReplaceTokens
+import org.gradle.api.tasks.PathSensitivity.RELATIVE
+import org.jetbrains.kotlin.util.parseSpaceSeparatedArgs
 
 plugins {
-    id("ru.vyarus.mkdocs") version "2.4.0"
+    id("com.pswidersk.python-plugin") version "2.4.0"
 }
 
-if (project.version.toString().endsWith("-SNAPSHOT")) {
-    // Do not generate the root index.html file with the redirect
-    // to a snapshot version, otherwise GitHub Pages-based documentation
-    // will always lead to the non-yet-released documentation.
-    // For more details, see https://github.com/Kotlin/dokka/issues/2869.
-    // For configuration details, see https://xvik.github.io/gradle-mkdocs-plugin/3.0.0/examples/#simple-multi-version.
-    mkdocs.publish.rootRedirect = false
+val dokkaVersion = provider { project.version.toString() }
+val isDokkaSnapshotVersion = dokkaVersion.map { it.endsWith("-SNAPSHOT") }
+
+/** Directory containing generated docs. */
+val currentMkDocsDir: Provider<Directory> = layout.buildDirectory.dir("mkdocs-current")
+
+/**
+ * Directory containing a fully built MkDocs site, ready for upload to GitHub Pages.
+ *
+ * The [currentMkDocsDir] must be placed in a [dokkaVersion] subdirectory.
+ *
+ * ```.
+ * └── build/
+ *     └── mkdocs/
+ *         └── 1.2.3-SNAPSHOT/
+ *             └── <content>
+ * ```
+ *
+ * If [dokkaVersion] is a release version (non-SNAPSHOT) then the dir must contain an index.html
+ * that redirects to the current version.
+ *
+ * ```
+ * └── build/
+ *     ├── mkdocs/
+ *     │   └── 1.2.3/
+ *     │       └── <content>
+ *     └── index.html (redirects to `1.2.3/index.html`)
+ * ```
+ */
+val mkDocsSiteDir: Provider<Directory> = layout.buildDirectory.dir("mkdocs")
+
+val mkDocsSetup: TaskProvider<VenvTask> by tasks.registering(VenvTask::class) {
+    description = "Install required Python libraries"
+    group = project.name
+    venvExec = "pip"
+    args = parseSpaceSeparatedArgs("install -r requirements.txt")
+
+    inputs.file("requirements.txt")
+        .withPropertyName("requirements.txt")
+        .withPathSensitivity(RELATIVE)
+        .normalizeLineEndings()
+}
+
+val pipPrintRequirements by tasks.registering(VenvTask::class) {
+    description = "Log the current requirements (useful util for manually updating dependencies & requirements.txt)"
+    group = project.name
+    venvExec = "pip"
+    args = parseSpaceSeparatedArgs("freeze")
+}
+
+val mkDocsBuild: TaskProvider<VenvTask> by tasks.registering(VenvTask::class) {
+    description = "Compile Dokka Developer Documentation site using MkDocs"
+    group = project.name
+
+    dependsOn(mkDocsSetup)
+    finalizedBy(logMkDocsLink)
+
+    venvExec = "mkdocs"
+    args = parseSpaceSeparatedArgs("build")
+
+    inputs.dir("docs")
+        .withPropertyName("docs")
+        .withPathSensitivity(RELATIVE)
+        .normalizeLineEndings()
+
+    inputs.file("mkdocs.yml")
+        .withPropertyName("mkdocs.yml")
+        .withPathSensitivity(RELATIVE)
+        .normalizeLineEndings()
+
+    // output directory is also specified in mkdocs.yml as `site_dir`
+    outputs.dir(currentMkDocsDir)
+        .withPropertyName("mkDocsOutputDir")
+
+    outputs.cacheIf("always cache - task has defined output directory") { true }
+}
+
+val generateMkDocsSiteIndexHtml by tasks.registering(Sync::class) {
+    description = "Generate the root index.html"
+    group = project.name
+
+    val dokkaVersion = dokkaVersion
+    inputs.property("dokkaVersion", dokkaVersion)
+
+    val indexHtml = layout.projectDirectory.file("index.html")
+    inputs.file(indexHtml)
+        .withPropertyName("indexHtml")
+        .withPathSensitivity(RELATIVE)
+        .normalizeLineEndings()
+
+    from(indexHtml)
+
+    filter<ReplaceTokens>("tokens" to mapOf("dokkaVersion" to dokkaVersion.get()))
+
+    into(temporaryDir)
+}
+
+
+val buildMkDocsSite by tasks.registering(Sync::class) {
+    description = "Generate a complete MkDocs site, with versioned subdirectories"
+    group = project.name
+
+    val dokkaVersion = dokkaVersion
+    inputs.property("dokkaVersion", dokkaVersion)
+
+// only generate a root index.html on non-snapshot versions
+    if (!isDokkaSnapshotVersion.get()) {
+        from(generateMkDocsSiteIndexHtml)
+    }
+    from(mkDocsBuild) {
+        eachFile {
+            relativePath = relativePath.prepend(dokkaVersion.get())
+        }
+    }
+
+    includeEmptyDirs = false
+
+    into(mkDocsSiteDir)
+}
+
+val logMkDocsLink: TaskProvider<Task> by tasks.registering {
+    description = "Prints a link to the generated docs"
+    group = project.name
+
+    dependsOn(buildMkDocsSite)
+    doNotTrackState("this task performs no work and should always log the link")
+
+    // redefine currentMkDocsDir for config-cache compliance
+    val mkDocsDir = buildMkDocsSite.map { it.destinationDir }
+
+    val ideaActive = System.getProperty("idea.active").toBoolean()
+
+    val dokkaProjectDir = project.rootDir.parentFile
+
+    val dokkaVersion = dokkaVersion
+    val isDokkaSnapshotVersion = isDokkaSnapshotVersion
+
+    doLast {
+        val indexHtml = if (isDokkaSnapshotVersion.get()) {
+            mkDocsDir.get().resolve("${dokkaVersion.get()}/index.html")
+        } else {
+            mkDocsDir.get().resolve("index.html")
+        }
+
+        val link: String =
+            if (ideaActive) {
+                // The built-in IntelliJ server requires a specific path to index.html:
+                // a _relative_ path starting with the project's directory (dokka)
+                val relativeOutputPath = indexHtml.relativeTo(dokkaProjectDir).invariantSeparatorsPath
+                "http://localhost:63342/$relativeOutputPath"
+            } else {
+                indexHtml.toURI().toString()
+            }
+
+        logger.quiet(
+            """
+            |
+            |***************************************************************************************************
+            |    
+            |    Dokka Developer Docs: $link
+            |
+            |***************************************************************************************************
+            |
+            """.trimMargin()
+        )
+    }
 }

docs-developer/index.html

@@ -0,0 +1,8 @@
+<html xmlns="http://www.w3.org/1999/xhtml" lang="en">
+<head>
+    <meta http-equiv="refresh" content="0; url='./@dokkaVersion@/'"/>
+    <title>Dokka Developer Docs</title>
+</head>
+<body>
+</body>
+</html>

docs-developer/src/doc/mkdocs.yml → docs-developer/mkdocs.yml

@@ -1,5 +1,8 @@
 site_name: Dokka
 
+# note that site_dir is also specified in the Gradle task mkDocsBuild
+site_dir: "build/mkdocs-current"
+
 # Meta tags (placed in header)
 site_description: Dokka is an API documentation engine for Kotlin, performing the same function as the Javadoc tool for Java
 site_author: JetBrains
@@ -26,6 +29,21 @@ theme:
     - navigation.instant
     - navigation.indexes
     - navigation.top
+  palette:
+    - media: "(prefers-color-scheme)"
+      toggle:
+        icon: material/brightness-auto
+        name: Switch to light mode
+    - media: "(prefers-color-scheme: light)"
+      scheme: default
+      toggle:
+        icon: material/brightness-7
+        name: Switch to dark mode
+    - media: "(prefers-color-scheme: dark)"
+      scheme: slate
+      toggle:
+        icon: material/brightness-4
+        name: Switch to system preference
 
 # Extensions
 markdown_extensions:

docs-developer/requirements.txt

@@ -0,0 +1,28 @@
+Babel==2.14.0
+certifi==2024.2.2
+charset-normalizer==3.3.2
+click==8.1.7
+colorama==0.4.6
+ghp-import==2.1.0
+idna==3.6
+Jinja2==3.1.3
+Markdown==3.5.2
+MarkupSafe==2.1.5
+mergedeep==1.3.4
+mkdocs==1.5.3
+mkdocs-material==9.5.10
+mkdocs-material-extensions==1.3.1
+packaging==23.2
+paginate==0.5.6
+pathspec==0.12.1
+platformdirs==4.2.0
+Pygments==2.17.2
+pymdown-extensions==10.7
+python-dateutil==2.8.2
+PyYAML==6.0.1
+pyyaml_env_tag==0.1
+regex==2023.12.25
+requests==2.31.0
+six==1.16.0
+urllib3==2.2.0
+watchdog==4.0.0