From 7544a215fb580ae0c47d1f397334f150d1a1ec65 Mon Sep 17 00:00:00 2001 From: Ignat Beresnev Date: Tue, 10 Jan 2023 13:14:43 +0100 Subject: Revise documentation (#2728) Co-authored-by: Sarah Haggarty --- docs/topics/dokka-plugins.md | 278 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 278 insertions(+) create mode 100644 docs/topics/dokka-plugins.md (limited to 'docs/topics/dokka-plugins.md') diff --git a/docs/topics/dokka-plugins.md b/docs/topics/dokka-plugins.md new file mode 100644 index 00000000..5d3501ac --- /dev/null +++ b/docs/topics/dokka-plugins.md @@ -0,0 +1,278 @@ +[//]: # (title: Dokka plugins) + +Dokka was built from the ground up to be easily extensible and highly customizable, which allows the community +to implement plugins for missing or very specific features that are not provided out of the box. + +Dokka plugins range anywhere from supporting other programming language sources to exotic output formats. You can add +support for your own KDoc tags or annotations, teach Dokka how to render different DSLs that are found in KDoc +descriptions, visually redesign Dokka's pages to be seamlessly integrated into your company's website, integrate it +with other tools and so much more. + +If you want to learn how to create Dokka plugins, see +[Developer guides](https://kotlin.github.io/dokka/%dokkaVersion%/developer_guide/introduction/). + +## Apply Dokka plugins + +Dokka plugins are published as separate artifacts, so to apply a Dokka plugin you only need to add it as a dependency. +From there, the plugin extends Dokka by itself - no further action is needed. + +> Plugins that use the same extension points or work in a similar way can interfere with each other. +> This may lead to visual bugs, general undefined behaviour or even failed builds. However, it should not lead to +> concurrency issues since Dokka does not expose any mutable data structures or objects. +> +> If you notice problems like this, it's a good idea to check which plugins are applied and what they do. +> +{type="note"} + +Let's have a look at how you can apply the [mathjax plugin](https://github.com/Kotlin/dokka/tree/master/plugins/mathjax) +to your project: + + + + +The Gradle plugin for Dokka creates convenient dependency configurations that allow you to apply plugins universally or +for a specific output format only. + +```kotlin +dependencies { + // Is applied universally + dokkaPlugin("org.jetbrains.dokka:mathjax-plugin:%dokkaVersion%") + + // Is applied for the single-module dokkaHtml task only + dokkaHtmlPlugin("org.jetbrains.dokka:kotlin-as-java-plugin:%dokkaVersion%") + + // Is applied for HTML format in multi-project builds + dokkaHtmlPartialPlugin("org.jetbrains.dokka:kotlin-as-java-plugin:%dokkaVersion%") +} +``` + +> When documenting [multi-project](dokka-gradle.md#multi-project-builds) builds, you need to apply Dokka plugins within +> subprojects as well as in their parent project. +> +{type="note"} + + + + +The Gradle plugin for Dokka creates convenient dependency configurations that allow you to apply Dokka plugins universally or +for a specific output format only. + +```groovy +dependencies { + // Is applied universally + dokkaPlugin 'org.jetbrains.dokka:mathjax-plugin:%dokkaVersion%' + + // Is applied for the single-module dokkaHtml task only + dokkaHtmlPlugin 'org.jetbrains.dokka:kotlin-as-java-plugin:%dokkaVersion%' + + // Is applied for HTML format in multi-project builds + dokkaHtmlPartialPlugin 'org.jetbrains.dokka:kotlin-as-java-plugin:%dokkaVersion%' +} +``` + +> When documenting [multi-project](dokka-gradle.md#multi-project-builds) builds, you need to apply Dokka plugins within +> subprojects as well as in their parent project. +> +{type="note"} + + + + +```xml + + org.jetbrains.dokka + dokka-maven-plugin + ... + + + + org.jetbrains.dokka + mathjax-plugin + %dokkaVersion% + + + + +``` + + + + +If you are using the [CLI](dokka-cli.md) runner with [command line options](dokka-cli.md#run-with-command-line-options), +Dokka plugins should be passed as `.jar` files to `-pluginsClasspath`: + +```Shell +java -jar dokka-cli-%dokkaVersion%.jar \ + -pluginsClasspath "./dokka-base-%dokkaVersion%.jar;...;./mathjax-plugin-%dokkaVersion%.jar" \ + ... +``` + +If you are using [JSON configuration](dokka-cli.md#run-with-json-configuration), Dokka plugins should be specified under +`pluginsClasspath`. + +```json +{ + ... + "pluginsClasspath": [ + "./dokka-base-%dokkaVersion%.jar", + "...", + "./mathjax-plugin-%dokkaVersion%.jar" + ], + ... +} +``` + + + + +## Configure Dokka plugins + +Dokka plugins can also have configuration options of their own. To see which options are available, consult +the documentation of the plugins you are using. + +Let's have a look at how you can configure the `DokkaBase` plugin, which is responsible for generating [HTML](dokka-html.md) +documentation, by adding a custom image to the assets (`customAssets` option), by adding custom style sheets +(`customStyleSheets` option), and by modifying the footer message (`footerMessage` option): + + + + +Gradle's Kotlin DSL allows for type-safe plugin configuration. This is achievable by adding the plugin's artifact to +the classpath dependencies in the `buildscript` block, and then importing plugin and configuration classes: + +```kotlin +import org.jetbrains.dokka.base.DokkaBase +import org.jetbrains.dokka.gradle.DokkaTask +import org.jetbrains.dokka.base.DokkaBaseConfiguration + +buildscript { + dependencies { + classpath("org.jetbrains.dokka:dokka-base:%dokkaVersion%") + } +} + +tasks.withType().configureEach { + pluginConfiguration { + customAssets = listOf(file("my-image.png")) + customStyleSheets = listOf(file("my-styles.css")) + footerMessage = "(c) 2022 MyOrg" + } +} +``` + +Alternatively, plugins can be configured via JSON. With this method, no additional dependencies are needed. + +```kotlin +import org.jetbrains.dokka.gradle.DokkaTask + +tasks.withType().configureEach { + val dokkaBaseConfiguration = """ + { + "customAssets": ["${file("assets/my-image.png")}"], + "customStyleSheets": ["${file("assets/my-styles.css")}"], + "footerMessage": "(c) 2022 MyOrg" + } + """ + pluginsMapConfiguration.set( + mapOf( + // fully qualified plugin name to json configuration + "org.jetbrains.dokka.base.DokkaBase" to dokkaBaseConfiguration + ) + ) +} +``` + + + + +```groovy +import org.jetbrains.dokka.gradle.DokkaTask + +tasks.withType(DokkaTask.class) { + String dokkaBaseConfiguration = """ + { + "customAssets": ["${file("assets/my-image.png")}"], + "customStyleSheets": ["${file("assets/my-styles.css")}"], + "footerMessage": "(c) 2022 MyOrg" + } + """ + pluginsMapConfiguration.set( + // fully qualified plugin name to json configuration + ["org.jetbrains.dokka.base.DokkaBase": dokkaBaseConfiguration] + ) +} +``` + + + + +```xml + + org.jetbrains.dokka + dokka-maven-plugin + ... + + + + + + + ${project.basedir}/my-image.png + + + ${project.basedir}/my-styles.css + + (c) MyOrg 2022 Maven + + + + +``` + + + + +If you are using the [CLI](dokka-cli.md) runner with [command line options](dokka-cli.md#run-with-command-line-options), +use the `-pluginsConfiguration` option that accepts JSON configuration in the form of `fullyQualifiedPluginName=json`. + +If you need to configure multiple plugins, you can pass multiple values separated by `^^`. + +```Bash +java -jar dokka-cli-%dokkaVersion%.jar \ + ... + -pluginsConfiguration "org.jetbrains.dokka.base.DokkaBase={\"customAssets\": [\"my-image.png\"], \"customStyleSheets\": [\"my-styles.css\"], \"footerMessage\": \"(c) 2022 MyOrg CLI\"}" +``` + +If you are using [JSON configuration](dokka-cli.md#run-with-json-configuration), there exists a similar +`pluginsConfiguration` array that accepts JSON configuration in `values`. + +```json +{ + "moduleName": "Dokka Example", + "pluginsConfiguration": [ + { + "fqPluginName": "org.jetbrains.dokka.base.DokkaBase", + "serializationFormat": "JSON", + "values": "{\"customAssets\": [\"my-image.png\"], \"customStyleSheets\": [\"my-styles.css\"], \"footerMessage\": \"(c) 2022 MyOrg\"}" + } + ] +} +``` + + + + +## Notable plugins + +Here are some notable Dokka plugins that you might find useful: + +| **Name** | **Description** | +|-----------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------| +| [Android documentation plugin](https://github.com/Kotlin/dokka/tree/master/plugins/android-documentation) | Improves the documentation experience on Android | +| [Versioning plugin](https://github.com/Kotlin/dokka/tree/master/plugins/versioning) | Adds version selector and helps to organize documentation for different versions of your application/library | +| [MermaidJS HTML plugin](https://github.com/glureau/dokka-mermaid) | Renders [MermaidJS](https://mermaid-js.github.io/mermaid/#/) diagrams and visualizations found in KDocs | +| [Mathjax HTML plugin](https://github.com/Kotlin/dokka/tree/master/plugins/mathjax) | Pretty prints mathematics found in KDocs | +| [Kotlin as Java plugin](https://github.com/Kotlin/dokka/tree/master/plugins/kotlin-as-java) | Renders Kotlin signatures as seen from Java's perspective | + +If you are a Dokka plugin author and would like to add your plugin to this list, get in touch with maintainers +via [Slack](dokka-introduction.md#community) or [GitHub](https://github.com/Kotlin/dokka/). \ No newline at end of file -- cgit