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/runners/dokka-cli.md | 859 +++++++++++++++++++ docs/topics/runners/dokka-gradle.md | 1557 +++++++++++++++++++++++++++++++++++ docs/topics/runners/dokka-maven.md | 646 +++++++++++++++ 3 files changed, 3062 insertions(+) create mode 100644 docs/topics/runners/dokka-cli.md create mode 100644 docs/topics/runners/dokka-gradle.md create mode 100644 docs/topics/runners/dokka-maven.md (limited to 'docs/topics/runners') diff --git a/docs/topics/runners/dokka-cli.md b/docs/topics/runners/dokka-cli.md new file mode 100644 index 00000000..fa8fa459 --- /dev/null +++ b/docs/topics/runners/dokka-cli.md @@ -0,0 +1,859 @@ +[//]: # (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. | +| `includes` | Markdown files that contain module and package documentation. 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" } + ], + "sourceSets": [ + { "_comment": "Options are described in a separate section" } + ], + "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" + ] +} +``` + + + +

The display name used to refer to the module. It is used for the table of contents, navigation, logging, etc.

+

Default: root

+ + +

The module version.

+

Default: empty

+ + +

The directory to where documentation is generated, regardless of output format.

+

Default: ./dokka

+ + +

+ Whether to fail documentation generation if Dokka has emitted a warning or an error. + The process waits until all errors and warnings have been emitted first. +

+

This setting works well with reportUndocumented

+

Default: false

+ + +

Whether to suppress obvious functions.

+

+ A function is considered to be obvious if it is: + +

  • + Inherited from kotlin.Any, Kotlin.Enum, java.lang.Object or + java.lang.Enum, such as equals, hashCode, toString. +
    • +
  • + Synthetic (generated by the compiler) and does not have any documentation, such as + dataClass.componentN or dataClass.copy. +
    • + +

    +

    Default: true

    +     + +

    Whether to suppress inherited members that aren't explicitly overridden in a given class.

    +

    + Note: This can suppress functions such as equals / hashCode / toString, + but cannot suppress synthetic functions such as dataClass.componentN and + dataClass.copy. Use suppressObviousFunctions + for that. +

    +

    Default: false

    +     + +

    Whether to resolve remote files/links over your network.

    +

    + This includes package-lists used for generating external documentation links. + For example, to make classes from the standard library clickable. +

    +

    + Setting this to true can significantly speed up build times in certain cases, + but can also worsen documentation quality and user experience. For example, by + not resolving class/member links from your dependencies, including the standard library. +

    +

    + Note: You can cache fetched files locally and provide them to + Dokka as local paths. See externalDocumentationLinks section. +

    +

    Default: false

    +     + +

    + A list of Markdown files that contain + module and package documentation. +

    +

    The contents of specified files are parsed and embedded into documentation as module and package descriptions.

    +

    This can be configured on per-package basis.

    +     + +

    + Individual and additional configuration of Kotlin + source sets. +

    +

    For a list of possible options, see source set configuration.

    +     + +

    The global configuration of source links that is applied for all source sets.

    +

    For a list of possible options, see source link configuration.

    +     + +

    The global configuration of matched packages, regardless of the source set they are in.

    +

    For a list of possible options, see per-package configuration.

    +     + +

    The global configuration of external documentation links, regardless of the source set they are used in.

    +

    For a list of possible options, see external documentation configuration.

    +     + +

    A list of JAR files with Dokka plugins and their dependencies.

    +     +     + +### Source set configuration + +How to configure Kotlin +[source sets](https://kotlinlang.org/docs/multiplatform-discover-project.html#source-sets): + +```json +{ + "sourceSets": [ + { + "displayName": "jvm", + "sourceSetID": { + "scopeId": "moduleName", + "sourceSetName": "main" + }, + "dependentSourceSets": [ + { + "scopeId": "dependentSourceSetScopeId", + "sourceSetName": "dependentSourceSetName" + } + ], + "documentedVisibilities": ["PUBLIC", "PRIVATE", "PROTECTED", "INTERNAL", "PACKAGE"], + "reportUndocumented": false, + "skipEmptyPackages": true, + "skipDeprecated": false, + "jdkVersion": 8, + "languageVersion": "1.7", + "apiVersion": "1.7", + "noStdlibLink": false, + "noJdkLink": false, + "includes": [ + "module.md" + ], + "analysisPlatform": "jvm", + "sourceRoots": [ + "/home/ignat/IdeaProjects/dokka-debug-mvn/src/main/kotlin" + ], + "classpath": [ + "libs/kotlin-stdlib-%kotlinVersion%.jar", + "libs/kotlin-stdlib-common-%kotlinVersion%.jar" + ], + "samples": [ + "samples/basic.kt" + ], + "suppressedFiles": [ + "src/main/kotlin/org/jetbrains/dokka/Suppressed.kt" + ], + "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" } + ] + } + ] +} +``` + + + +

    The display name used to refer to this source set.

    +

    + The name is used both externally (for example, the source set name is visible to documentation readers) and + internally (for example, for logging messages of reportUndocumented). +

    +

    The platform name can be used if you don't have a better alternative.

    +     + +

    The technical ID of the source set

    +     + +

    The set of visibility modifiers that should be documented.

    +

    + This can be used if you want to document protected/internal/private declarations, + as well as if you want to exclude public declarations and only document internal API. +

    +

    This can be configured on per-package basis.

    +

    + Possible values: + +

  • PUBLIC
    • +
  • PRIVATE
    • +
  • PROTECTED
    • +
  • INTERNAL
    • +
  • PACKAGE
    • + +

    +

    Default: PUBLIC

    +     + +

    + Whether to emit warnings about visible undocumented declarations, that is declarations without KDocs + after they have been filtered by documentedVisibilities and other filters. +

    +

    This setting works well with failOnWarning.

    +

    This can be configured on per-package basis.

    +

    Default: false

    +     + +

    + Whether to skip packages that contain no visible declarations after + various filters have been applied. +

    +

    + For example, if skipDeprecated is set to true and your package contains only + deprecated declarations, it is considered to be empty. +

    +

    Default for CLI runner is false.

    +     + +

    Whether to document declarations annotated with @Deprecated.

    +

    This can be configured on per-package basis.

    +

    Default: false

    +     + +

    The JDK version to use when generating external documentation links for Java types.

    +

    + For example, if you use java.util.UUID in some public declaration signature, + and this option is set to 8, Dokka generates an external documentation link + to JDK 8 Javadocs for it. +

    +     + +

    + The Kotlin language version + used for setting up analysis and @sample + environment. +

    +     + +

    + The Kotlin API version + used for setting up analysis and @sample + environment. +

    +     + +

    + Whether to generate external documentation links that lead to the API reference + documentation of Kotlin's standard library. +

    +

    Note: Links are generated when noStdLibLink is set to false.

    +

    Default: false

    +     + +

    Whether to generate external documentation links to JDK's Javadocs.

    +

    The version of JDK Javadocs is determined by the jdkVersion option.

    +

    Note: Links are generated when noJdkLink is set to false.

    +

    Default: false

    +     + +

    + A list of Markdown files that contain + module and package documentation. +

    +

    The contents of the specified files are parsed and embedded into documentation as module and package descriptions.

    +     + +

    + Platform to be used for setting up code analysis and + @sample environment. +

    +

    + Possible values: + +

  • jvm
    • +
  • common
    • +
  • js
    • +
  • native
    • + +

    +     + +

    + The source code roots to be analyzed and documented. + Acceptable inputs are directories and individual .kt / .java files. +

    +     + +

    The classpath for analysis and interactive samples.

    +

    This is useful if some types that come from dependencies are not resolved/picked up automatically.

    +

    This option accepts both .jar and .klib files.

    +     + +

    + A list of directories or files that contain sample functions which are referenced via the + @sample KDoc tag. +

    +     + +

    The files to be suppressed when generating documentation.

    +     + +

    A set of parameters for source links that is applied only for this source set.

    +

    For a list of possible options, see source link configuration.

    +     + +

    A set of parameters specific to matched packages within this source set.

    +

    For a list of possible options, see per-package configuration.

    +     + +

    A set of parameters for external documentation links that is applied only for this source set.

    +

    For a list of possible options, see external documentation configuration.

    +     +     + +### Source link configuration + +The `sourceLinks` configuration block allows you to add a `source` link to each signature +that leads to the `remoteUrl` with a specific line number. (The line number is configurable by setting `remoteLineSuffix`). + +This helps readers to find the source code for each declaration. + +For an example, see the documentation for the +[`count()`](https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/count.html) +function in `kotlinx.coroutines`. + +You can configure source links for all source sets together at the same time, or +[individually](#source-set-configuration): + +```json +{ + "sourceLinks": [ + { + "localDirectory": "src/main/kotlin", + "remoteUrl": "https://github.com/Kotlin/dokka/tree/master/src/main/kotlin", + "remoteLineSuffix": "#L" + } + ] +} +``` + + + +

    The path to the local source directory.

    +     + +

    + The URL of the source code hosting service that can be accessed by documentation readers, + like GitHub, GitLab, Bitbucket, etc. This URL is used to generate + source code links of declarations. +

    +     + +

    + The suffix used to append the source code line number to the URL. This helps readers navigate + not only to the file, but to the specific line number of the declaration. +

    +

    + The number itself is appended to the specified suffix. For example, + if this option is set to #L and the line number is 10, the resulting URL suffix + is #L10. +

    +

    + Suffixes used by popular services: + +

  • GitHub: #L
    • +
  • GitLab: #L
    • +
  • Bitbucket: #lines-
    • + +

    +

    Default: empty (no suffix)

    +     +     + +### Per-package configuration + +The `perPackageOptions` configuration block allows setting some options for specific packages matched by `matchingRegex`. + +You can add package configurations for all source sets together at the same time, or +[individually](#source-set-configuration): + +```json +{ + "perPackageOptions": [ + { + "matchingRegex": ".*internal.*", + "suppress": false, + "skipDeprecated": false, + "reportUndocumented": false, + "documentedVisibilities": ["PUBLIC", "PRIVATE", "PROTECTED", "INTERNAL", "PACKAGE"] + } + ] +} +``` + + + +

    The regular expression that is used to match the package.

    +     + +

    Whether this package should be skipped when generating documentation.

    +

    Default: false

    +     + +

    Whether to document declarations annotated with @Deprecated.

    +

    This can be set on project/module level.

    +

    Default: false

    +     + +

    + Whether to emit warnings about visible undocumented declarations, that is declarations without KDocs + after they have been filtered by documentedVisibilities and other filters. +

    +

    This setting works well with failOnWarning.

    +

    This can be configured on source set level.

    +

    Default: false

    +     + +

    The set of visibility modifiers that should be documented.

    +

    + This can be used if you want to document protected/internal/private declarations within this package, + as well as if you want to exclude public declarations and only document internal API. +

    +

    Can be configured on source set level.

    +

    Default: PUBLIC

    +     +     + +### External documentation configuration + +The `externalDocumentationLink` block allows the creation of links that lead to the externally hosted documentation of +your dependencies. + +For example, if you are using types from `kotlinx.serialization`, by default they are unclickable in your +documentation, as if they are unresolved. However, since the API reference documentation for `kotlinx.serialization` +is built by Dokka and is [published on kotlinlang.org](https://kotlinlang.org/api/kotlinx.serialization/), you can +configure external documentation links for it. Thus allowing Dokka to generate links for types from the library, making +them resolve successfully and clickable. + +You can configure external documentation links for all source sets together at the same time, or +[individually](#source-set-configuration): + +```json +{ + "externalDocumentationLinks": [ + { + "url": "https://kotlinlang.org/api/kotlinx.serialization/", + "packageListUrl": "https://kotlinlang.org/api/kotlinx.serialization/package-list" + } + ] +} +``` + + + +

    The root URL of documentation to link to. It must contain a trailing slash.

    +

    + Dokka does its best to automatically find package-list for the given URL, + and link declarations together. +

    +

    + If automatic resolution fails or if you want to use locally cached files instead, + consider setting the packageListUrl option. +

    +     + +

    + The exact location of a package-list. This is an alternative to relying on Dokka + automatically resolving it. +

    +

    + Package lists contain information about the documentation and the project itself, + such as module and package names. +

    +

    This can also be a locally cached file to avoid network calls.

    +     +     + +### Complete configuration + +Below you can see all possible configuration options applied at the same time. + +```json +{ + "moduleName": "Dokka Example", + "moduleVersion": null, + "outputDir": "./build/dokka/html", + "failOnWarning": false, + "suppressObviousFunctions": true, + "suppressInheritedMembers": false, + "offlineMode": false, + "sourceLinks": [ + { + "localDirectory": "src/main/kotlin", + "remoteUrl": "https://github.com/Kotlin/dokka/tree/master/src/main/kotlin", + "remoteLineSuffix": "#L" + } + ], + "externalDocumentationLinks": [ + { + "url": "https://docs.oracle.com/javase/8/docs/api/", + "packageListUrl": "https://docs.oracle.com/javase/8/docs/api/package-list" + }, + { + "url": "https://kotlinlang.org/api/latest/jvm/stdlib/", + "packageListUrl": "https://kotlinlang.org/api/latest/jvm/stdlib/package-list" + } + ], + "perPackageOptions": [ + { + "matchingRegex": ".*internal.*", + "suppress": false, + "reportUndocumented": false, + "skipDeprecated": false, + "documentedVisibilities": ["PUBLIC", "PRIVATE", "PROTECTED", "INTERNAL", "PACKAGE"] + } + ], + "sourceSets": [ + { + "displayName": "jvm", + "sourceSetID": { + "scopeId": "moduleName", + "sourceSetName": "main" + }, + "dependentSourceSets": [ + { + "scopeId": "dependentSourceSetScopeId", + "sourceSetName": "dependentSourceSetName" + } + ], + "documentedVisibilities": ["PUBLIC", "PRIVATE", "PROTECTED", "INTERNAL", "PACKAGE"], + "reportUndocumented": false, + "skipEmptyPackages": true, + "skipDeprecated": false, + "jdkVersion": 8, + "languageVersion": "1.7", + "apiVersion": "1.7", + "noStdlibLink": false, + "noJdkLink": false, + "includes": [ + "module.md" + ], + "analysisPlatform": "jvm", + "sourceRoots": [ + "/home/ignat/IdeaProjects/dokka-debug-mvn/src/main/kotlin" + ], + "classpath": [ + "libs/kotlin-stdlib-%kotlinVersion%.jar", + "libs/kotlin-stdlib-common-%kotlinVersion%.jar" + ], + "samples": [ + "samples/basic.kt" + ], + "suppressedFiles": [ + "src/main/kotlin/org/jetbrains/dokka/Suppressed.kt" + ], + "sourceLinks": [ + { + "localDirectory": "src/main/kotlin", + "remoteUrl": "https://github.com/Kotlin/dokka/tree/master/src/main/kotlin", + "remoteLineSuffix": "#L" + } + ], + "externalDocumentationLinks": [ + { + "url": "https://docs.oracle.com/javase/8/docs/api/", + "packageListUrl": "https://docs.oracle.com/javase/8/docs/api/package-list" + }, + { + "url": "https://kotlinlang.org/api/latest/jvm/stdlib/", + "packageListUrl": "https://kotlinlang.org/api/latest/jvm/stdlib/package-list" + } + ], + "perPackageOptions": [ + { + "matchingRegex": ".*internal.*", + "suppress": false, + "reportUndocumented": false, + "skipDeprecated": false, + "documentedVisibilities": ["PUBLIC", "PRIVATE", "PROTECTED", "INTERNAL", "PACKAGE"] + } + ] + } + ], + "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" + ], + "pluginsConfiguration": [ + { + "fqPluginName": "org.jetbrains.dokka.base.DokkaBase", + "serializationFormat": "JSON", + "values": "{\"separateInheritedMembers\":false,\"footerMessage\":\"© 2021 pretty good Copyright\"}" + } + ], + "includes": [ + "module.md" + ] +} +``` diff --git a/docs/topics/runners/dokka-gradle.md b/docs/topics/runners/dokka-gradle.md new file mode 100644 index 00000000..21a42322 --- /dev/null +++ b/docs/topics/runners/dokka-gradle.md @@ -0,0 +1,1557 @@ +[//]: # (title: Gradle) + +To generate documentation for a Gradle-based project, you can use the +[Gradle plugin for Dokka](https://plugins.gradle.org/plugin/org.jetbrains.dokka). + +It comes with basic autoconfiguration for your project, has convenient [Gradle tasks](#generate-documentation) for +generating documentation, and provides a great deal of [configuration options](#configuration-options) to +customize the output. + +You can play around with Dokka and see how it can be configured for various projects by visiting our +[Gradle example projects](https://github.com/Kotlin/dokka/tree/%dokkaVersion%/examples/gradle). + +## Apply Dokka + +The recommended way of applying the Gradle plugin for Dokka is with the +[plugins DSL](https://docs.gradle.org/current/userguide/plugins.html#sec:plugins_block): + + + + +```kotlin +plugins { + id("org.jetbrains.dokka") version "%dokkaVersion%" +} +``` + + + + +```groovy +plugins { + id 'org.jetbrains.dokka' version '%dokkaVersion%' +} +``` + + + + +When documenting [multi-project](dokka-gradle.md#multi-project-builds) builds, you need to apply the Gradle plugin for Dokka +within subprojects as well. You can use `allprojects {}` or `subprojects {}` Gradle configurations to achieve that: + + + + +```kotlin +subprojects { + apply(plugin = "org.jetbrains.dokka") +} +``` + + + + +```groovy +subprojects { + apply plugin: 'org.jetbrains.dokka' +} +``` + + + + +See [Configuration examples](#configuration-examples) if you are not sure where to apply Dokka. + +> Under the hood, Dokka uses the [Kotlin Gradle plugin](https://kotlinlang.org/docs/gradle-configure-project.html#apply-the-plugin) +> to perform autoconfiguration of [source sets](https://kotlinlang.org/docs/multiplatform-discover-project.html#source-sets) +> for which documentation is to be generated. Make sure to apply the Kotlin Gradle Plugin or +> [configure source sets](#source-set-configuration) manually. +> +{type="note"} + +> If you are using Dokka in a +> [precompiled script plugin](https://docs.gradle.org/current/userguide/custom_plugins.html#sec:precompiled_plugins), +> you need to add the [Kotlin Gradle plugin](https://kotlinlang.org/docs/gradle-configure-project.html#apply-the-plugin) +> as a dependency for it to work properly: +> +> +> +> +> ```kotlin +> implementation(kotlin("gradle-plugin", "%kotlinVersion%")) +> ``` +> +> +> +> +> ```groovy +> implementation 'org.jetbrains.kotlin:kotlin-gradle-plugin:%kotlinVersion%' +> ``` +> +> +> +> +{type="note"} + +If you cannot use the plugins DSL for some reason, you can use +[the legacy method](https://docs.gradle.org/current/userguide/plugins.html#sec:old_plugin_application) of applying +plugins. + +## Generate documentation + +The Gradle plugin for Dokka comes with [HTML](dokka-html.md), [Markdown](dokka-markdown.md) and [Javadoc](dokka-javadoc.md) output formats +built in. It adds a number of tasks for generating documentation, both for [single](#single-project-builds) +and [multi-project](#multi-project-builds) builds. + +### Single-project builds + +Use the following tasks to build documentation for simple, single-project applications and libraries: + +#### Stable formats + +| **Task** | **Description** | +|----------------|-------------------------------------------------------------------------------------| +| `dokkaHtml` | Generates documentation in [HTML](dokka-html.md) format. | + +#### Experimental formats + +| **Task** | **Description** | +|----------------|-------------------------------------------------------------------------------------| +| `dokkaGfm` | Generates documentation in [GitHub Flavored Markdown](dokka-markdown.md#gfm) format. | +| `dokkaJavadoc` | Generates documentation in [Javadoc](dokka-javadoc.md) format. | +| `dokkaJekyll` | Generates documentation in [Jekyll compatible Markdown](dokka-markdown.md#jekyll) format. | + +By default, generated documentation is located in the `build/dokka/{format}` directory of your project. +The output location, among other things, can be [configured](#configuration-examples). + +### Multi-project builds + +For documenting [multi-project builds](https://docs.gradle.org/current/userguide/multi_project_builds.html), make sure +that you [apply the Gradle plugin for Dokka](#apply-dokka) within subprojects that you want to generate documentation +for, as well as in their parent project. + +#### MultiModule tasks + +`MultiModule` tasks generate documentation for each subproject individually via [`Partial`](#partial-tasks) tasks, +collect and process all outputs, and produce complete documentation with a common table of contents and resolved +cross-project references. + +Dokka creates the following tasks for **parent** projects automatically: + +#### Stable formats + +| **Task** | **Description** | +|--------------------------|------------------------------------------------------------------------| +| `dokkaHtmlMultiModule` | Generates multi-module documentation in [HTML](dokka-html.md) output format. | + +#### Experimental formats + +| **Task** | **Description** | +|--------------------------|---------------------------------------------------------------------------------------------------------| +| `dokkaGfmMultiModule` | Generates multi-module documentation in [GitHub Flavored Markdown](dokka-markdown.md#gfm) output format. | +| `dokkaJekyllMultiModule` | Generates multi-module documentation in [Jekyll compatible Markdown](dokka-markdown.md#jekyll) output format. | + +> The [Javadoc](dokka-javadoc.md) output format does not have a `MultiModule` task, but a [`Collector`](#collector-tasks) task can +> be used instead. +> +{type="note"} + +By default, you can find ready-to-use documentation under `{parentProject}/build/dokka/{format}MultiModule` directory. + +#### MultiModule results + +Given a project with the following structure: + +```text +parentProject + └── childProjectA + ├── demo + ├── ChildProjectAClass + └── childProjectB + ├── demo + ├── ChildProjectBClass +``` + +These pages are generated after running `dokkaHtmlMultiModule`: + +![Screenshot for output of dokkaHtmlMultiModule task](dokkaHtmlMultiModule-example.png){width=600} + +See our [multi-module project example](https://github.com/Kotlin/dokka/tree/master/examples/gradle/dokka-multimodule-example) +for more details. + +#### Collector tasks + +Similar to `MultiModule` tasks, `Collector` tasks are created for each parent project: `dokkaHtmlCollector`, +`dokkaGfmCollector`, `dokkaJavadocCollector` and `dokkaJekyllCollector`. + +A `Collector` task executes the corresponding [single-project task](#single-project-builds) for each subproject (for +example, +`dokkaHtml`), and merges all outputs into a single virtual project. + +The resulting documentation looks as if you have a single-project +build that contains all declarations from the subprojects. + +> Use the `dokkaJavadocCollector` task if you need to create Javadoc documentation for your multi-project build. +> +{type="tip"} + +#### Collector results + +Given a project with the following structure: + +```text +parentProject + └── childProjectA + ├── demo + ├── ChildProjectAClass + └── childProjectB + ├── demo + ├── ChildProjectBClass +``` + +These pages are generated after running `dokkaHtmlCollector`: + +![Screenshot for output of dokkaHtmlCollector task](dokkaHtmlCollector-example.png){width=800} + +See our [multi-module project example](https://github.com/Kotlin/dokka/tree/master/examples/gradle/dokka-multimodule-example) +for more details. + +#### Partial tasks + +Each subproject has `Partial` tasks created for it: `dokkaHtmlPartial`,`dokkaGfmPartial`, +and `dokkaJekyllPartial`. + +These tasks are not intended to be run independently, they are called by the parent's +[MultiModule](#multimodule-tasks) task. + +However, you can [configure](#subproject-configuration) `Partial` tasks to customize Dokka for your subprojects. + +> Output generated by `Partial` tasks contains unresolved HTML templates and references, so it cannot be used +> on its own without post-processing done by the parent's [`MultiModule`](#multimodule-tasks) task. +> +{type="warning"} + +> If you want to generate documentation for a single subproject only, use +> [single-project tasks](#single-project-builds). For example, `:subprojectName:dokkaHtml`. +> +{type="note"} + +## Build javadoc.jar + +If you want to publish your library to a repository, you may need to provide a `javadoc.jar` file that contains +API reference documentation of your library. + +For example, if you want to publish to [Maven Central](https://central.sonatype.org/), you +[must](https://central.sonatype.org/publish/requirements/) supply a `javadoc.jar` alongside your project. However, +not all repositories have that rule. + +The Gradle plugin for Dokka does not provide any way to do this out of the box, but it can be achieved with custom Gradle +tasks. One for generating documentation in [HTML](dokka-html.md) format and another one for [Javadoc](dokka-javadoc.md) format: + + + + +```kotlin +tasks.register("dokkaHtmlJar") { + dependsOn(tasks.dokkaHtml) + from(tasks.dokkaHtml.flatMap { it.outputDirectory }) + archiveClassifier.set("html-docs") +} + +tasks.register("dokkaJavadocJar") { + dependsOn(tasks.dokkaJavadoc) + from(tasks.dokkaJavadoc.flatMap { it.outputDirectory }) + archiveClassifier.set("javadoc") +} +``` + + + + +```groovy +tasks.register('dokkaHtmlJar', Jar.class) { + dependsOn(dokkaHtml) + from(dokkaHtml) + archiveClassifier.set("html-docs") +} + +tasks.register('dokkaJavadocJar', Jar.class) { + dependsOn(dokkaJavadoc) + from(dokkaJavadoc) + archiveClassifier.set("javadoc") +} +``` + + + + +> If you publish your library to Maven Central, you can use services like [javadoc.io](https://javadoc.io/) to +> host your library's API documentation for free and without any setup. It takes documentation pages straight +> from the `javadoc.jar`. It works well with the HTML format as demonstrated in +> [this example](https://javadoc.io/doc/com.trib3/server/latest/index.html). +> +{type="tip"} + +## Configuration examples + +Depending on the type of project that you have, the way you apply and configure Dokka differs slightly. However, +[configuration options](#configuration-options) themselves are the same, regardless of the type of your project. + +For simple and flat projects with a single `build.gradle.kts` or `build.gradle` file found in the root of your project, +see [Single-project configuration](#single-project-configuration). + +For a more complex build with subprojects and multiple nested `build.gradle.kts` or `build.gradle` files, +see [Multi-project configuration](#multi-project-configuration). + +### Single-project configuration + +Single-project builds usually have only one `build.gradle.kts` or `build.gradle` file in the root of the project, +and typically have the following structure: + + + + +Single platform: + +```text +. +├── build.gradle.kts +└── src + └── main + └── kotlin + └── HelloWorld.kt +``` + +Multiplatform: + +```text +. +├── build.gradle.kts +└── src + └── commonMain + └── kotlin + └── Common.kt + └── jvmMain + └── kotlin + └── JvmUtils.kt + └── nativeMain + └── kotlin + └── NativeUtils.kt +``` + + + + +Single platform: + +```text +. +├── build.gradle +└── src + └── main + └── kotlin + └── HelloWorld.kt +``` + +Multiplatform: + +```text +. +├── build.gradle +└── src + └── commonMain + └── kotlin + └── Common.kt + └── jvmMain + └── kotlin + └── JvmUtils.kt + └── nativeMain + └── kotlin + └── NativeUtils.kt +``` + + + + +In such projects, you need to apply Dokka and its configuration in the root `build.gradle.kts` or `build.gradle` file. + +You can configure tasks and output formats individually: + + + + +Inside `./build.gradle.kts`: + +```kotlin +plugins { + id("org.jetbrains.dokka") version "%dokkaVersion%" +} + +tasks.dokkaHtml { + outputDirectory.set(buildDir.resolve("documentation/html")) +} + +tasks.dokkaGfm { + outputDirectory.set(buildDir.resolve("documentation/markdown")) +} +``` + + + + +Inside `./build.gradle`: + +```groovy +plugins { + id 'org.jetbrains.dokka' version '%dokkaVersion%' +} + +dokkaHtml { + outputDirectory.set(file("build/documentation/html")) +} + +dokkaGfm { + outputDirectory.set(file("build/documentation/markdown")) +} +``` + + + + +Or you can configure all tasks and output formats at the same time: + + + + +Inside `./build.gradle.kts`: + +```kotlin +import org.jetbrains.dokka.gradle.DokkaTask +import org.jetbrains.dokka.gradle.DokkaTaskPartial +import org.jetbrains.dokka.DokkaConfiguration.Visibility + +plugins { + id("org.jetbrains.dokka") version "%dokkaVersion%" +} + +// Configure all single-project Dokka tasks at the same time, +// such as dokkaHtml, dokkaJavadoc and dokkaGfm. +tasks.withType().configureEach { + dokkaSourceSets.configureEach { + documentedVisibilities.set( + setOf( + Visibility.PUBLIC, + Visibility.PROTECTED, + ) + ) + + perPackageOption { + matchingRegex.set(".*internal.*") + suppress.set(true) + } + } +} +``` + + + + +Inside `./build.gradle`: + +```groovy +import org.jetbrains.dokka.gradle.DokkaTask +import org.jetbrains.dokka.gradle.DokkaTaskPartial +import org.jetbrains.dokka.DokkaConfiguration.Visibility + +plugins { + id 'org.jetbrains.dokka' version '%dokkaVersion%' +} + +// Configure all single-project Dokka tasks at the same time, +// such as dokkaHtml, dokkaJavadoc and dokkaGfm. +tasks.withType(DokkaTask.class) { + dokkaSourceSets.configureEach { + documentedVisibilities.set([ + DokkaConfiguration.Visibility.PUBLIC, + DokkaConfiguration.Visibility.PROTECTED + ]) + + perPackageOption { + matchingRegex.set(".*internal.*") + suppress.set(true) + } + } +} +``` + + + + +### Multi-project configuration + +Gradle's [multi-project builds](https://docs.gradle.org/current/userguide/multi_project_builds.html) are more complex +in structure and configuration. They usually have multiple nested `build.gradle.kts` or `build.gradle` files, and +typically have the following structure: + + + + +```text +. +├── build.gradle.kts +├── settings.gradle.kts +├── subproject-A + └── build.gradle.kts + └── src + └── main + └── kotlin + └── HelloFromA.kt +├── subproject-B + └── build.gradle.kts + └── src + └── main + └── kotlin + └── HelloFromB.kt +``` + + + + +```text +. +├── build.gradle +├── settings.gradle +├── subproject-A + └── build.gradle + └── src + └── main + └── kotlin + └── HelloFromA.kt +├── subproject-B + └── build.gradle + └── src + └── main + └── kotlin + └── HelloFromB.kt +``` + + + + +In this case, there are multiple ways of applying and configuring Dokka. + +#### Subproject configuration + +To configure subprojects in a multi-project build, you need to configure [`Partial`](#partial-tasks) tasks. + +You can configure all subprojects at the same time in the root `build.gradle.kts` or `build.gradle` file, +using Gradle's `allprojects {}` or `subprojects {}` configuration blocks: + + + + +In the root `./build.gradle.kts`: + +```kotlin +import org.jetbrains.dokka.gradle.DokkaTaskPartial + +plugins { + id("org.jetbrains.dokka") version "%dokkaVersion%" +} + +subprojects { + apply(plugin = "org.jetbrains.dokka") + + // configure only the HTML task + tasks.dokkaHtmlPartial { + outputDirectory.set(buildDir.resolve("docs/partial")) + } + + // configure all format tasks at once + tasks.withType().configureEach { + dokkaSourceSets.configureEach { + includes.from("README.md") + } + } +} +``` + + + + +In the root `./build.gradle`: + +```groovy +import org.jetbrains.dokka.gradle.DokkaTaskPartial + +plugins { + id 'org.jetbrains.dokka' version '%dokkaVersion%' +} + +subprojects { + apply plugin: 'org.jetbrains.dokka' + + // configure only the HTML task + dokkaHtmlPartial { + outputDirectory.set(file("build/docs/partial")) + } + + // configure all format tasks at once + tasks.withType(DokkaTaskPartial.class) { + dokkaSourceSets.configureEach { + includes.from("README.md") + } + } +} +``` + + + + +Alternatively, you can apply and configure Dokka within subprojects individually. + +For example, to have specific settings for the `subproject-A` subproject only, you need to apply the following code +inside `./subproject-A/build.gradle.kts`: + + + + +Inside `./subproject-A/build.gradle.kts`: + +```kotlin +apply(plugin = "org.jetbrains.dokka") + +// configuration for subproject-A only. +tasks.dokkaHtmlPartial { + outputDirectory.set(buildDir.resolve("docs/partial")) +} +``` + + + + +Inside `./subproject-A/build.gradle`: + +```groovy +apply plugin: 'org.jetbrains.dokka' + +// configuration for subproject-A only. +dokkaHtmlPartial { + outputDirectory.set(file("build/docs/partial")) +} +``` + + + + +#### Parent project configuration + +If you want to configure something which is universal across all documentation and does not belong to the +subprojects - in other words, it's a property of the parent project - you need to configure the +[`MultiModule`](#multimodule-tasks) tasks. + +For example, if you want to change the name of your project which is used in the header of the HTML documentation, +you need to apply the following inside the root `build.gradle.kts` or `build.gradle` file: + + + + +In the root `./build.gradle.kts` file: + +```kotlin +plugins { + id("org.jetbrains.dokka") version "%dokkaVersion%" +} + +tasks.dokkaHtmlMultiModule { + moduleName.set("WHOLE PROJECT NAME USED IN THE HEADER") +} +``` + + + + +In the root `./build.gradle` file: + +```groovy +plugins { + id 'org.jetbrains.dokka' version '%dokkaVersion%' +} + +dokkaHtmlMultiModule { + moduleName.set("WHOLE PROJECT NAME USED IN THE HEADER") +} +``` + + + + +## Configuration options + +Dokka has many configuration options to tailor your and your reader's experience. + +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. + +See [Configuration examples](#configuration-examples) for more details on where to apply configuration blocks and how. + +### General configuration + +Here is an example of general configuration of any Dokka task, regardless of source set or package: + + + + +```kotlin +import org.jetbrains.dokka.gradle.DokkaTask + +// Note: To configure multi-project builds, you need +// to configure Partial tasks of the subprojects. +// See "Configuration example" section of documentation. +tasks.withType().configureEach { + moduleName.set(project.name) + moduleVersion.set(project.version.toString()) + outputDirectory.set(buildDir.resolve("dokka/$name")) + failOnWarning.set(false) + suppressObviousFunctions.set(true) + suppressInheritedMembers.set(false) + offlineMode.set(false) + + // .. + // s