Revise README documentation for examples and plugins

.github/workflows/dokka-examples.yml

@@ -90,8 +90,6 @@ jobs:
     strategy:
       matrix:
         include:
-          - task: "dokkaCustomFormat"
-            dir: "examples/gradle/dokka-customFormat-example"
           - task: "dokkaHtmlMultiModule"
             dir: "examples/gradle/dokka-multimodule-example"
     steps:

.github/workflows/gh-pages-examples.yml

@@ -48,7 +48,10 @@ jobs:
     if: github.repository == 'Kotlin/dokka'
     strategy:
       matrix:
-        projects: [ dokka-versioning-multimodule-example ]
+        projects: [
+          dokka-versioning-multimodule-example,
+          dokka-multimodule-example
+        ]
     steps:
       - uses: actions/checkout@v3
       - uses: dorny/paths-filter@v2

CONTRIBUTING.md

@@ -1,41 +1,89 @@
-## Building Dokka
-
-Dokka is built with Gradle. To build it, use `./gradlew build`.
-Alternatively, open the project directory in IntelliJ IDEA and use the IDE to build and run dokka.
-
-Here's how to import and configure Dokka in IntelliJ IDEA:
- * Select "Open" from the IDEA welcome screen, or File > Open if a project is
-  already open
-* Select the directory with your clone of Dokka
-  * Note: IDEA may have an error after the project is initally opened; it is OK
-    to ignore this as the next step will address this error
-* After IDEA opens the project, select File > New > Module from existing sources
-  and select the `build.gradle` file from the root directory of your Dokka clone
-* Use the default options and select "OK"
-* After Dokka is loaded into IDEA, open the Gradle tool window (View > Tool
-  Windows > Gradle) and click on the top left "Refresh all Gradle projects"
-  button
-* Verify the following project settings.  In File > Settings > Build, Execution,
-  Deployment > Build Tools > Gradle > Runner:
-  * Ensure "Delegate IDE build/run actions to gradle" is checked
-  * "Gradle Test Runner" should be selected in the "Run tests using" drop-down
-    menu
-* Note: After closing and re-opening the project, IDEA may give an error
-  message: "Error Loading Project: Cannot load 3 modules".  Open up the details
-  of the error, and click "Remove Selected", as these module `.iml` files are
-  safe to remove.
-
-## Using/testing locally built Dokka
-
-If you want to use/test your locally built Dokka in a project, do the following:
+# Contributing Guidelines
+
+There are three main ways you can contribute to Dokka's development:
+
+* Submitting issues.
+* Submitting fixes/changes/improvements via pull requests.
+* Developing community plugins.
+
+## Submitting issues
+
+Bug reports, feature requests and questions are welcome. Submit issues [here](https://github.com/Kotlin/dokka/issues).
+
+* Search for existing issues to avoid reporting duplicates.
+* When submitting a bug report:
+   * Test it against the most recently released version. It might have been fixed already.
+   * Include code that reproduces the problem. Provide a complete reproducer, yet minimize it as much as 
+     possible. A separate project that can be cloned is ideal.
+   * If the bug is in behavior, explain what behavior you expected and what the actual result is.
+* When submitting a feature request:
+   * Explain why you need the feature.
+   * Explaining the problem you face is more important than suggesting a solution.
+     Report your problem even if you have no proposed solution.
+
+## Submitting PRs
+
+Dokka has extensive [Developer Guides](https://kotlin.github.io/dokka/1.7.20/developer_guide/introduction/) documentation
+which goes over the development [Workflow](https://kotlin.github.io/dokka/1.7.20/developer_guide/workflow/) and 
+[Dokka's architecture](https://kotlin.github.io/dokka/1.7.20/developer_guide/architecture/architecture_overview/),
+which can help you understand how to achieve what you want and where to look.
+
+All development (both new features and bugfixes) takes place in the `master` branch, it contains sources for the next
+version of Dokka.
+
+For any code changes:
+
+* Follow [Kotlin Coding Conventions](https://kotlinlang.org/docs/reference/coding-conventions.html).
+  Use 4 spaces for indentation.
+* [Build the project](#building) to make sure it all works and tests pass.
+* Write tests that reproduce the bug or test new features.
+* PRs without tests are accepted only in exceptional circumstances if it is evident that writing the
+  corresponding test is too hard or otherwise impractical.
+* If you add new or change old public API, [update public API dump](#updating-public-api-dump), otherwise it will fail 
+  the build.
+
+Please [contact maintainers](#contacting-maintainers) in advance to coordinate any big piece of work.
+
+### Building
+
+Building Dokka is pretty straightforward, with one small caveat: when you run `./gradlew build`, it will run integration
+tests as well, which might take some time and will consume a lot of RAM (~20-30 GB), so you would usually want to exclude 
+integration tests when building locally:
+
+```Bash
+./gradlew build -x integrationTest
+```
+
+Unit tests which are run as part of `build` should not take much time, but you can also skip it with `-x test`.
+
+### Using/testing locally built Dokka
+
+Below you will find a bare-bones instruction on how to use and test locally built Dokka. For more details and examples, 
+visit [Workflow](https://kotlin.github.io/dokka/1.7.20/developer_guide/workflow/) topic.
+
 1. Change `dokka_version` in `gradle.properties` to something that you will use later on as the dependency version.
-   For example, you can set it to something like `1.7.20-my-fix-SNAPSHOT`.
-2. Publish it to maven local (`./gradlew publishToMavenLocal`)
-3. In the project you want to generate documentation for, add maven local as a plugin/dependency
+   For instance, you can set it to something like `1.7.20-my-fix-SNAPSHOT`.
+2. Publish it to Maven Local (`./gradlew publishToMavenLocal`)
+3. In the project for which you want to generate documentation add Maven Local as a buildscript/dependency
    repository (`mavenLocal()`)
-4. Update your dokka dependency to the version you've just published:
+4. Update your Dokka dependency to the version you've just published:
+
 ```kotlin
 plugins {
     id("org.jetbrains.dokka") version "1.7.20-my-fix-SNAPSHOT"
 }
 ```
+
+### Updating public API dump
+
+[Binary Compatibility Validator](https://github.com/Kotlin/binary-compatibility-validator/blob/master/README.md) 
+is used to keep track of public API changes.
+
+Run `./gradlew apiDump` to update API index files after introducing new or changing old public API. Commit updated 
+API indexes together with other changes.
+
+## Contacting maintainers
+
+* If something cannot be done, not convenient, or does not work — submit an [issue](#submitting-issues).
+* Discussions and general inquiries — use `#dokka` channel in 
+  [Kotlin Community Slack](https://surveys.jetbrains.com/s3/kotlin-slack-sign-up).

examples/README.md

@@ -0,0 +1,25 @@
+# Dokka examples
+
+## Gradle
+
+| Project                                                                             | Description                                                                                                                                                           |
+|-------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| [dokka-customFormat-example](gradle/dokka-customFormat-example)                     | Demonstrates how to override `.css` styles and add custom images as assets, allowing you to change the logo used in the header.                                       |
+| [dokka-gradle-example](gradle/dokka-gradle-example)                                 | Demonstrates how to apply Dokka in a simple single-project Gradle build, as well as how to configure it.                                                              |
+| [dokka-kotlinAsJava-example](gradle/dokka-kotlinAsJava-example)                     | Demonstrates how to apply Dokka plugins, [Kotlin as Java](../plugins/kotlin-as-java) specifically.                                                                    |
+| [dokka-library-publishing-example](gradle/dokka-library-publishing-example)         | Demonstrates how to integrate Dokka into the publishing process of a library, adding documentation generated by Dokka as artifacts.                                   |
+| [dokka-multimodule-example](gradle/dokka-multimodule-example)                       | Demonstrates how to apply and configure Dokka in a [multi-project build](https://docs.gradle.org/current/userguide/multi_project_builds.html).                        |
+| [dokka-multiplatform-example](gradle/dokka-multiplatform-example)                   | Demonstrates Dokka's configuration and output for a simple [Kotlin Multiplatform](https://kotlinlang.org/docs/multiplatform.html) project.                            |
+| [dokka-versioning-multimodule-example](gradle/dokka-versioning-multimodule-example) | Demonstrates configuration of Dokka's [versioning plugin](../../../plugins/versioning), which allows readers to navigate through different versions of documentation. |
+
+## Maven
+
+| Project        | Description                                         |
+|----------------|-----------------------------------------------------|
+| [maven](maven) | Simple Maven project with basic Dokka configuration |
+
+## Plugins
+
+| Project                                       | Description                                                                                            |
+|-----------------------------------------------|--------------------------------------------------------------------------------------------------------|
+| [hide-internal-api](plugin/hide-internal-api) | Dokka plugin that excludes declarations from generated documentation based on an `Internal` annotation |

examples/gradle/README.md

@@ -0,0 +1,11 @@
+# Gradle examples
+
+| Project                                                                             | Description                                                                                                                                                           |
+|-------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| [dokka-customFormat-example](gradle/dokka-customFormat-example)                     | Demonstrates how to override `.css` styles and add custom images as assets, allowing you to change the logo used in the header.                                       |
+| [dokka-gradle-example](gradle/dokka-gradle-example)                                 | Demonstrates how to apply Dokka in a simple single-project Gradle build, as well as how to configure it.                                                              |
+| [dokka-kotlinAsJava-example](gradle/dokka-kotlinAsJava-example)                     | Demonstrates how to apply Dokka plugins, [Kotlin as Java](../plugins/kotlin-as-java) specifically.                                                                    |
+| [dokka-library-publishing-example](gradle/dokka-library-publishing-example)         | Demonstrates how to integrate Dokka into the publishing process of a library, adding documentation generated by Dokka as artifacts.                                   |
+| [dokka-multimodule-example](gradle/dokka-multimodule-example)                       | Demonstrates how to apply and configure Dokka in a [multi-project build](https://docs.gradle.org/current/userguide/multi_project_builds.html).                        |
+| [dokka-multiplatform-example](gradle/dokka-multiplatform-example)                   | Demonstrates Dokka's configuration and output for a simple [Kotlin Multiplatform](https://kotlinlang.org/docs/multiplatform.html) project.                            |
+| [dokka-versioning-multimodule-example](gradle/dokka-versioning-multimodule-example) | Demonstrates configuration of Dokka's [versioning plugin](../../../plugins/versioning), which allows readers to navigate through different versions of documentation. |

examples/gradle/dokka-customFormat-example/README.md

@@ -1,24 +1,17 @@
 ## Dokka custom format example
 
-This example demonstrates a few things:
+This example demonstrates how to override `.css` styles and add custom images as assets, allowing
+you to change the logo used in the header.
 
-1. How to override css styles and add custom images.
-2. How to change logo used in the header.
-3. How to register a custom `Dokka` task with its own independent configuration.
+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).
 
-### Running
+![screenshot demonstration of output](demo.png)
 
-`dokkaCustomFormat` task has been created in the buildscript of this example project with a few configuration changes.
+### Running
 
-In order to see the full effect of these changes, run `dokkaCustomFormat` task from your IDE or execute
-the following command:
+Run `dokkaHtml` task to generate documentation with the custom logo in place:
 
 ```bash
-./gradlew clean dokkaCustomFormat
+./gradlew dokkaHtml
 ```
-
----
-
-If you run any other `Dokka` task, such as `dokkaHtml`, you'll see vanilla `Dokka` without any alterations.
-This is because changes to configuration are applied only within `dokkaCustomFormat` task. This can be useful
-if you want to generate multiple versions of documentation with different configuration settings.

examples/gradle/dokka-customFormat-example/build.gradle.kts

@@ -1,4 +1,6 @@
 import org.jetbrains.dokka.gradle.DokkaTask
+import org.jetbrains.dokka.base.DokkaBase
+import org.jetbrains.dokka.base.DokkaBaseConfiguration
 
 plugins {
     kotlin("jvm") version "1.7.20"
@@ -15,16 +17,16 @@ repositories {
     mavenCentral()
 }
 
-/**
- * Custom format adds a custom logo
- */
-tasks.register<DokkaTask>("dokkaCustomFormat") {
-    pluginConfiguration<org.jetbrains.dokka.base.DokkaBase, org.jetbrains.dokka.base.DokkaBaseConfiguration> {
+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"
     }
 }
 

examples/gradle/dokka-gradle-example/README.md

@@ -0,0 +1,22 @@
+# Dokka Gradle example
+
+This example demonstrates how to apply Dokka in a simple single-project Gradle build, as well as how to configure it.
+
+Configuration changes:
+
+* Custom project name used in the header, `Dokka Gradle Example`.
+* Description for the project and the packages taken from [Module.md](Module.md).
+* Documentation contains source links that lead to declarations in this GitHub repository.
+
+You can see up-to-date documentation generated for this example on
+[GitHub Pages](https://kotlin.github.io/dokka/examples/dokka-gradle-example/html/index.html).
+
+![screenshot demonstration of output](demo.png)
+
+### Running
+
+Run `dokkaHtml` task to generate documentation for this example:
+
+```bash
+./gradlew dokkaHtml
+```

examples/gradle/dokka-gradle-example/build.gradle.kts

@@ -18,8 +18,14 @@ dependencies {
 tasks.withType<DokkaTask>().configureEach {
     dokkaSourceSets {
         named("main") {
+            // used as project name in the header
             moduleName.set("Dokka Gradle Example")
+
+            // contains descriptions for the module and the packages
             includes.from("Module.md")
+
+            // adds source links that lead to this repository, allowing readers
+            // to easily find source code for inspected declarations
             sourceLink {
                 localDirectory.set(file("src/main/kotlin"))
                 remoteUrl.set(URL("https://github.com/Kotlin/dokka/tree/master/" +

examples/gradle/dokka-kotlinAsJava-example/README.md

@@ -0,0 +1,19 @@
+# Dokka Kotlin-as-Java plugin example
+
+This example demonstrates how you can apply a Dokka plugin in a simple Gradle project.
+
+In particular, it applies [Kotlin as Java](../../../plugins/kotlin-as-java) Dokka plugin that renders all
+Kotlin signatures as Java signatures.
+
+You can see up-to-date documentation generated for this example on
+[GitHub Pages](https://kotlin.github.io/dokka/examples/dokka-kotlinAsJava-example/html/index.html).
+
+![screenshot demonstration of output](demo.png)
+
+### Running
+
+Run `dokkaHtml` task to generate documentation for this example:
+
+```bash
+./gradlew dokkaHtml
+```

examples/gradle/dokka-kotlinAsJava-example/build.gradle.kts

@@ -11,7 +11,7 @@ dependencies {
     implementation(kotlin("stdlib"))
     testImplementation(kotlin("test-junit"))
 
-    // Will apply the plugin to all dokka tasks
+    // Will apply the plugin to all Dokka tasks
     dokkaPlugin("org.jetbrains.dokka:kotlin-as-java-plugin:1.7.20")
 
     // Will apply the plugin only to the `:dokkaHtml` task

examples/gradle/dokka-library-publishing-example/README.md

@@ -0,0 +1,41 @@
+# Dokka Library publishing example
+
+This example demonstrates how you can integrate Dokka into the publishing process of your library, adding
+documentation generated by Dokka as artifacts.
+
+This is useful because some repositories, like Maven Central, require documentation (`javadoc.jar`) to be published
+alongside library artifacts.
+
+You can also use services like [javadoc.io](https://javadoc.io/) to host of your library's API documentation for free 
+and without any additional setup - it will take documentation pages straight from the published artifact. It works with 
+both HTML and Javadoc formats as demonstrated by 
+[com.trib3's Javadocs](https://javadoc.io/doc/com.trib3/server/latest/index.html).
+
+## Running
+
+Run `dokkaHtml` task to generate documentation for this example:
+
+```bash
+./gradlew dokkaHtml
+```
+
+### Javadoc jar
+
+Run `dokkaJavadocJar` task to create a jar file that contains documentation generated in Dokka's Javadoc format.
+
+```Bash
+./gradlew dokkaJavadocJar
+```
+
+After that, you can find the jar under `build/libs/dokka-library-publishing-example-javadoc.jar`
+
+### HTML jar
+
+
+Run `dokkaHtmlJar` task to create a jar file that contains documentation generated in Dokka's HTML format.
+
+```Bash
+./gradlew dokkaHtmlJar
+```
+
+After that, you can find the jar under `build/libs/dokka-library-publishing-example-html.jar`

examples/gradle/dokka-multimodule-example/README.md

@@ -0,0 +1,25 @@
+# Dokka MultiModule example
+
+This example demonstrates how to apply and configure Dokka in a 
+[multi-project build](https://docs.gradle.org/current/userguide/multi_project_builds.html).
+
+You can also learn how to set Dokka's version in [gradle.properties](gradle.properties) using `pluginManagement` 
+configuration block in [settings.gradle.kts](settings.gradle.kts).
+
+____
+
+You can see up-to-date documentation generated for this example on
+[GitHub Pages](https://kotlin.github.io/dokka/examples/dokka-multimodule-example/htmlMultiModule/index.html).
+
+![screenshot demonstration of output](demo.png)
+
+### Running
+
+Run `dokkaHtmlMultiModule` task to generate documentation for this example:
+
+```bash
+./gradlew dokkaHtmlMultiModule
+```
+
+It will generate complete documentation for the root project and its subprojects, with a common
+Table of Contents.

examples/gradle/dokka-multimodule-example/gradle.properties

@@ -0,0 +1,2 @@
+kotlinVersion=1.7.20
+dokkaVersion=1.7.20