path: root/docs/topics/runners/dokka-cli.md

[//]: # (title: CLI)

If for some reason you cannot use [Gradle](dokka-gradle.md) or [Maven](dokka-maven.md) build tools, Dokka has
a command line (CLI) runner for generating documentation.

In comparison, it has the same, if not more, capabilities as the Gradle plugin for Dokka. Although it is considerably more
difficult to set up as there is no autoconfiguration, especially in multiplatform and multi-module environments.

## Get started

The CLI runner is published to Maven Central as a separate runnable artifact.

You can find it on [mvnrepository](https://mvnrepository.com/artifact/org.jetbrains.dokka/dokka-cli/%dokkaVersion%) or by browsing
[maven central repository directories](https://repo1.maven.org/maven2/org/jetbrains/dokka/dokka-cli/%dokkaVersion%) directly.

With the `dokka-cli-%dokkaVersion%.jar` file saved on your computer, run it with the `-help` option to see all 
available configuration options and their description:

```Bash
java -jar dokka-cli-%dokkaVersion%.jar -help
```

It also works for some nested options, such as `-sourceSet`:

```Bash
java -jar dokka-cli-%dokkaVersion%.jar -sourceSet -help
```

## Generate documentation

### Prerequisites

Since there is no build tool to manage dependencies, you have to provide dependency `.jar` files yourself.

Listed below are the dependencies that you need for any output format:

| **Group**             | **Artifact**               | **Version**    | **Link**                                                                                                        |
|-----------------------|----------------------------|----------------|-----------------------------------------------------------------------------------------------------------------|
| `org.jetbrains.dokka` | `dokka-base`               | %dokkaVersion% | [mvnrepository](https://mvnrepository.com/artifact/org.jetbrains.dokka/dokka-base/%dokkaVersion%)               |
| `org.jetbrains.dokka` | `dokka-analysis`           | %dokkaVersion% | [mvnrepository](https://mvnrepository.com/artifact/org.jetbrains.dokka/dokka-analysis/%dokkaVersion%)           |
| `org.jetbrains.dokka` | `kotlin-analysis-compiler` | %dokkaVersion% | [mvnrepository](https://mvnrepository.com/artifact/org.jetbrains.dokka/kotlin-analysis-compiler/%dokkaVersion%) |
| `org.jetbrains.dokka` | `kotlin-analysis-intellij` | %dokkaVersion% | [mvnrepository](https://mvnrepository.com/artifact/org.jetbrains.dokka/kotlin-analysis-intellij/%dokkaVersion%) |

Below are the additional dependencies that you need for [HTML](dokka-html.md) output format:

| **Group**               | **Artifact**       | **Version** | **Link**                                                                                         |
|-------------------------|--------------------|-------------|--------------------------------------------------------------------------------------------------|
| `org.jetbrains.kotlinx` | `kotlinx-html-jvm` | 0.8.0       | [mvnrepository](https://mvnrepository.com/artifact/org.jetbrains.kotlinx/kotlinx-html-jvm/0.8.0) |
| `org.freemarker`        | `freemarker`       | 2.3.31      | [mvnrepository](https://mvnrepository.com/artifact/org.freemarker/freemarker/2.3.31)             |


### Run with command line options

You can pass command line options to configure the CLI runner. 

At the very least you need to provide the following options:

* `-pluginsClasspath` - a list of absolute/relative paths to downloaded dependencies, separated by semi-colons `;`
* `-sourceSet` - an absolute path to code sources to generate documentation for
* `-outputDir` - an absolute/relative path of the documentation output directory

```Bash
java -jar dokka-cli-%dokkaVersion%.jar \
     -pluginsClasspath "./dokka-base-%dokkaVersion%.jar;./dokka-analysis-%dokkaVersion%.jar;./kotlin-analysis-intellij-%dokkaVersion%.jar;./kotlin-analysis-compiler-%dokkaVersion%.jar;./kotlinx-html-jvm-0.8.0.jar;./freemarker-2.3.31.jar" \
     -sourceSet "-src /home/myCoolProject/src/main/kotlin" \
     -outputDir "./dokka/html"
```

> Due to an internal class conflict, first pass `kotlin-analysis-intellij` and only then `kotlin-analysis-compiler`.
> Otherwise you may see obscure exceptions, such as `NoSuchFieldError`.
>
{type="note"}

Executing the given example generates documentation in [HTML](dokka-html.md) output format.

See [Command line options](#command-line-options) for more configuration details.

### Run with JSON configuration

It's possible to configure the CLI runner with JSON. In this case, you need to provide an
absolute/relative path to the JSON configuration file as the first and only argument. 
All other configuration options are parsed from it.

```Bash
java -jar dokka-cli-%dokkaVersion%.jar dokka-configuration.json
```

At the very least, you need the following JSON configuration file:

```json
{
  "outputDir": "./dokka/html",
  "sourceSets": [
    {
      "sourceSetID": {
        "scopeId": "moduleName",
        "sourceSetName": "main"
      },
      "sourceRoots": [
        "/home/myCoolProject/src/main/kotlin"
      ]
    }
  ],
  "pluginsClasspath": [
    "./dokka-base-%dokkaVersion%.jar",
    "./kotlinx-html-jvm-0.8.0.jar",
    "./dokka-analysis-%dokkaVersion%.jar",
    "./kotlin-analysis-intellij-%dokkaVersion%.jar",
    "./kotlin-analysis-compiler-%dokkaVersion%.jar",
    "./freemarker-2.3.31.jar"
  ]
}
```

> Due to an internal class conflict, first pass `kotlin-analysis-intellij` and only then `kotlin-analysis-compiler`.
> Otherwise you may see obscure exceptions, such as `NoSuchFieldError`.
>
{type="note"}

See [JSON configuration options](#json-configuration) for more details.

### Other output formats

By default, the `dokka-base` artifact contains the [HTML](dokka-html.md) output format only.

All other output formats are implemented as [Dokka plugins](dokka-plugins.md). In order to use them, you have to put them
on the plugins classpath.

For example, if you want to generate documentation in the experimental [GFM](dokka-markdown.md#gfm) output format, you need to download and
pass [gfm-plugin's JAR](https://mvnrepository.com/artifact/org.jetbrains.dokka/gfm-plugin/%dokkaVersion%) into 
the `pluginsClasspath` configuration option.

Via command line options:

```Shell
java -jar dokka-cli-%dokkaVersion%.jar \
     -pluginsClasspath "./dokka-base-%dokkaVersion%.jar;...;./gfm-plugin-%dokkaVersion%.jar" \
     ...
```

Via JSON configuration:

```json
{
  ...
  "pluginsClasspath": [
    "./dokka-base-%dokkaVersion%.jar",
    "...",
    "./gfm-plugin-%dokkaVersion%.jar"
  ],
  ...
}
```

With the GFM plugin passed to `pluginsClasspath`, the CLI runner generates documentation in the GFM output format.

For more information, see [Markdown](dokka-markdown.md) and [Javadoc](dokka-javadoc.md#generate-javadoc-documentation) pages.

## Command line options

To see the list of all possible command line options and their detailed description, run:

```Bash
java -jar dokka-cli-%dokkaVersion%.jar -help
```

Short summary:

| Option                       | Description                                                                                                                                                                                           |
|------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `moduleName`                 | Name of the project/module.                                                                                                                                                                           |
| `moduleVersion`              | Documented version.                                                                                                                                                                                   |
| `outputDir`                  | Output directory path, `./dokka` by default.                                                                                                                                                          |
| `sourceSet`                  | Configuration for a Dokka source set. Contains nested configuration options.                                                                                                                          |
| `pluginsConfiguration`       | Configuration for Dokka plugins.                                                                                                                                                                      |
| `pluginsClasspath`           | List of jars with Dokka plugins and their dependencies. Accepts multiple paths separated by semicolons.                                                                                               |
| `offlineMode`                | Whether to resolve remote files/links over network.                                                                                                                                                   |
| `failOnWarning`              | Whether to fail documentation generation if Dokka has emitted a warning or an error.                                                                                                                  |
| `delayTemplateSubstitution`  | Whether to delay substitution of some elements. Used in incremental builds of multi-module projects.                                                                                                  |
| `noSuppressObviousFunctions` | Whether to suppress obvious functions such as those inherited from `kotlin.Any` and `java.lang.Object`.                                                                                               |
| `includes`                   | Markdown files that contain module and package documentation. Accepts multiple values separated by semicolons.                                                                                        |
| `suppressInheritedMembers`   | Whether to suppress inherited members that aren't explicitly overridden in a given class.                                                                                                             |
| `globalPackageOptions`       | Global list of package configuration options in format `"matchingRegex,-deprecated,-privateApi,+warnUndocumented,+suppress;+visibility:PUBLIC;..."`. Accepts multiple values separated by semicolons. |
| `globalLinks`                | Global external documentation links in format `{url}^{packageListUrl}`. Accepts multiple values separated by `^^`.                                                                                    |
| `globalSrcLink`              | Global mapping between a source directory and a Web service for browsing the code. Accepts multiple paths separated by semicolons.                                                                    |
| `helpSourceSet`              | Prints help for the nested `-sourceSet` configuration.                                                                                                                                                |
| `loggingLevel`               | Logging level, possible values: `DEBUG, PROGRESS, INFO, WARN, ERROR`.                                                                                                                                 |
| `help, h`                    | Usage info.                                                                                                                                                                                           |

#### Source set options

To see the list of command line options for the nested `-sourceSet` configuration, run:

```Bash
java -jar dokka-cli-%dokkaVersion%.jar -sourceSet -help
```

Short summary:

| Option                       | Description                                                                                                                                                                    |
|------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `sourceSetName`              | Name of the source set.                                                                                                                                                        |
| `displayName`                | Display name of the source set, used both internally and externally.                                                                                                           |
| `classpath`                  | Classpath for analysis and interactive samples. Accepts multiple paths separated by semicolons.                                                                                |
| `src`                        | Source code roots to be analyzed and documented. Accepts multiple paths separated by semicolons.                                                                               |
| `dependentSourceSets`        | Names of the dependent source sets in format `moduleName/sourceSetName`. Accepts multiple paths separated by semicolons.                                                       |
| `samples`                    | List of directories or files that contain sample functions. Accepts multiple paths separated by semicolons. <anchor name="includes-cli"/>                                      |
| `includes`                   | Markdown files that contain [module and package documentation](dokka-module-and-package-docs.md). Accepts multiple paths separated by semicolons.                              |
| `documentedVisibilities`     | Visibilities to be documented. Accepts multiple values separated by semicolons. Possible values: `PUBLIC`, `PRIVATE`, `PROTECTED`, `INTERNAL`, `PACKAGE`.                      |
| `reportUndocumented`         | Whether to report undocumented declarations.                                                                                                                                   | 
| `noSkipEmptyPackages`        | Whether to create pages for empty packages.                                                                                                                                    | 
| `skipDeprecated`             | Whether to skip deprecated declarations.                                                                                                                                       | 
| `jdkVersion`                 | Version of JDK to use for linking to JDK Javadocs.                                                                                                                             |
| `languageVersion`            | Language version used for setting up analysis and samples.                                                                                                                     |
| `apiVersion`                 | Kotlin API version used for setting up analysis and samples.                                                                                                                   |
| `noStdlibLink`               | Whether to generate links to the Kotlin standard library.                                                                                                                      | 
| `noJdkLink`                  | Whether to generate links to JDK Javadocs.                                                                                                                                     | 
| `suppressedFiles`            | Paths to files to be suppressed. Accepts multiple paths separated by semicolons.                                                                                               |
| `analysisPlatform`           | Platform used for setting up analysis.                                                                                                                                         |
| `perPackageOptions`          | List of package source set configurations in format `matchingRegexp,-deprecated,-privateApi,+warnUndocumented,+suppress;...`. Accepts multiple values separated by semicolons. |
| `externalDocumentationLinks` | External documentation links in format `{url}^{packageListUrl}`. Accepts multiple values separated by `^^`.                                                                    |
| `srcLink`                    | Mapping between a source directory and a Web service for browsing the code. Accepts multiple paths separated by semicolons.                                                    |

## JSON configuration

Below are some examples and detailed descriptions for each configuration section. You can also find an example
with [all configuration options](#complete-configuration) applied at the bottom of the page.

### General configuration

```json
{
  "moduleName": "Dokka Example",
  "moduleVersion": null,
  "outputDir": "./build/dokka/html",
  "failOnWarning": false,
  "suppressObviousFunctions": true,
  "suppressInheritedMembers": false,
  "offlineMode": false,
  "includes": [
    "module.md"
  ],
  "sourceLinks":  [
    { "_comment": "Options are described in a separate section" }
  ],
  "perPackageOptions": [
    { "_comment": "Options are described in a separate section" }
  ],
  "externalDocumentationLinks":  [
    { "_comment": "Options are described in a separate section" }
  ],
  "