From a806517ecf56aa16e01ad2d45cb5a6431137cc67 Mon Sep 17 00:00:00 2001 From: IgnatBeresnev Date: Thu, 3 Nov 2022 07:41:52 +0100 Subject: [PATCH 1/5] Revise root README.md documentation --- README.md | 269 ++++++++++++++++++++++++++++++------------------------ 1 file changed, 151 insertions(+), 118 deletions(-) diff --git a/README.md b/README.md index 4f4e523f7e..78d1160c1f 100644 --- a/README.md +++ b/README.md @@ -1,184 +1,217 @@ # Dokka +[![JetBrains official project](https://jb.gg/badges/official.svg)](https://github.com/JetBrains#jetbrains-on-github) [![Kotlin Beta](https://kotl.in/badges/beta.svg)](https://kotlinlang.org/docs/components-stability.html) -[![JetBrains official project](https://jb.gg/badges/official.svg)](https://confluence.jetbrains.com/display/ALL/JetBrains+on+GitHub) -[![TeamCity (build status)](https://teamcity.jetbrains.com/app/rest/builds/buildType:(id:Kotlin_Dokka_DokkaAntMavenGradle)/statusIcon)](https://teamcity.jetbrains.com/viewType.html?buildTypeId=Kotlin_Dokka_DokkaAntMavenGradle&branch_KotlinTools_Dokka=%3Cdefault%3E&tab=buildTypeStatusDiv) -Dokka is a documentation engine for Kotlin, performing the same function as javadoc for Java. -Just like Kotlin itself, Dokka fully supports mixed-language Java/Kotlin projects. It understands -standard Javadoc comments in Java files and [KDoc comments](https://kotlinlang.org/docs/reference/kotlin-doc.html) in Kotlin files, -and can generate documentation in multiple formats including standard Javadoc, HTML and Markdown. +Dokka is an API documentation engine for Kotlin. -:mega: Dokka team now leads the product to the first Stable release. -And we’d really appreciate it if you could [take our brief survey](https://surveys.jetbrains.com/s3/dokka-survey) about your dev. experience with the tool. It helps us to understand priorities right and deliver the most valuable things. +Just like Kotlin itself, Dokka supports mixed-language projects: it understands Kotlin's +[KDoc comments](https://kotlinlang.org/docs/kotlin-doc.html#kdoc-syntax) and Java's +[Javadoc comments](https://www.oracle.com/technical-resources/articles/java/javadoc-tool.html). -## Using Dokka +Dokka can generate documentation in multiple formats, including its own and modern [HTML format](TODO), +multiple flavours of [Markdown](TODO) and Java's [Javadoc HTML](TODO). -**Full documentation is available at [https://kotlin.github.io/dokka/1.7.20/](https://kotlin.github.io/dokka/1.7.20/)** +Libraries that use Dokka for API reference docs: -### Using the Gradle plugin -_Note: If you are upgrading from 0.10.x to a current release of Dokka, please have a look at our -[migration guide](runners/gradle-plugin/MIGRATION.md)_ +* [kotlinx.coroutines](https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/) +* [Bitmovin](https://cdn.bitmovin.com/player/android/3/docs/index.html) +* [Hexagon](https://hexagonkt.com/api/index.html) +* [Ktor](https://api.ktor.io/) +* [OkHttp](https://square.github.io/okhttp/4.x/okhttp/okhttp3/) (Markdown format) + +Dokka can be run via [Gradle](TODO), [Maven](TODO) or [command line](TODO). It is also +[highly pluggable](TODO). + +## Quickstart + +### Gradle + +
+Kotlin DSL + +Apply Dokka Gradle plugin in the root project: -The preferred way is to use `plugins` block. - -build.gradle.kts: ```kotlin plugins { id("org.jetbrains.dokka") version "1.7.20" } +``` + +When documenting [multi-project](gradle.md#multi-project-builds) builds, you need to apply Dokka in subprojects as well: -repositories { - mavenCentral() +```kotlin +subprojects { + apply(plugin = "org.jetbrains.dokka") } ``` -The plugin adds `dokkaHtml`, `dokkaJavadoc`, `dokkaGfm` and `dokkaJekyll` tasks to the project. - -#### Applying plugins -Dokka plugin creates Gradle configuration for each output format in the form of `dokka${format}Plugin`: +To generate documentation run the following Gradle tasks: -```kotlin -dependencies { - dokkaHtmlPlugin("org.jetbrains.dokka:kotlin-as-java-plugin:1.7.20") +* `dokkaHtml` for single-project builds. +* `dokkaHtmlMultiModule` for multi-module builds. + +By default, output directory is set to `/build/dokka/html` and `/build/dokka/htmlMultiModule` respectively. + +
+ +
+Groovy DSL + +Apply Dokka Gradle plugin in the root project: + +```groovy +plugins { + id 'org.jetbrains.dokka' version '1.7.20' } -``` +``` -You can also create a custom Dokka task and add plugins directly inside: +When documenting multi-project builds, you need to apply Dokka in subprojects as well: -```kotlin -val customDokkaTask by creating(DokkaTask::class) { - dependencies { - plugins("org.jetbrains.dokka:kotlin-as-java-plugin:1.7.20") - } +```groovy +subprojects { + apply plugin: 'org.jetbrains.dokka' } ``` -Please note that `dokkaJavadoc` task will properly document only single `jvm` source set +To generate documentation run the following Gradle tasks: -To generate the documentation, use the appropriate `dokka${format}` Gradle task: +* `dokkaHtml` for single-project builds. +* `dokkaHtmlMultiModule` for multi-module builds. -```bash -./gradlew dokkaHtml -``` +By default, output directory is set to `/build/dokka/html` and `/build/dokka/htmlMultiModule`. -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). +Learn more about Gradle configuration in a separate [topic dedicated to Gradle](TODO). -#### Android +### Maven -Make sure you apply Dokka after `com.android.library` and `kotlin-android`. +Add Dokka Maven plugin to the plugins section of your POM: -```kotlin -buildscript { - dependencies { - classpath("org.jetbrains.kotlin:kotlin-gradle-plugin:${kotlin_version}") - classpath("org.jetbrains.dokka:dokka-gradle-plugin:${dokka_version}") - } -} -repositories { - mavenCentral() -} -apply(plugin= "com.android.library") -apply(plugin= "kotlin-android") -apply(plugin= "org.jetbrains.dokka") +```xml + + + + org.jetbrains.dokka + dokka-maven-plugin + 1.7.20 + + + pre-site + + dokka + + + + + + ``` -```kotlin -dokkaHtml.configure { - dokkaSourceSets { - named("main") { - noAndroidSdkLink.set(false) - } - } -} -``` +To generate documentation run `dokka:dokka` goal. By default, output directory is set to `target/dokka`. + +Learn more about Maven configuration in a separate [topic dedicated to Maven](TODO). -#### Multi-module projects -For documenting Gradle multi-module projects, you can use `dokka${format}Multimodule` tasks. +### CLI + +It is possible to run Dokka from command line without having to use any of the build tools, but it's more +difficult to set up and for that reason is not covered by this Quickstart guide. + +Please consult [documentation for command line runner](https://kotlin.github.io/dokka/1.7.20/user_guide/applying/cli/) +to learn how to use it. + +### Android + +In addition to applying and configuring Dokka, you can apply Dokka's +[Android documentation plugin](plugins/android-documentation) which aims to improve documentation experience on the +Android platform: + +
+Gradle Kotlin DSL ```kotlin -tasks.dokkaHtmlMultiModule.configure { - outputDirectory.set(buildDir.resolve("dokkaCustomMultiModuleOutput")) +dependencies { + dokkaPlugin("org.jetbrains.dokka:android-documentation-plugin:1.7.20") } ``` -`DokkaMultiModule` depends on all Dokka tasks in the subprojects, runs them, and creates a toplevel page -with links to all generated (sub)documentations - -### Using the Maven plugin +
-The Maven plugin does not support multi-platform projects. +
+Gradle Groovy DSL -Documentation is by default generated in `target/dokka`. - -The following goals are provided by the plugin: +```groovy +dependencies { + dokkaPlugin 'org.jetbrains.dokka:android-documentation-plugin:1.7.20' +} +``` - * `dokka:dokka` - generate HTML documentation in Dokka format (showing declarations in Kotlin syntax) - * `dokka:javadoc` - generate HTML documentation in Javadoc format (showing declarations in Java syntax) - * `dokka:javadocJar` - generate a .jar file with Javadoc format documentation +
-#### Applying plugins -You can add plugins inside the `dokkaPlugins` block: +
+Maven ```xml org.jetbrains.dokka dokka-maven-plugin - ${dokka.version} - - - pre-site - - dokka - - - + ... org.jetbrains.dokka - kotlin-as-java-plugin - ${dokka.version} + android-documentation-plugin + 1.7.20 ``` -Please see the [Dokka Maven example project](https://github.com/Kotlin/dokka/tree/master/examples/maven) for an example. +
-### Using the Command Line +## Output formats -To run Dokka from the command line, download the [Dokka CLI runner](https://mvnrepository.com/artifact/org.jetbrains.dokka/dokka-cli). -To generate documentation, run the following command: -``` -java -jar dokka-cli.jar -``` +### HTML -You can also use a JSON file with dokka configuration: - ``` - java -jar - ``` +HTML is Dokka's default, stable and recommended format. You can see it in action by browsing documentation for +[kotlinx.coroutines](https://kotlinlang.org/api/kotlinx.coroutines/). -### Output formats - Dokka documents Java classes as seen in Kotlin by default, with javadoc format being the only exception. +HTML format is configurable and, among other things, allows you to modify stylesheets, add custom image assets, change +footer message and revamp the structure of generated HTML pages through templates. - * `html` - HTML format used by default - * `javadoc` - looks like JDK's Javadoc, Kotlin classes are translated to Java - * `gfm` - GitHub flavored markdown - * `jekyll` - Jekyll compatible markdown +For more details and examples see [HTML format](TODO) topic. -If you want to generate the documentation as seen from Java perspective, you can add the `kotlin-as-java` plugin -to the Dokka plugins classpath, eg. in Gradle: +### Markdown -```kotlin -dependencies{ - implementation("...") - dokkaGfmPlugin("org.jetbrains.dokka:kotlin-as-java-plugin:${dokka-version}") -} -``` +Dokka is able to generate documentation in GitHub Flavored and Jekyll compatible Markdown. However, both of these +formats are still in Alpha, so you might encounter bugs and migration issues. + +`GFM` and `Jekyll` formats are essentially Dokka plugins. Learn how to apply and use them in a separate topic +dedicated to [Markdown format](TODO). + +### Javadoc + +Dokka's Javadoc output format is a lookalike of Java's +[Javadoc HTML format](https://docs.oracle.com/en/java/javase/19/docs/api/index.html). The format is still in Alpha, +so you might encounter bugs and migration issues. + +Javadoc format tries to visually mimic HTML pages generated by the Javadoc tool, but it's not a direct implementation, +and it's not an exact copy. In addition, all Kotlin signatures are translated to Java signatures. + +For more details and examples see [Javadoc format](TODO) topic. + +## Dokka plugins + +Dokka was built 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. + +Learn more about Dokka plugin and their configuration in a separate [topic dedicated to plugins](TODO) + +If you want to learn how to create Dokka plugins, see +[Developer guides](https://kotlin.github.io/dokka/1.7.20/developer_guide/introduction/). + +## Building and Contributing -#### FAQ -If you encounter any problems, please see the [FAQ](https://github.com/Kotlin/dokka/wiki/faq). +See [Contributing Guidelines](CONTRIBUTING.md) From 14901a27192aa5b01ecdcc978c0287998e4589b3 Mon Sep 17 00:00:00 2001 From: IgnatBeresnev Date: Wed, 9 Nov 2022 02:49:13 +0100 Subject: [PATCH 2/5] Fix problems encountered while proofreading --- README.md | 21 +++++++-------------- 1 file changed, 7 insertions(+), 14 deletions(-) diff --git a/README.md b/README.md index 78d1160c1f..b0a676f0ab 100644 --- a/README.md +++ b/README.md @@ -46,13 +46,6 @@ subprojects { } ``` -To generate documentation run the following Gradle tasks: - -* `dokkaHtml` for single-project builds. -* `dokkaHtmlMultiModule` for multi-module builds. - -By default, output directory is set to `/build/dokka/html` and `/build/dokka/htmlMultiModule` respectively. -
@@ -74,14 +67,14 @@ subprojects { } ``` +
+ To generate documentation run the following Gradle tasks: * `dokkaHtml` for single-project builds. * `dokkaHtmlMultiModule` for multi-module builds. -By default, output directory is set to `/build/dokka/html` and `/build/dokka/htmlMultiModule`. - - +By default, output directory is set to `/build/dokka/html` and `/build/dokka/htmlMultiModule` respectively. Learn more about Gradle configuration in a separate [topic dedicated to Gradle](TODO). @@ -116,7 +109,7 @@ Learn more about Maven configuration in a separate [topic dedicated to Maven](TO ### CLI It is possible to run Dokka from command line without having to use any of the build tools, but it's more -difficult to set up and for that reason is not covered by this Quickstart guide. +difficult to set up and for that reason it is not covered by this Quickstart guide. Please consult [documentation for command line runner](https://kotlin.github.io/dokka/1.7.20/user_guide/applying/cli/) to learn how to use it. @@ -124,7 +117,7 @@ to learn how to use it. ### Android In addition to applying and configuring Dokka, you can apply Dokka's -[Android documentation plugin](plugins/android-documentation) which aims to improve documentation experience on the +[Android documentation plugin](plugins/android-documentation), which aims to improve documentation experience on the Android platform:
@@ -175,13 +168,13 @@ dependencies { ### HTML -HTML is Dokka's default, stable and recommended format. You can see it in action by browsing documentation for +HTML is Dokka's default, stable and recommended output format. You can see it in action by browsing documentation for [kotlinx.coroutines](https://kotlinlang.org/api/kotlinx.coroutines/). HTML format is configurable and, among other things, allows you to modify stylesheets, add custom image assets, change footer message and revamp the structure of generated HTML pages through templates. -For more details and examples see [HTML format](TODO) topic. +For more details and examples, see [HTML format](TODO) topic. ### Markdown From 34d84a654e07345960e2826b2a866386fbf121e6 Mon Sep 17 00:00:00 2001 From: IgnatBeresnev Date: Thu, 22 Dec 2022 10:19:22 +0100 Subject: [PATCH 3/5] Sync root README documentation with the kotlinlang version --- README.md | 81 ++++++++++++++++++++++++++++++------------------------- 1 file changed, 45 insertions(+), 36 deletions(-) diff --git a/README.md b/README.md index b0a676f0ab..4d6af17149 100644 --- a/README.md +++ b/README.md @@ -1,36 +1,36 @@ # Dokka -[![JetBrains official project](https://jb.gg/badges/official.svg)](https://github.com/JetBrains#jetbrains-on-github) [![Kotlin Beta](https://kotl.in/badges/beta.svg)](https://kotlinlang.org/docs/components-stability.html) +[![JetBrains official project](https://jb.gg/badges/official.svg)](https://github.com/JetBrains#jetbrains-on-github) Dokka is an API documentation engine for Kotlin. -Just like Kotlin itself, Dokka supports mixed-language projects: it understands Kotlin's +Just like Kotlin itself, Dokka supports mixed-language projects. It understands Kotlin's [KDoc comments](https://kotlinlang.org/docs/kotlin-doc.html#kdoc-syntax) and Java's [Javadoc comments](https://www.oracle.com/technical-resources/articles/java/javadoc-tool.html). -Dokka can generate documentation in multiple formats, including its own and modern [HTML format](TODO), -multiple flavours of [Markdown](TODO) and Java's [Javadoc HTML](TODO). +Dokka can generate documentation in multiple formats, including its own modern [HTML format](/TODO), +multiple flavors of [Markdown](/TODO), and Java's [Javadoc HTML](/TODO). -Libraries that use Dokka for API reference docs: +Some libraries that use Dokka for their API reference documentation: * [kotlinx.coroutines](https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/) * [Bitmovin](https://cdn.bitmovin.com/player/android/3/docs/index.html) * [Hexagon](https://hexagonkt.com/api/index.html) * [Ktor](https://api.ktor.io/) -* [OkHttp](https://square.github.io/okhttp/4.x/okhttp/okhttp3/) (Markdown format) +* [OkHttp](https://square.github.io/okhttp/4.x/okhttp/okhttp3/) (Markdown) -Dokka can be run via [Gradle](TODO), [Maven](TODO) or [command line](TODO). It is also -[highly pluggable](TODO). +You can run Dokka using [Gradle](/TODO), [Maven](/TODO) or from the [command line](/TODO). It is also +[highly pluggable](/TODO). -## Quickstart +## Get started ### Gradle
Kotlin DSL -Apply Dokka Gradle plugin in the root project: +Apply the Dokka Gradle plugin in the root build script of your project: ```kotlin plugins { @@ -38,7 +38,8 @@ plugins { } ``` -When documenting [multi-project](gradle.md#multi-project-builds) builds, you need to apply Dokka in subprojects as well: +When documenting [multi-project](https://docs.gradle.org/current/userguide/multi_project_builds.html) builds, you need +to apply the Dokka Gradle plugin within subprojects as well: ```kotlin subprojects { @@ -59,7 +60,8 @@ plugins { } ``` -When documenting multi-project builds, you need to apply Dokka in subprojects as well: +When documenting [multi-project](https://docs.gradle.org/current/userguide/multi_project_builds.html) builds, you need +to apply the Dokka Gradle plugin within subprojects as well: ```groovy subprojects { @@ -69,18 +71,18 @@ subprojects {
-To generate documentation run the following Gradle tasks: +To generate documentation, run the following Gradle tasks: -* `dokkaHtml` for single-project builds. -* `dokkaHtmlMultiModule` for multi-module builds. +* `dokkaHtml` for single-project builds +* `dokkaHtmlMultiModule` for multi-module builds -By default, output directory is set to `/build/dokka/html` and `/build/dokka/htmlMultiModule` respectively. +By default, the output directory is set to `/build/dokka/html` and `/build/dokka/htmlMultiModule` respectively. -Learn more about Gradle configuration in a separate [topic dedicated to Gradle](TODO). +To learn more about the Gradle runner, see [Gradle](/TODO). ### Maven -Add Dokka Maven plugin to the plugins section of your POM: +Add the Dokka Maven plugin to the `plugins` section of your POM file: ```xml @@ -102,16 +104,18 @@ Add Dokka Maven plugin to the plugins section of your POM: ``` -To generate documentation run `dokka:dokka` goal. By default, output directory is set to `target/dokka`. +To generate documentation, run the `dokka:dokka` goal. -Learn more about Maven configuration in a separate [topic dedicated to Maven](TODO). +By default, the output directory is set to `target/dokka`. + +To learn more about the Maven runner, see [Maven](/TODO). ### CLI -It is possible to run Dokka from command line without having to use any of the build tools, but it's more -difficult to set up and for that reason it is not covered by this Quickstart guide. +It is possible to run Dokka from the command line without having to use any of the build tools, but it's more +difficult to set up and for that reason it is not covered in this Get started section. -Please consult [documentation for command line runner](https://kotlin.github.io/dokka/1.7.20/user_guide/applying/cli/) +Please consult [documentation for the command line runner](/TODO) to learn how to use it. ### Android @@ -168,43 +172,48 @@ dependencies { ### HTML -HTML is Dokka's default, stable and recommended output format. You can see it in action by browsing documentation for -[kotlinx.coroutines](https://kotlinlang.org/api/kotlinx.coroutines/). +HTML is Dokka's default and recommended output format. You can see an example of the final result by browsing +documentation for [kotlinx.coroutines](https://kotlinlang.org/api/kotlinx.coroutines/). HTML format is configurable and, among other things, allows you to modify stylesheets, add custom image assets, change footer message and revamp the structure of generated HTML pages through templates. -For more details and examples, see [HTML format](TODO) topic. +For more details and examples, see [HTML format](/TODO). ### Markdown Dokka is able to generate documentation in GitHub Flavored and Jekyll compatible Markdown. However, both of these formats are still in Alpha, so you might encounter bugs and migration issues. -`GFM` and `Jekyll` formats are essentially Dokka plugins. Learn how to apply and use them in a separate topic -dedicated to [Markdown format](TODO). +`GFM` and `Jekyll` formats are [Dokka plugins](/TODO). Learn how to apply and use them in a separate topic +dedicated to the [Markdown formats](/TODO). ### Javadoc Dokka's Javadoc output format is a lookalike of Java's -[Javadoc HTML format](https://docs.oracle.com/en/java/javase/19/docs/api/index.html). The format is still in Alpha, +[Javadoc HTML format](https://docs.oracle.com/en/java/javase/19/docs/api/index.html). This format is still in Alpha, so you might encounter bugs and migration issues. -Javadoc format tries to visually mimic HTML pages generated by the Javadoc tool, but it's not a direct implementation, -and it's not an exact copy. In addition, all Kotlin signatures are translated to Java signatures. +Javadoc format tries to visually mimic HTML pages generated by the Javadoc tool, but it's not a direct implementation +or an exact copy. In addition, all Kotlin signatures are translated to Java signatures. -For more details and examples see [Javadoc format](TODO) topic. +For more details and examples see [Javadoc format](/TODO) topic. ## Dokka plugins -Dokka was built 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 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. -Learn more about Dokka plugin and their configuration in a separate [topic dedicated to plugins](TODO) +Learn more about Dokka plugins and their configuration in [Dokka plugins](TODO) -If you want to learn how to create Dokka plugins, see +If you want to learn how to develop Dokka plugins, see [Developer guides](https://kotlin.github.io/dokka/1.7.20/developer_guide/introduction/). ## Building and Contributing See [Contributing Guidelines](CONTRIBUTING.md) + +## Community + +Dokka has a dedicated `#dokka` channel in [Kotlin Community Slack](https://surveys.jetbrains.com/s3/kotlin-slack-sign-up) +where you can chat about Dokka, its plugins and how to develop them, as well as get in touch with maintainers. From 2a6c01c7a5715939d013b48d57ab6e0a1dde1d40 Mon Sep 17 00:00:00 2001 From: IgnatBeresnev Date: Tue, 3 Jan 2023 02:33:35 +0100 Subject: [PATCH 4/5] Add a paragraph about dev. experience survey --- README.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/README.md b/README.md index 4d6af17149..2958286a10 100644 --- a/README.md +++ b/README.md @@ -23,6 +23,10 @@ Some libraries that use Dokka for their API reference documentation: You can run Dokka using [Gradle](/TODO), [Maven](/TODO) or from the [command line](/TODO). It is also [highly pluggable](/TODO). +:mega: Dokka team now leads the product to the Stable release. +We’d really appreciate it if you could [take our brief survey](https://surveys.jetbrains.com/s3/dokka-survey) about +your dev. experience with the tool. It helps us get priorities right and deliver the most valuable things first. + ## Get started ### Gradle From 9f210d78794f0d4209badf38e32608fd27dd018b Mon Sep 17 00:00:00 2001 From: IgnatBeresnev Date: Thu, 19 Jan 2023 04:00:56 +0100 Subject: [PATCH 5/5] Add links leading to kotlinlang.org --- README.md | 58 +++++++++++++++++++++++++++---------------------------- 1 file changed, 29 insertions(+), 29 deletions(-) diff --git a/README.md b/README.md index 2958286a10..21b99bfcd4 100644 --- a/README.md +++ b/README.md @@ -9,8 +9,8 @@ Just like Kotlin itself, Dokka supports mixed-language projects. It understands [KDoc comments](https://kotlinlang.org/docs/kotlin-doc.html#kdoc-syntax) and Java's [Javadoc comments](https://www.oracle.com/technical-resources/articles/java/javadoc-tool.html). -Dokka can generate documentation in multiple formats, including its own modern [HTML format](/TODO), -multiple flavors of [Markdown](/TODO), and Java's [Javadoc HTML](/TODO). +Dokka can generate documentation in multiple formats, including its own modern [HTML format](#html), +multiple flavors of [Markdown](#markdown), and Java's [Javadoc HTML](#javadoc). Some libraries that use Dokka for their API reference documentation: @@ -20,21 +20,22 @@ Some libraries that use Dokka for their API reference documentation: * [Ktor](https://api.ktor.io/) * [OkHttp](https://square.github.io/okhttp/4.x/okhttp/okhttp3/) (Markdown) -You can run Dokka using [Gradle](/TODO), [Maven](/TODO) or from the [command line](/TODO). It is also -[highly pluggable](/TODO). +You can run Dokka using [Gradle](https://kotlinlang.org/docs/dokka-gradle.html), +[Maven](https://kotlinlang.org/docs/dokka-maven.html) or from the [command line](https://kotlinlang.org/docs/dokka-cli.html). +It is also [highly pluggable](https://kotlinlang.org/docs/dokka-plugins.html). -:mega: Dokka team now leads the product to the Stable release. -We’d really appreciate it if you could [take our brief survey](https://surveys.jetbrains.com/s3/dokka-survey) about -your dev. experience with the tool. It helps us get priorities right and deliver the most valuable things first. +## Documentation -## Get started +Comprehensive documentation for Dokka is available on [kotlinlang.org](https://kotlinlang.org/docs/dokka-introduction.html) + +## Get started with Dokka ### Gradle
Kotlin DSL -Apply the Dokka Gradle plugin in the root build script of your project: +Apply the Gradle plugin for Dokka in the root build script of your project: ```kotlin plugins { @@ -43,7 +44,7 @@ plugins { ``` When documenting [multi-project](https://docs.gradle.org/current/userguide/multi_project_builds.html) builds, you need -to apply the Dokka Gradle plugin within subprojects as well: +to apply the Gradle plugin for Dokka within subprojects as well: ```kotlin subprojects { @@ -56,7 +57,7 @@ subprojects {
Groovy DSL -Apply Dokka Gradle plugin in the root project: +Apply Gradle plugin for Dokka in the root project: ```groovy plugins { @@ -65,7 +66,7 @@ plugins { ``` When documenting [multi-project](https://docs.gradle.org/current/userguide/multi_project_builds.html) builds, you need -to apply the Dokka Gradle plugin within subprojects as well: +to apply the Gradle plugin for Dokka within subprojects as well: ```groovy subprojects { @@ -78,11 +79,11 @@ subprojects { To generate documentation, run the following Gradle tasks: * `dokkaHtml` for single-project builds -* `dokkaHtmlMultiModule` for multi-module builds +* `dokkaHtmlMultiModule` for multi-project builds By default, the output directory is set to `/build/dokka/html` and `/build/dokka/htmlMultiModule` respectively. -To learn more about the Gradle runner, see [Gradle](/TODO). +To learn more about the Gradle plugin for Dokka, see [documentation for Gradle](https://kotlinlang.org/docs/dokka-gradle.html). ### Maven @@ -112,14 +113,14 @@ To generate documentation, run the `dokka:dokka` goal. By default, the output directory is set to `target/dokka`. -To learn more about the Maven runner, see [Maven](/TODO). +To learn more about using Dokka with Maven, see [documentation for Maven](https://kotlinlang.org/docs/dokka-maven.html). ### CLI It is possible to run Dokka from the command line without having to use any of the build tools, but it's more -difficult to set up and for that reason it is not covered in this Get started section. +difficult to set up and for that reason it is not covered in this section. -Please consult [documentation for the command line runner](/TODO) +Please consult [documentation for the command line runner](https://kotlinlang.org/docs/dokka-cli.html) to learn how to use it. ### Android @@ -176,21 +177,20 @@ dependencies { ### HTML -HTML is Dokka's default and recommended output format. You can see an example of the final result by browsing -documentation for [kotlinx.coroutines](https://kotlinlang.org/api/kotlinx.coroutines/). +HTML is Dokka's default and recommended output format. You can see an example of the output by browsing documentation +for [kotlinx.coroutines](https://kotlinlang.org/api/kotlinx.coroutines/). HTML format is configurable and, among other things, allows you to modify stylesheets, add custom image assets, change -footer message and revamp the structure of generated HTML pages through templates. +footer message and revamp the structure of the generated HTML pages through templates. -For more details and examples, see [HTML format](/TODO). +For more details and examples, see [documentation for HTML format](https://kotlinlang.org/docs/dokka-html.html). ### Markdown Dokka is able to generate documentation in GitHub Flavored and Jekyll compatible Markdown. However, both of these formats are still in Alpha, so you might encounter bugs and migration issues. -`GFM` and `Jekyll` formats are [Dokka plugins](/TODO). Learn how to apply and use them in a separate topic -dedicated to the [Markdown formats](/TODO). +For more details and examples, see [documentation for Markdown formats](https://kotlinlang.org/docs/dokka-markdown.html). ### Javadoc @@ -201,23 +201,23 @@ so you might encounter bugs and migration issues. Javadoc format tries to visually mimic HTML pages generated by the Javadoc tool, but it's not a direct implementation or an exact copy. In addition, all Kotlin signatures are translated to Java signatures. -For more details and examples see [Javadoc format](/TODO) topic. +For more details and examples, see [documentation for Javadoc format](https://kotlinlang.org/docs/dokka-javadoc.html). ## 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. -Learn more about Dokka plugins and their configuration in [Dokka plugins](TODO) +Learn more about Dokka plugins and their configuration in [Dokka plugins](https://kotlinlang.org/docs/dokka-plugins.html). If you want to learn how to develop Dokka plugins, see [Developer guides](https://kotlin.github.io/dokka/1.7.20/developer_guide/introduction/). -## Building and Contributing - -See [Contributing Guidelines](CONTRIBUTING.md) - ## Community Dokka has a dedicated `#dokka` channel in [Kotlin Community Slack](https://surveys.jetbrains.com/s3/kotlin-slack-sign-up) where you can chat about Dokka, its plugins and how to develop them, as well as get in touch with maintainers. + +## Building and Contributing + +See [Contributing Guidelines](CONTRIBUTING.md)