Contribute Dokkatoo (#3188)

12 files changed, 168 insertions, 0 deletions

diff --git a/dokka-runners/dokkatoo/examples/custom-format-example/dokka/README.md b/dokka-runners/dokkatoo/examples/custom-format-example/dokka/README.md
new file mode 100644
index 00000000..a25cd80e
--- /dev/null
+++ b/dokka-runners/dokkatoo/examples/custom-format-example/dokka/README.md
@@ -0,0 +1,17 @@
+## Dokka custom format example
+
+This example demonstrates how to override `.css` styles and add custom images as assets, allowing
+you to change the logo used in the header.
+
+You can see up-to-date documentation generated for this example on 
+[GitHub Pages](https://kotlin.github.io/dokka/examples/dokka-customFormat-example/html/index.html).
+
+![screenshot demonstration of output](demo.png)
+
+### Running
+
+Run `dokkaHtml` task to generate documentation with the custom logo in place:
+
+```bash
+./gradlew dokkaHtml
+```
diff --git a/dokka-runners/dokkatoo/examples/custom-format-example/dokka/build.gradle.kts b/dokka-runners/dokkatoo/examples/custom-format-example/dokka/build.gradle.kts
new file mode 100644
index 00000000..27540ee6
--- /dev/null
+++ b/dokka-runners/dokkatoo/examples/custom-format-example/dokka/build.gradle.kts
@@ -0,0 +1,35 @@
+import org.jetbrains.dokka.gradle.DokkaTask
+import org.jetbrains.dokka.base.DokkaBase
+import org.jetbrains.dokka.base.DokkaBaseConfiguration
+
+plugins {
+    kotlin("jvm") version "1.9.0"
+    id("org.jetbrains.dokka") version "1.9.0"
+}
+
+buildscript {
+    dependencies {
+        classpath("org.jetbrains.dokka:dokka-base:1.9.0")
+    }
+}
+
+repositories {
+    mavenCentral()
+}
+
+tasks.dokkaHtml {
+    pluginConfiguration<DokkaBase, DokkaBaseConfiguration> {
+        // Dokka's stylesheets and assets with conflicting names will be overriden.
+        // In this particular case, logo-styles.css will be overriden and ktor-logo.png will
+        // be added as an additional image asset
+        customStyleSheets = listOf(file("logo-styles.css"))
+        customAssets = listOf(file("ktor-logo.png"))
+
+        // Text used in the footer
+        footerMessage = "(c) Custom Format Dokka example"
+    }
+}
+
+dependencies {
+    testImplementation(kotlin("test-junit"))
+}
diff --git a/dokka-runners/dokkatoo/examples/custom-format-example/dokka/demo.png b/dokka-runners/dokkatoo/examples/custom-format-example/dokka/demo.png
new file mode 100644
index 00000000..8f9b88b0
--- /dev/null
+++ b/dokka-runners/dokkatoo/examples/custom-format-example/dokka/demo.png
diff --git a/dokka-runners/dokkatoo/examples/custom-format-example/dokka/ktor-logo.png b/dokka-runners/dokkatoo/examples/custom-format-example/dokka/ktor-logo.png
new file mode 100644
index 00000000..ef943896
--- /dev/null
+++ b/dokka-runners/dokkatoo/examples/custom-format-example/dokka/ktor-logo.png
diff --git a/dokka-runners/dokkatoo/examples/custom-format-example/dokka/logo-styles.css b/dokka-runners/dokkatoo/examples/custom-format-example/dokka/logo-styles.css
new file mode 100644
index 00000000..ffe4d503
--- /dev/null
+++ b/dokka-runners/dokkatoo/examples/custom-format-example/dokka/logo-styles.css
@@ -0,0 +1,20 @@
+/*
+ * All Margins and sizes are custom for the ktor-logo.png file.
+ * You may need to override it and find what works best for your case.
+ */
+:root {
+    --dokka-logo-image-url: url('../images/ktor-logo.png');
+    --dokka-logo-height: 125px;
+    --dokka-logo-width: 50px;
+}
+
+/* link custom rules styles */
+.library-name--link {
+    /* ... */
+}
+
+/* logo custom rules styles */
+.library-name--link::before {
+    background-position: left;
+    width: 52px;
+}
\ No newline at end of file
diff --git a/dokka-runners/dokkatoo/examples/custom-format-example/dokka/settings.gradle.kts b/dokka-runners/dokkatoo/examples/custom-format-example/dokka/settings.gradle.kts
new file mode 100644
index 00000000..9855e823
--- /dev/null
+++ b/dokka-runners/dokkatoo/examples/custom-format-example/dokka/settings.gradle.kts
@@ -0,0 +1 @@
+rootProject.name = "dokka-customFormat-example"
diff --git a/dokka-runners/dokkatoo/examples/custom-format-example/dokka/src/main/kotlin/demo/HelloWorld.kt b/dokka-runners/dokkatoo/examples/custom-format-example/dokka/src/main/kotlin/demo/HelloWorld.kt
new file mode 100644
index 00000000..172e18f7
--- /dev/null
+++ b/dokka-runners/dokkatoo/examples/custom-format-example/dokka/src/main/kotlin/demo/HelloWorld.kt
@@ -0,0 +1,20 @@
+package demo
+
+/**
+ * This class supports greeting people by name.
+ *
+ * @property name The name of the person to be greeted.
+ */
+class Greeter(val name: String) {
+
+    /**
+     * Prints the greeting to the standard output.
+     */
+    fun greet() {
+        println("Hello $name!")
+    }
+}
+
+fun main(args: Array<String>) {
+    Greeter(args[0]).greet()
+}
diff --git a/dokka-runners/dokkatoo/examples/custom-format-example/dokkatoo/build.gradle.kts b/dokka-runners/dokkatoo/examples/custom-format-example/dokkatoo/build.gradle.kts
new file mode 100644
index 00000000..7832a8f9
--- /dev/null
+++ b/dokka-runners/dokkatoo/examples/custom-format-example/dokkatoo/build.gradle.kts
@@ -0,0 +1,18 @@
+plugins {
+  kotlin("jvm") version "1.9.0"
+  id("org.jetbrains.dokka.dokkatoo") version "2.1.0-SNAPSHOT"
+}
+
+dokkatoo {
+  moduleName.set("customFormat-example")
+  pluginsConfiguration.html {
+    // Dokka's stylesheets and assets with conflicting names will be overridden.
+    // In this particular case, logo-styles.css will be overridden
+    // and ktor-logo.png will be added as an additional image asset
+    customStyleSheets.from("logo-styles.css")
+    customAssets.from("ktor-logo.png")
+
+    // Text used in the footer
+    footerMessage.set("(c) Custom Format Dokka example")
+  }
+}
diff --git a/dokka-runners/dokkatoo/examples/custom-format-example/dokkatoo/ktor-logo.png b/dokka-runners/dokkatoo/examples/custom-format-example/dokkatoo/ktor-logo.png
new file mode 100644
index 00000000..ef943896
--- /dev/null
+++ b/dokka-runners/dokkatoo/examples/custom-format-example/dokkatoo/ktor-logo.png
diff --git a/dokka-runners/dokkatoo/examples/custom-format-example/dokkatoo/logo-styles.css b/dokka-runners/dokkatoo/examples/custom-format-example/dokkatoo/logo-styles.css
new file mode 100644
index 00000000..ffe4d503
--- /dev/null
+++ b/dokka-runners/dokkatoo/examples/custom-format-example/dokkatoo/logo-styles.css
@@ -0,0 +1,20 @@
+/*
+ * All Margins and sizes are custom for the ktor-logo.png file.
+ * You may need to override it and find what works best for your case.
+ */
+:root {
+    --dokka-logo-image-url: url('../images/ktor-logo.png');
+    --dokka-logo-height: 125px;
+    --dokka-logo-width: 50px;
+}
+
+/* link custom rules styles */
+.library-name--link {
+    /* ... */
+}
+
+/* logo custom rules styles */
+.library-name--link::before {
+    background-position: left;
+    width: 52px;
+}
\ No newline at end of file
diff --git a/dokka-runners/dokkatoo/examples/custom-format-example/dokkatoo/settings.gradle.kts b/dokka-runners/dokkatoo/examples/custom-format-example/dokkatoo/settings.gradle.kts
new file mode 100644
index 00000000..31ad8c91
--- /dev/null
+++ b/dokka-runners/dokkatoo/examples/custom-format-example/dokkatoo/settings.gradle.kts
@@ -0,0 +1,17 @@
+rootProject.name = "custom-format-example"
+
+pluginManagement {
+  repositories {
+    mavenCentral()
+    gradlePluginPortal()
+    maven(providers.gradleProperty("testMavenRepo"))
+  }
+}
+
+@Suppress("UnstableApiUsage")
+dependencyResolutionManagement {
+  repositories {
+    mavenCentral()
+    maven(providers.gradleProperty("testMavenRepo"))
+  }
+}
diff --git a/dokka-runners/dokkatoo/examples/custom-format-example/dokkatoo/src/main/kotlin/demo/HelloWorld.kt b/dokka-runners/dokkatoo/examples/custom-format-example/dokkatoo/src/main/kotlin/demo/HelloWorld.kt
new file mode 100644
index 00000000..172e18f7
--- /dev/null
+++ b/dokka-runners/dokkatoo/examples/custom-format-example/dokkatoo/src/main/kotlin/demo/HelloWorld.kt
@@ -0,0 +1,20 @@
+package demo
+
+/**
+ * This class supports greeting people by name.
+ *
+ * @property name The name of the person to be greeted.
+ */
+class Greeter(val name: String) {
+
+    /**
+     * Prints the greeting to the standard output.
+     */
+    fun greet() {
+        println("Hello $name!")
+    }
+}
+
+fun main(args: Array<String>) {
+    Greeter(args[0]).greet()
+}