test: automation script for local Dokka testing (#3432)

* test: added script for faster dokka testing

* docs: added readme for testDokka.sh

* test: improved testDokka.sh after review

* test: made testDokka start server event with option set -e

* test: support multimodule projects

* test: add docs

* test: move testDokka to /scripts dir

CONTRIBUTING.md

@@ -76,6 +76,8 @@ plugins {
 }
 ```
 
+There is an automation script for this routine, see [testDokka.sh.md](scripts/testDokka.sh.md) for details.
+
 ### Updating public API dump
 
 [Binary Compatibility Validator](https://github.com/Kotlin/binary-compatibility-validator/blob/master/README.md) 

scripts/testDokka.sh

@@ -0,0 +1,113 @@
+#!/bin/bash
+#
+# Copyright 2014-2024 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+#
+set -e
+
+# Get the path to the script itself
+SCRIPT_PATH="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+# Path to Dokka
+DOKKA_REPO_PATH="$SCRIPT_PATH/../"
+
+# Path to test project
+TEST_PROJECT_PATH="./examples/gradle/dokka-gradle-example"
+
+# New version to be published
+NEW_VERSION="1.9.20-my-fix-SNAPSHOT"
+
+# Port to view results
+PORT=8001
+
+#
+IS_MULTIMODULE=0
+
+# 0. Parse command line arguments
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        -v|--version)
+            NEW_VERSION="$2"
+            shift 2
+            ;;
+          -d|--directory)
+            TEST_PROJECT_PATH="$2"
+            shift 2
+            ;;
+          -m|--multimodule)
+            IS_MULTIMODULE=1
+            shift
+            ;;
+        -p|--port)
+            PORT="$2"
+            shift 2
+            ;;
+        *)
+            echo "TestDokka: Wrong parameter: $1"
+            exit 1
+            ;;
+    esac
+done
+
+echo "TestDokka: Test locally Dokka version $NEW_VERSION"
+echo "TestDokka: Test project path: $TEST_PROJECT_PATH"
+echo "TestDokka: Is multimodule: $IS_MULTIMODULE"
+echo "TestDokka: Dokka path: $DOKKA_REPO_PATH"
+echo "TestDokka: Port: $PORT"
+
+# 1. Publish to local Maven repository
+cd "$DOKKA_REPO_PATH"
+echo "TestDokka: Publish to local Maven repository"
+./gradlew publishToMavenLocal -Pversion="$NEW_VERSION"
+
+# 2. Update Dokka version in test project
+cd "$TEST_PROJECT_PATH"
+if [ -f "build.gradle.kts" ]; then
+    echo "TestDokka: Update version in build.gradle.kts"
+    sed -i "" "s/\(id(\"org\.jetbrains\.dokka\") version\) \".*\"/\1 \"$NEW_VERSION\"/"  build.gradle.kts
+fi
+
+if [ -f "gradle.properties" ]; then
+     echo "TestDokka: Update version in gradle.properties"
+    sed -i "" "s/dokka_version=.*/dokka_version=$NEW_VERSION/"  gradle.properties
+fi
+
+
+# 3. Build and generate documentation
+if [ "$IS_MULTIMODULE" -eq 1 ]; then
+    echo "TestDokka: Build multimodule project"
+    ./gradlew clean && ./gradlew dokkaHtmlMultiModule
+else
+    echo "TestDokka: Build single module project"
+    ./gradlew clean && ./gradlew dokkaHTML
+fi
+
+wait
+
+# 4 Vacate port
+# Find PID of process listening on port
+PID=$(lsof -t -i :"$PORT" || true)
+
+# Check that PID is not empty
+if [ -n "$PID" ]; then
+    echo "TestDokka: Kill process with PID $PID"
+    kill -9 "$PID"
+else
+    echo "TestDokka: Port $PORT is free"
+fi
+
+# 5.1 Echo link to documentation
+echo "TestDokka: Open http://localhost:$PORT in browser"
+
+# 5.2 Start Python server to view results
+if [ "$IS_MULTIMODULE" -eq 1 ]; then
+    cd "./build/dokka/htmlMultiModule"
+else
+    cd "./build/dokka/html"
+fi
+
+echo 'TestDokka: Start Python server in directory'
+echo "TestDokka: $TEST_PROJECT_PATH/build/dokka/html"
+
+python3 -m http.server "$PORT"
+
+echo "TestDokka: Done"

scripts/testDokka.sh.md

@@ -0,0 +1,67 @@
+## Purpose
+This is a helper script for Dokka development and testing.
+If it does not work for you, you can always do the same steps manually
+as described in [CONTRIBUTING.md](../CONTRIBUTING.md#usetest-locally-built-dokka).
+
+`.testDokka.sh` makes Dokka development and testing a bit faster
+
+It compiles current Dokka version from the source code, \
+publishes it to the local Maven repository, \
+then runs the Dokka documentation generation against the specified project \
+and finally runs a webserver to open the generated documentation in the browser.
+
+## Usage
+
+`cd scripts` and then
+
+### Without parameters 
+By default it applied to the `./examples/gradle/dokka-gradle-example` project
+
+```bash
+./testDokka.sh
+```
+
+### Specify test project path
+
+```bash
+./testDokka.sh -d ./examples/gradle/dokka-gradle-example
+```
+
+### Specify Dokka version
+
+```bash
+./testDokka.sh -v 1.9.20-my-fix-SNAPSHOT
+```
+
+### Specify port
+
+```bash
+./testDokka.sh  -p 8001
+```
+
+### All together
+
+```bash
+./testDokka.sh -d ./examples/gradle/dokka-gradle-example -v 1.9.20-my-fix-SNAPSHOT -p 8001
+```
+
+### Apply to a multi-module project
+
+```bash
+./testDokka.sh -m
+```
+
+
+## Requirements
+To run the server you need to have Python 3 installed.
+
+## Troubleshooting
+
+* Make sure thar the path to the test project specified relative to the root of the Dokka project
+
+* If occurs `Could not resolve all files for configuration ':dokkaHtmlPlugin'` error,
+    * then make sure that `mavenLocal()` is added to the `repositories` section of the `build.gradle` file of the project you are testing against.
+    It is not automated and should be done manually.
+
+* if occurs `Failed to write org.jetbrains.dokka.base.renderers.FileWriter@628cef4a. Parent job is Cancelling`
+  * then try to change the dokka version specified by `-v` parameter (e.g. `-v 1.9.20-my-fix1-SNAPSHOT`)