From 1fa8552994fb292729eca8c0de6a1561380b008c Mon Sep 17 00:00:00 2001 From: Ignat Beresnev Date: Thu, 19 Jan 2023 04:02:47 +0100 Subject: [PATCH] Revise README.md (#2737) --- README.md | 275 +++++++++++++++++++++++++++++++----------------------- 1 file changed, 157 insertions(+), 118 deletions(-) diff --git a/README.md b/README.md index 4f4e523f7e..21b99bfcd4 100644 --- a/README.md +++ b/README.md @@ -1,184 +1,223 @@ # Dokka [![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) +[![JetBrains official project](https://jb.gg/badges/official.svg)](https://github.com/JetBrains#jetbrains-on-github) -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 modern [HTML format](#html), +multiple flavors of [Markdown](#markdown), and Java's [Javadoc HTML](#javadoc). -**Full documentation is available at [https://kotlin.github.io/dokka/1.7.20/](https://kotlin.github.io/dokka/1.7.20/)** +Some libraries that use Dokka for their API reference documentation: -### 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) + +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). + +## Documentation + +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 Gradle plugin for Dokka in the root build script of your 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](https://docs.gradle.org/current/userguide/multi_project_builds.html) builds, you need +to apply the Gradle plugin for Dokka within 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`: +
-```kotlin -dependencies { - dokkaHtmlPlugin("org.jetbrains.dokka:kotlin-as-java-plugin:1.7.20") +
+Groovy DSL + +Apply Gradle plugin for Dokka 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](https://docs.gradle.org/current/userguide/multi_project_builds.html) builds, you need +to apply the Gradle plugin for Dokka within 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 the documentation, use the appropriate `dokka${format}` Gradle task: +To generate documentation, run the following Gradle tasks: -```bash -./gradlew dokkaHtml -``` +* `dokkaHtml` for single-project builds +* `dokkaHtmlMultiModule` for multi-project builds -Please see the [Dokka Gradle example project](https://github.com/Kotlin/dokka/tree/master/examples/gradle/dokka-gradle-example) for an example. +By default, the output directory is set to `/build/dokka/html` and `/build/dokka/htmlMultiModule` respectively. -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). +To learn more about the Gradle plugin for Dokka, see [documentation for Gradle](https://kotlinlang.org/docs/dokka-gradle.html). -#### Android +### Maven -Make sure you apply Dokka after `com.android.library` and `kotlin-android`. +Add the Dokka Maven plugin to the `plugins` section of your POM file: -```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 the `dokka:dokka` goal. + +By default, the output directory is set to `target/dokka`. + +To learn more about using Dokka with Maven, see [documentation for Maven](https://kotlinlang.org/docs/dokka-maven.html). + +### CLI -#### Multi-module projects -For documenting Gradle multi-module projects, you can use `dokka${format}Multimodule` tasks. +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 section. + +Please consult [documentation for the command line runner](https://kotlinlang.org/docs/dokka-cli.html) +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. +
-Documentation is by default generated in `target/dokka`. +
+Gradle Groovy DSL -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 and recommended output format. You can see an example of the output 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 the 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 [documentation for HTML format](https://kotlinlang.org/docs/dokka-html.html). -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. + +For more details and examples, see [documentation for Markdown formats](https://kotlinlang.org/docs/dokka-markdown.html). + +### 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). 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 +or an exact copy. In addition, all Kotlin signatures are translated to Java signatures. + +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](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/). + +## 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 -#### FAQ -If you encounter any problems, please see the [FAQ](https://github.com/Kotlin/dokka/wiki/faq). +See [Contributing Guidelines](CONTRIBUTING.md)