diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c6916b3975..5a0379edcb 100644 --- a/CONTRIBUTING.md +++ b/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) diff --git a/scripts/testDokka.sh b/scripts/testDokka.sh new file mode 100755 index 0000000000..9c2c4bca8e --- /dev/null +++ b/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" diff --git a/scripts/testDokka.sh.md b/scripts/testDokka.sh.md new file mode 100644 index 0000000000..715f51e940 --- /dev/null +++ b/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`)