Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Revise root README.md documentation #2737

Merged
merged 5 commits into from
Jan 19, 2023
Merged

Revise root README.md documentation #2737

Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
a806517
Revise root README.md documentation
IgnatBeresnev Nov 3, 2022
14901a2
Fix problems encountered while proofreading
IgnatBeresnev Nov 9, 2022
34d84a6
Sync root README documentation with the kotlinlang version
IgnatBeresnev Dec 22, 2022
2a6c01c
Add a paragraph about dev. experience survey
IgnatBeresnev Jan 3, 2023
9f210d7
Add links leading to kotlinlang.org
IgnatBeresnev Jan 19, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
275 changes: 157 additions & 118 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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

<details open>
<summary>Kotlin DSL</summary>

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`:
</details>

```kotlin
dependencies {
dokkaHtmlPlugin("org.jetbrains.dokka:kotlin-as-java-plugin:1.7.20")
<details>
<summary>Groovy DSL</summary>

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
</details>

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
<build>
<plugins>
<plugin>
<groupId>org.jetbrains.dokka</groupId>
<artifactId>dokka-maven-plugin</artifactId>
<version>1.7.20</version>
<executions>
<execution>
<phase>pre-site</phase>
<goals>
<goal>dokka</goal>
</goals>
</execution>
</executions>
</plugin>
</plugins>
</build>
```

```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:

<details open>
<summary>Gradle Kotlin DSL</summary>

```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.
</details>

Documentation is by default generated in `target/dokka`.
<details>
<summary>Gradle Groovy DSL</summary>

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
</details>

#### Applying plugins
You can add plugins inside the `dokkaPlugins` block:
<details>
<summary>Maven</summary>

```xml
<plugin>
<groupId>org.jetbrains.dokka</groupId>
<artifactId>dokka-maven-plugin</artifactId>
<version>${dokka.version}</version>
<executions>
<execution>
<phase>pre-site</phase>
<goals>
<goal>dokka</goal>
</goals>
</execution>
</executions>
...
<configuration>
<dokkaPlugins>
<plugin>
<groupId>org.jetbrains.dokka</groupId>
<artifactId>kotlin-as-java-plugin</artifactId>
<version>${dokka.version}</version>
<artifactId>android-documentation-plugin</artifactId>
<version>1.7.20</version>
</plugin>
</dokkaPlugins>
</configuration>
</plugin>
```

Please see the [Dokka Maven example project](https://github.com/Kotlin/dokka/tree/master/examples/maven) for an example.
</details>

### 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 <arguments>
```
### HTML

You can also use a JSON file with dokka configuration:
```
java -jar <dokka_cli.jar> <path_to_config.json>
```
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<a name="output_formats"></a>
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)