Migrate Dokka examples to Dokka repo (KT-47798) (#2030)

* Migrate Dokka examples to Dokka repo (KT-47798)

* Configure workflow of examples checking

* Add workflow to deploy examples

75 files changed, 2556 insertions, 4 deletions

diff --git a/.github/workflows/dokka-examples.yml b/.github/workflows/dokka-examples.yml
new file mode 100644
index 00000000..35fc5f92
--- /dev/null
+++ b/.github/workflows/dokka-examples.yml
@@ -0,0 +1,119 @@
+name: Build examples
+
+on: pull_request
+
+jobs:
+  build:
+    strategy:
+      matrix:
+        projects: [
+            examples/gradle/dokka-gradle-example,
+            examples/gradle/dokka-kotlinAsJava-example,
+            examples/gradle/dokka-library-publishing-example,
+            examples/gradle/dokka-multimodule-example,
+            examples/gradle/dokka-multiplatform-example,
+            examples/gradle/dokka-customFormat-example
+        ]
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - uses: dorny/paths-filter@v2
+        id: filter
+        with:
+          filters: |
+            examples_changed:
+              - '${{ matrix.projects }}/**'
+      - uses: actions/setup-java@v1
+        with:
+          java-version: 11
+      - run: ./gradlew build --no-daemon --stacktrace
+        working-directory: ${{ matrix.projects }}
+        if: steps.filter.outputs.examples_changed == 'true'
+
+  run-dokka-html:
+    strategy:
+      matrix:
+        projects: [
+            examples/gradle/dokka-gradle-example,
+            examples/gradle/dokka-kotlinAsJava-example,
+            examples/gradle/dokka-library-publishing-example,
+            examples/gradle/dokka-multiplatform-example,
+            examples/gradle/dokka-customFormat-example
+        ]
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - uses: dorny/paths-filter@v2
+        id: filter
+        with:
+          filters: |
+            examples_changed:
+              - '${{ matrix.projects }}/**'
+      - uses: actions/setup-java@v1
+        with:
+          java-version: 11
+      - run: ./gradlew dokkaHtml --no-daemon --stacktrace
+        working-directory: ${{ matrix.projects }}
+        if: steps.filter.outputs.examples_changed == 'true'
+
+  run-dokka-publishing:
+    strategy:
+      matrix:
+        tasks: [dokkaJavadocJar, dokkaHtmlJar]
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - uses: dorny/paths-filter@v2
+        id: filter
+        with:
+          filters: |
+            examples_changed:
+              - 'examples/gradle/dokka-library-publishing-example/**'
+      - uses: actions/setup-java@v1
+        with:
+          java-version: 11
+      - run: ./gradlew ${{ matrix.tasks }} --no-daemon --stacktrace
+        working-directory: examples/gradle/dokka-library-publishing-example
+        if: steps.filter.outputs.examples_changed == 'true'
+
+  run-dokka-gradle-tasks:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        include:
+          - task: "dokkaCustomFormat"
+            dir: "examples/gradle/dokka-customFormat-example"
+          - task: "dokkaHtmlMultiModule"
+            dir: "examples/gradle/dokka-multimodule-example"
+    steps:
+      - uses: actions/checkout@v2
+      - uses: dorny/paths-filter@v2
+        id: filter
+        with:
+          filters: |
+            examples_changed:
+              - '${{ matrix.dir }}/**'
+      - uses: actions/setup-java@v1
+        with:
+          java-version: 11
+      - run: ./gradlew ${{ matrix.task }} --no-daemon --stacktrace
+        working-directory: ${{ matrix.dir }}
+        if: steps.filter.outputs.examples_changed == 'true'
+
+  run-dokka-maven-example:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - uses: dorny/paths-filter@v2
+        id: filter
+        with:
+          filters: |
+            examples_changed:
+              - 'examples/maven/**'
+          working-directory: examples/maven
+      - uses: actions/setup-java@v1
+        with:
+          java-version: 11
+      - run: mvn compile dokka:dokka
+        working-directory: examples/maven
+        if: steps.filter.outputs.examples_changed == 'true'
\ No newline at end of file
diff --git a/.github/workflows/gh-pages-examples.yml b/.github/workflows/gh-pages-examples.yml
new file mode 100644
index 00000000..1931aaa7
--- /dev/null
+++ b/.github/workflows/gh-pages-examples.yml
@@ -0,0 +1,59 @@
+name: Build and deploy examples to GitHub Pages
+
+on:
+  push:
+    branches:
+      - master
+jobs:
+  build-examples:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        projects: [
+            dokka-gradle-example,
+            dokka-kotlinAsJava-example,
+            dokka-library-publishing-example,
+            dokka-multiplatform-example,
+            dokka-customFormat-example
+        ]
+    steps:
+      - name: Checkout dokka
+        uses: actions/checkout@v2
+      - uses: dorny/paths-filter@v2
+        id: filter
+        with:
+          filters: |
+            examples_changed:
+              - 'examples/gradle/${{ matrix.projects }}/**'
+
+      - uses: actions/setup-java@v1
+        with:
+          java-version: 11
+
+      - name: Build html
+        run: ./gradlew dokkaHtml --no-daemon --stacktrace
+        working-directory: examples/gradle/${{ matrix.projects }}
+        if: steps.filter.outputs.examples_changed == 'true'
+
+      - name: Upload artifact
+        uses: actions/upload-artifact@v2
+        if: steps.filter.outputs.examples_changed == 'true'
+        with:
+          name: ${{ matrix.projects }}
+          path: examples/gradle/${{ matrix.projects }}/build/dokka
+
+
+  deploy-examples:
+    runs-on: ubuntu-latest
+    needs: build-examples
+    steps:
+      - uses: actions/download-artifact@v2
+        with:
+          path: public/examples
+      - name: Deploy
+        uses: peaceiris/actions-gh-pages@v3
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          keep_files: true
+          publish_dir: ./public
+          full_commit_message: Publish examples
\ No newline at end of file
diff --git a/README.md b/README.md
index 5cb2370b..dc18c641 100644
--- a/README.md
+++ b/README.md
@@ -55,7 +55,7 @@ To generate the documentation, use the appropriate `dokka${format}` Gradle task:
 ./gradlew dokkaHtml
 ```
 
-Please see the [Dokka Gradle example project](https://github.com/Kotlin/kotlin-examples/tree/master/gradle/dokka/dokka-gradle-example) for an example.
+Please see the [Dokka Gradle example project](https://github.com/Kotlin/dokka/tree/master/examples/gradle/dokka-gradle-example) for an example.
 
 We encourage users to create their own plugins and share them with the community on [official plugins list](docs/src/doc/docs/community/plugins-list.md).
 
@@ -140,7 +140,7 @@ You can add plugins inside the `dokkaPlugins` block:
 </plugin>
 ```
 
-Please see the [Dokka Maven example project](https://github.com/JetBrains/kotlin-examples/tree/master/maven/dokka-maven-example) for an example.
+Please see the [Dokka Maven example project](https://github.com/Kotlin/dokka/tree/master/examples/maven) for an example.
 
 ### Using the Command Line
 
diff --git a/docs/src/doc/docs/user_guide/gradle/usage.md b/docs/src/doc/docs/user_guide/gradle/usage.md
index 85e7d75f..aa9783b4 100644
--- a/docs/src/doc/docs/user_guide/gradle/usage.md
+++ b/docs/src/doc/docs/user_guide/gradle/usage.md
@@ -330,4 +330,6 @@ tasks.dokkaHtmlPartial.configure {
 
 ## Example projects
 
-Please see the [Dokka Gradle single module example project](https://github.com/Kotlin/kotlin-examples/tree/master/gradle/dokka/dokka-gradle-example) or [multimodule](https://github.com/Kotlin/kotlin-examples/tree/master/gradle/dokka/dokka-multimodule-example) for an example.
+Please see the [Dokka Gradle single module example project](https://github.com/Kotlin/dokka/tree/master/examples/gradle/dokka-gradle-example) or [multimodule](https://github.com/Kotlin/dokka/tree/master/examples/gradle/dokka-multimodule-example) for an example.
+
+Also see [generated documentation](https://Kotlin.github.io/dokka/examples/dokka-gradle-example/html) in `HTML` format.
\ No newline at end of file
diff --git a/docs/src/doc/docs/user_guide/maven/usage.md b/docs/src/doc/docs/user_guide/maven/usage.md
index 6137d23d..25ccabf0 100644
--- a/docs/src/doc/docs/user_guide/maven/usage.md
+++ b/docs/src/doc/docs/user_guide/maven/usage.md
@@ -219,4 +219,4 @@ Some plugins can be configured separately using plugin's fully qualified name. F
 
 ## Example project
 
-Please see the [Dokka Maven example project](https://github.com/JetBrains/kotlin-examples/tree/master/maven/dokka-maven-example) for an example.
+Please see the [Dokka Maven example project](https://github.com/Kotlin/dokka/tree/master/examples/maven) for an example.
diff --git a/examples/gradle/dokka-customFormat-example/build.gradle.kts b/examples/gradle/dokka-customFormat-example/build.gradle.kts
new file mode 100644
index 00000000..94ea5029
--- /dev/null
+++ b/examples/gradle/dokka-customFormat-example/build.gradle.kts
@@ -0,0 +1,31 @@
+import org.jetbrains.dokka.gradle.DokkaTask
+
+plugins {
+    kotlin("jvm") version "1.4.32"
+    id("org.jetbrains.dokka") version ("1.4.32")
+}
+
+buildscript {
+    dependencies {
+        classpath("org.jetbrains.dokka:dokka-base:1.4.32")
+    }
+}
+
+repositories {
+    mavenCentral()
+}
+
+/**
+ * Custom format adds a custom logo
+ */
+tasks.register<DokkaTask>("dokkaCustomFormat") {
+    pluginConfiguration<org.jetbrains.dokka.base.DokkaBase, org.jetbrains.dokka.base.DokkaBaseConfiguration> {
+        customStyleSheets = listOf(file("logo-styles.css"))
+        customAssets = listOf(file("ktor-logo.png"))
+    }
+}
+
+dependencies {
+    implementation(kotlin("stdlib"))
+    testImplementation(kotlin("test-junit"))
+}
diff --git a/examples/gradle/dokka-customFormat-example/gradle/wrapper/gradle-wrapper.jar b/examples/gradle/dokka-customFormat-example/gradle/wrapper/gradle-wrapper.jar
new file mode 100644
index 00000000..5c2d1cf0
--- /dev/null
+++ b/examples/gradle/dokka-customFormat-example/gradle/wrapper/gradle-wrapper.jar
diff --git a/examples/gradle/dokka-customFormat-example/gradle/wrapper/gradle-wrapper.properties b/examples/gradle/dokka-customFormat-example/gradle/wrapper/gradle-wrapper.properties
new file mode 100644
index 00000000..bb8b2fc2
--- /dev/null
+++ b/examples/gradle/dokka-customFormat-example/gradle/wrapper/gradle-wrapper.properties
@@ -0,0 +1,5 @@
+distributionBase=GRADLE_USER_HOME
+distributionPath=wrapper/dists
+distributionUrl=https\://services.gradle.org/distributions/gradle-6.5.1-bin.zip
+zipStoreBase=GRADLE_USER_HOME
+zipStorePath=wrapper/dists
diff --git a/examples/gradle/dokka-customFormat-example/gradlew b/examples/gradle/dokka-customFormat-example/gradlew
new file mode 100755
index 00000000..83f2acfd
--- /dev/null
+++ b/examples/gradle/dokka-customFormat-example/gradlew
@@ -0,0 +1,188 @@
+#!/usr/bin/env sh
+
+#
+# Copyright 2015 the original author or authors.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+
+##############################################################################
+##
+##  Gradle start up script for UN*X
+##
+##############################################################################
+
+# Attempt to set APP_HOME
+# Resolve links: $0 may be a link
+PRG="$0"
+# Need this for relative symlinks.
+while [ -h "$PRG" ] ; do
+    ls=`ls -ld "$PRG"`
+    link=`expr "$ls" : '.*-> \(.*\)$'`
+    if expr "$link" : '/.*' > /dev/null; then
+        PRG="$link"
+    else
+        PRG=`dirname "$PRG"`"/$link"
+    fi
+done
+SAVED="`pwd`"
+cd "`dirname \"$PRG\"`/" >/dev/null
+APP_HOME="`pwd -P`"
+cd "$SAVED" >/dev/null
+
+APP_NAME="Gradle"
+APP_BASE_NAME=`basename "$0"`
+
+# Add default JVM options here. You can also use JAVA_OPTS and GRADLE_OPTS to pass JVM options to this script.
+DEFAULT_JVM_OPTS='"-Xmx64m" "-Xms64m"'
+
+# Use the maximum available, or set MAX_FD != -1 to use that value.
+MAX_FD="maximum"
+
+warn () {
+    echo "$*"
+}
+
+die () {
+    echo
+    echo "$*"
+    echo
+    exit 1
+}
+
+# OS specific support (must be 'true' or 'false').
+cygwin=false
+msys=false
+darwin=false
+nonstop=false
+case "`uname`" in
+  CYGWIN* )
+    cygwin=true
+    ;;
+  Darwin* )
+    darwin=true
+    ;;
+  MINGW* )
+    msys=true
+    ;;
+  NONSTOP* )
+    nonstop=true
+    ;;
+esac
+
+CLASSPATH=$APP_HOME/gradle/wrapper/gradle-wrapper.jar
+
+# Determine the Java command to use to start the JVM.
+if [ -n "$JAVA_HOME" ] ; then
+    if [ -x "$JAVA_HOME/jre/sh/java" ] ; then
+        # IBM's JDK on AIX uses strange locations for the executables
+        JAVACMD="$JAVA_HOME/jre/sh/java"
+    else
+        JAVACMD="$JAVA_HOME/bin/java"