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 --- mkdocs/src/doc/docs/user_guide/applying/cli.md | 158 +++++++++ mkdocs/src/doc/docs/user_guide/applying/gradle.md | 380 +++++++++++++++++++++ mkdocs/src/doc/docs/user_guide/applying/maven.md | 243 +++++++++++++ mkdocs/src/doc/docs/user_guide/introduction.md | 74 ++++ .../src/doc/docs/user_guide/output-formats/html.md | 112 ++++++ .../doc/docs/user_guide/plugins/android-plugin.md | 8 + .../docs/user_guide/plugins/versioning-plugin.md | 86 +++++ 7 files changed, 1061 insertions(+) create mode 100644 mkdocs/src/doc/docs/user_guide/applying/cli.md create mode 100644 mkdocs/src/doc/docs/user_guide/applying/gradle.md create mode 100644 mkdocs/src/doc/docs/user_guide/applying/maven.md create mode 100644 mkdocs/src/doc/docs/user_guide/introduction.md create mode 100644 mkdocs/src/doc/docs/user_guide/output-formats/html.md create mode 100644 mkdocs/src/doc/docs/user_guide/plugins/android-plugin.md create mode 100644 mkdocs/src/doc/docs/user_guide/plugins/versioning-plugin.md (limited to 'mkdocs/src/doc/docs/user_guide') diff --git a/mkdocs/src/doc/docs/user_guide/applying/cli.md b/mkdocs/src/doc/docs/user_guide/applying/cli.md new file mode 100644 index 00000000..3b02add2 --- /dev/null +++ b/mkdocs/src/doc/docs/user_guide/applying/cli.md @@ -0,0 +1,158 @@ +# Using command line + +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 +``` + +## Configuration options + +Dokka supports the following command line arguments: + +* `-outputDir` - the output directory where the documentation is generated +* `-moduleName` - (required) - module name used as a part of source set ID when declaring dependent source sets +* `-cacheRoot` - cache directory to enable package-list caching +* `-pluginsClasspath` - artifacts with Dokka plugins, separated by `;`. At least `dokka-base` and all its dependencies must be added there +* `-pluginsConfiguration` - configuration for plugins in format `fqPluginName=json^^fqPluginName=json...` +* `-offlineMode` - do not resolve package-lists online +* `-failOnWarning` - throw an exception instead of a warning +* `-globalPackageOptions` - per package options added to all source sets +* `-globalLinks` - external documentation links added to all source sets +* `-globalSrcLink` - source links added to all source sets +* `-noSuppressObviousFunctions` - don't suppress obvious functions like default `toString` or `equals` +* `-suppressInheritedMembers` - suppress all inherited members that were not overriden in a given class. Eg. using it you can suppress toString or equals functions but you can't suppress componentN or copy on data class +* `-sourceSet` - (repeatable) - configuration for a single source set. Following this argument, you can pass other arguments: + * `-sourceSetName` - source set name as a part of source set ID when declaring dependent source sets + * `-displayName` - source set name displayed in the generated documentation + * `-src` - list of source files or directories separated by `;` + * `-classpath` - list of directories or .jar files to include in the classpath (used for resolving references) separated by `;` + * `-samples` - list of directories containing sample code (documentation for those directories is not generated but declarations from them can be referenced using the `@sample` tag) separated by `;` + * `-includes` - list of files containing the documentation for the module and individual packages separated by `;` + * `-includeNonPublic` - **Deprecated**, prefer using `documentedVisibilities`. Include protected and private code + * `-documentedVisibilities` - a list of visibility modifiers (separated by `;`) that should be documented. Overrides `includeNonPublic`. Default is `PUBLIC`. Possible values: `PUBLIC`, `PRIVATE`, `PROTECTED`, `INTERNAL` (Kotlin-specific), `PACKAGE` (Java-specific package-private) + * `-skipDeprecated` - if set, deprecated elements are not included in the generated documentation + * `-reportUndocumented` - warn about undocumented members + * `-noSkipEmptyPackages` - create index pages for empty packages + * `-perPackageOptions` - list of package options in format `matchingRegex,-deprecated,-privateApi,+reportUndocumented;+visibility:PRIVATE;matchingRegex, ...`, separated by `;` + * `-links` - list of external documentation links in format `url^packageListUrl^^url2...`, separated by `;` + * `-srcLink` - mapping between a source directory and a Web site for browsing the code in format `=[#lineSuffix]` + * `-noStdlibLink` - disable linking to online kotlin-stdlib documentation + * `-noJdkLink` - disable linking to online JDK documentation + * `-jdkVersion` - version of JDK to use for linking to JDK JavaDoc + * `-analysisPlatform` - platform used for analysis, see the [Platforms](#platforms) section + * `-dependentSourceSets` - list of dependent source sets in format `moduleName/sourceSetName`, separated by `;` +* `-loggingLevel` - one of `DEBUG`, `PROGRESS`, `INFO`, `WARN`, `ERROR`. Defaults to `DEBUG`. Please note that this argument can't be passed in JSON. + + +You can also use a JSON file with Dokka configuration: + ``` + java -jar + ``` + +## Applying plugins +To apply a Dokka plugin you have to provide it and all its dependencies in the `pluginsClasspath` parameter + +## Base plugin + +Using CLI runner to generate default documentation requires providing all dependencies manually on classpath. +For Base plugins these are: + +* [dokka-base.jar](https://mvnrepository.com/artifact/org.jetbrains.dokka/dokka-base) +* [dokka-analysis.jar](https://mvnrepository.com/artifact/org.jetbrains.dokka/dokka-analysis) +* [kotlin-analysis-compiler.jar](https://mvnrepository.com/artifact/org.jetbrains.dokka/kotlin-analysis-compiler) +* [kotlin-analysis-intellij.jar](https://mvnrepository.com/artifact/org.jetbrains.dokka/kotlin-analysis-intellij) +* [kotlinx-html-jvm.jar](https://mvnrepository.com/artifact/org.jetbrains.kotlinx/kotlinx-html-jvm?repo=kotlinx) + +All of them are published on maven central. Another dependencies of Base plugin (e.g. `kotlinx-coroutines-core` and so on) are already included in `dokka-cli.jar`. +To get them on classpath one should add them via `pluginsClasspath` argument, e. g. +``` +java -jar dokka-cli.jar -pluginsClasspath "dokka-base.jar;dokka-analysis.jar;kotlin-analysis-compiler.jar;kotlin-analysis-intellij.jar;kotlinx-html-jvm.jar" ... +``` + +## Example using JSON + +To run Dokka with JSON configuration: +``` +java -jar dokka-cli.jar dokkaConfiguration.json +``` +Option values of JSON correspond to [Gradle ones](../../gradle/usage#configuration-options). +The content of JSON file ```dokkaConfiguration.json```: +```json +{ + "moduleName": "Dokka Example", + "moduleVersion": null, + "outputDir": "build/dokka/html", + "cacheRoot": null, + "offlineMode": false, + "sourceSets": [ + { + "displayName": "jvm", + "sourceSetID": { + "scopeId": ":dokkaHtml", + "sourceSetName": "main" + }, + "classpath": [ + "libs/kotlin-stdlib-1.7.20.jar", + "libs/kotlin-stdlib-common-1.7.20.jar" + ], + "sourceRoots": [ + "/home/Vadim.Mishenev/dokka/examples/cli/src/main/kotlin" + ], + "dependentSourceSets": [], + "samples": [], + "includes": [ + "Module.md" + ], + "includeNonPublic": false, + "documentedVisibilities": ["PUBLIC", "PRIVATE", "PROTECTED", "INTERNAL", "PACKAGE"], + "reportUndocumented": false, + "skipEmptyPackages": true, + "skipDeprecated": false, + "jdkVersion": 8, + "sourceLinks": [ + { + "localDirectory": "/home/Vadim.Mishenev/dokka/examples/cli/src/main/kotlin", + "remoteUrl": "https://github.com/Kotlin/dokka/tree/master/examples/gradle/dokka-gradle-example/src/main/kotlin", + "remoteLineSuffix": "#L" + } + ], + "perPackageOptions": [], + "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" + } + ], + "noStdlibLink": false, + "noJdkLink": false, + "suppressedFiles": [], + "analysisPlatform": "jvm" + } + ], + "pluginsClasspath": [ + "plugins/dokka-base-1.7.20.jar", + "libs/kotlinx-html-jvm-0.7.3.jar", + "libs/dokka-analysis-1.7.20.jar", + "libs/kotlin-analysis-intellij-1.7.20.jar", + "libs/kotlin-analysis-compiler-1.7.20.jar" + ], + "pluginsConfiguration": [ + { + "fqPluginName": "org.jetbrains.dokka.base.DokkaBase", + "serializationFormat": "JSON", + "values": "{\"separateInheritedMembers\":false,\"footerMessage\":\"© 2021 Copyright\"}" + } + ], + "modules": [], + "failOnWarning": false, + "delayTemplateSubstitution": false, + "suppressObviousFunctions": true, + "includes": [], + "suppressInheritedMembers": false +} +``` diff --git a/mkdocs/src/doc/docs/user_guide/applying/gradle.md b/mkdocs/src/doc/docs/user_guide/applying/gradle.md new file mode 100644 index 00000000..435824f9 --- /dev/null +++ b/mkdocs/src/doc/docs/user_guide/applying/gradle.md @@ -0,0 +1,380 @@ +# Using the Gradle plugin + +!!! important + If you are upgrading from 0.10.x to a current release of Dokka, please have a look at our + [migration guide](https://github.com/Kotlin/dokka/blob/master/runners/gradle-plugin/MIGRATION.md) + +### Supported versions +Dokka should work on gradle newer than 5.6 + +### Setup + +The preferred way is to use `plugins` block. + +build.gradle.kts: +```kotlin +plugins { + id("org.jetbrains.dokka") version "1.7.20" +} + +repositories { + mavenCentral() +} +``` + +You can also use the legacy plugin application method with `buildscript` block. +Note that by using the `buildscript` way type-safe accessors are not available in Gradle Kotlin DSL, +eg. you'll have to use `named("dokkaHtml")` instead of `dokkaHtml`: + +```kotlin +buildscript { + dependencies { + classpath("org.jetbrains.dokka:dokka-gradle-plugin:${dokka_version}") + } +} + +apply(plugin="org.jetbrains.dokka") +``` + +The plugin adds `dokkaHtml`, `dokkaJavadoc`, `dokkaGfm` and `dokkaJekyll` tasks to the project. + +Each task corresponds to one output format, so you should run `dokkaGfm` when you want to have a documentation in `GFM` format. +Output formats are explained in [the introduction](../introduction.md#output-formats) + +If you encounter any problems when migrating from older versions of Dokka, please see the [FAQ](https://github.com/Kotlin/dokka/wiki/faq). + +Minimal configuration (with custom output directory only): + +Kotlin DSL +```kotlin +tasks.dokkaHtml.configure { + outputDirectory.set(buildDir.resolve("dokka")) +} +``` + + +Groovy DSL +```groovy +dokkaHtml { + outputDirectory.set(file("${buildDir}/dokka")) +} +``` + +!!! note + Dokka extracts the information about sourcesets from the Kotlin Gradle plugin. + Therefore, if you are using Dokka in a [precompiled script plugin](https://docs.gradle.org/current/userguide/custom_plugins.html#sec:precompiled_plugins), + you will have to add a depencency to the Kotlin Gradle Plugin as well + (`implementation(kotlin("gradle-plugin", ""))` resp. `implementation("org.jetbrains.kotlin:kotlin-gradle-plugin:")`). + +## Configuration options + +Dokka documents single-platform as well as multi-platform projects. +Most of the configuration options are set per one source set. +The available configuration options are shown below: + +```kotlin +import org.jetbrains.dokka.DokkaConfiguration +import org.jetbrains.dokka.gradle.DokkaTask + +val dokkaHtml by getting(DokkaTask::class) { + outputDirectory.set(buildDir.resolve("dokka")) + + // Set module name displayed in the final output + moduleName.set("moduleName") + + // Use default or set to custom path to cache directory + // to enable package-list caching + // When this is set to default, caches are stored in $USER_HOME/.cache/dokka + cacheRoot.set(file("default")) + + // Suppress obvious functions like default toString or equals. Defaults to true + suppressObviousFunctions.set(false) + + // Suppress all inherited members that were not overriden in a given class. + // Eg. using it you can suppress toString or equals functions but you can't suppress componentN or copy on data class. To do that use with suppressObviousFunctions + // Defaults to false + suppressInheritedMembers.set(true) + + // Used to prevent resolving package-lists online. When this option is set to true, only local files are resolved + offlineMode.set(false) + + dokkaSourceSets { + configureEach { // Or source set name, for single-platform the default source sets are `main` and `test` + + // Used when configuring source sets manually for declaring which source sets this one depends on + dependsOn("otherSourceSetName") + + // Used to remove a source set from documentation, test source sets are suppressed by default + suppress.set(false) + + // Deprecated. Prefer using documentedVisibilities. + includeNonPublic.set(false) + + // A set of visibility modifiers that should be documented + // If set by user, overrides includeNonPublic. Default is PUBLIC + documentedVisibilities.set( + setOf( + DokkaConfiguration.Visibility.PUBLIC, // Same for both Kotlin and Java + DokkaConfiguration.Visibility.PRIVATE, // Same for both Kotlin and Java + DokkaConfiguration.Visibility.PROTECTED, // Same for both Kotlin and Java + DokkaConfiguration.Visibility.INTERNAL, // Kotlin-specific internal modifier + DokkaConfiguration.Visibility.PACKAGE, // Java-specific package-private visibility + ) + ) + + // Do not output deprecated members. Applies globally, can be overridden by packageOptions + skipDeprecated.set(false) + + // Emit warnings about not documented members. Applies globally, also can be overridden by packageOptions + reportUndocumented.set(true) + + // Do not create index pages for empty packages + skipEmptyPackages.set(true) + + // This name will be shown in the final output + displayName.set("JVM") + + // Platform used for code analysis. See the "Platforms" section of this readme + platform.set(org.jetbrains.dokka.Platform.jvm) + + // Property used for manual addition of files to the classpath + // This property does not override the classpath collected automatically but appends to it + classpath.from(file("libs/dependency.jar")) + + // List of files with module and package documentation + // https://kotlinlang.org/docs/reference/kotlin-doc.html#module-and-package-documentation + includes.from("packages.md", "extra.md") + + // List of files or directories containing sample code (referenced with @sample tags) + samples.from("samples/basic.kt", "samples/advanced.kt") + + // By default, sourceRoots are taken from Kotlin Plugin and kotlinTasks, following roots will be appended to them + // Repeat for multiple sourceRoots + sourceRoots.from(file("src")) + + // Specifies the location of the project source code on the Web. + // If provided, Dokka generates "source" links for each declaration. + // Repeat for multiple mappings + sourceLink { + // Unix based directory relative path to the root of the project (where you execute gradle respectively). + localDirectory.set(file("src/main/kotlin")) + + // URL showing where the source code can be accessed through the web browser + remoteUrl.set(java.net.URL( + "https://github.com/cy6erGn0m/vertx3-lang-kotlin/blob/master/src/main/kotlin")) + // Suffix which is used to append the line number to the URL. Use #L for GitHub + remoteLineSuffix.set("#L") + } + + // Used for linking to JDK documentation + jdkVersion.set(8) + + // Disable linking to online kotlin-stdlib documentation + noStdlibLink.set(false) + + // Disable linking to online JDK documentation + noJdkLink.set(false) + + // Disable linking to online Android documentation (only applicable for Android projects) + noAndroidSdkLink.set(false) + + // Allows linking to documentation of the project"s dependencies (generated with Javadoc or Dokka) + // Repeat for multiple links + externalDocumentationLink { + // Root URL of the generated documentation to link with. The trailing slash is required! + url.set(URL("https://example.com/docs/")) + + // If package-list file is located in non-standard location + // packageListUrl = URL("file:///home/user/localdocs/package-list") + } + + // Allows to customize documentation generation options on a per-package basis + // Repeat for multiple packageOptions + // If multiple packages match the same matchingRegex, the longest matchingRegex will be used + perPackageOption { + // will match kotlin and all sub-packages of it + matchingRegex.set("kotlin($|\\.).*") + + // All options are optional + skipDeprecated.set(false) + reportUndocumented.set(true) // Emit warnings about not documented members + includeNonPublic.set(false) // Deprecated, prefer using documentedVisibilities + + // Visibilities that should be included in the documentation + // If set by user, overrides includeNonPublic. Default is PUBLIC + documentedVisibilities.set( + setOf( + DokkaConfiguration.Visibility.PUBLIC, // Same for both Kotlin and Java + DokkaConfiguration.Visibility.PRIVATE, // Same for both Kotlin and Java + DokkaConfiguration.Visibility.PROTECTED, // Same for both Kotlin and Java + DokkaConfiguration.Visibility.INTERNAL, // Kotlin-specific internal modifier + DokkaConfiguration.Visibility.PACKAGE, // Java-specific package-private visibility + ) + ) + } + // Suppress a package + perPackageOption { + matchingRegex.set(""".*\.internal.*""") // will match all .internal packages and sub-packages + suppress.set(true) + } + + // Include generated files in documentation + // By default Dokka will omit all files in folder named generated that is a child of buildDir + suppressGeneratedFiles.set(false) + } + // Configures a plugin separately from the global configuration + pluginConfiguration{ + // values + } + } +} +``` + +## Multiplatform +Dokka supports single-platform and multi-platform projects using source sets abstraction. For most mutli-platform projects +you should assume that Dokka's source sets correspond to Kotlin plugin's source sets. All source sets are by default registered +and configured automatically although test source sets are suppressed + +Kotlin +```kotlin +kotlin { // Kotlin Multiplatform plugin configuration + jvm() + js("customName") +} + +tasks.withType().configureEach { + // custom output directory + outputDirectory.set(buildDir.resolve("dokka")) + + dokkaSourceSets { + named("customNameMain") { // The same name as in Kotlin Multiplatform plugin, so the sources are fetched automatically + includes.from("packages.md", "extra.md") + samples.from("samples/basic.kt", "samples/advanced.kt") + } + + register("differentName") { // Different name, so source roots must be passed explicitly + displayName.set("JVM") + platform.set(org.jetbrains.dokka.Platform.jvm) + sourceRoots.from(kotlin.sourceSets.getByName("jvmMain").kotlin.srcDirs) + sourceRoots.from(kotlin.sourceSets.getByName("commonMain").kotlin.srcDirs) + } + } +} +``` + +!!! note + If you want to share the configuration between source sets, you can use Gradle's `configureEach` + +## Applying plugins +Dokka plugin creates Gradle configuration for each output format in the form of `dokka${format}Plugin` (or `dokka${format}PartialPlugin` for multi-module tasks) : + +```kotlin +dependencies { + dokkaHtmlPlugin("org.jetbrains.dokka:kotlin-as-java-plugin:1.7.20") +} +``` + +You can also create a custom Dokka task and add plugins directly inside: + +```kotlin +val customDokkaTask by creating(DokkaTask::class) { + dependencies { + plugins("org.jetbrains.dokka:kotlin-as-java-plugin:1.7.20") + } +} +``` + +!!! important + Please note that `dokkaJavadoc` task will properly document only single `jvm` source set + +To generate the documentation, use the appropriate `dokka${format}` Gradle task: + +```bash +./gradlew dokkaHtml +``` + +Some plugins can be configured separately using a plugin class and configuration class. For example: + +```kotlin +import org.jetbrains.dokka.base.DokkaBase +import org.jetbrains.dokka.base.DokkaBaseConfiguration + +pluginConfiguration { + customAssets = listOf(file("")) + customStyleSheets = listOf(file("")) +} +``` + +Keep in mind, that this only works when using a buildscript (with the configured plugin on classpath) since it is not possible to import plugin's class without it. +For example, you can add `DokkaBase` to gain access to aforementioned configuration: + +```kotlin +buildscript { + dependencies { + // classpath(":") + classpath("org.jetbrains.dokka:dokka-base:1.7.20") + } +} +``` + +If you don't want to use a buildscript or use Kotlin version lower than 1.3.50 you can achieve the same behaviour manually: +```kotlin +pluginsMapConfiguration.set(mapOf("" to """""")) +``` +## Android + +!!! important + Make sure you apply Dokka after `com.android.library` and `kotlin-android`. + +```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") +``` + +```kotlin +dokkaHtml.configure { + dokkaSourceSets { + named("main") { + noAndroidSdkLink.set(false) + } + } +} +``` + +## Multi-module projects +For documenting Gradle multi-module projects, you can use `dokka${format}MultiModule` tasks. +Dokka plugin adds `dokkaHtmlMultiModule`, `dokkaGfmMultiModule` and `dokkaJekyllMultiModule` tasks to +all Gradle parent projects (all projects that have some child projects) as well as +`dokkaHtmlPartial`, `dokkaGfmPartial` and `dokkaJekyllPartial` to all projects that have a parent. +If you want eg. to add an external link to some dependency you should do so in respective `dokka${format}Partial` tasks, +or configure them all at once using the `subprojects` block and `configureEach` method. + +```kotlin +tasks.dokkaHtmlMultiModule.configure { + outputDirectory.set(buildDir.resolve("dokkaCustomMultiModuleOutput")) +} +``` + +`DokkaMultiModule` depends on all Dokka tasks in the subprojects named `dokka${format}Partial`, runs them, and creates a top-level page +with links to all generated (sub)documentations. It is possible to configure each of them: +```kotlin +tasks.dokkaHtmlPartial.configure { + failOnWarning.set(true) +} +``` + +## Example projects + +Please see the [Dokka Gradle single module example project](https://github.com/Kotlin/dokka/tree/master/examples/gradle/dokka-gradle-example) or [multimodule](https://github.com/Kotlin/dokka/tree/master/examples/gradle/dokka-multimodule-example) for an example. + +Also see [generated documentation](https://Kotlin.github.io/dokka/examples/dokka-gradle-example/html) in `HTML` format. diff --git a/mkdocs/src/doc/docs/user_guide/applying/maven.md b/mkdocs/src/doc/docs/user_guide/applying/maven.md new file mode 100644 index 00000000..cde6e927 --- /dev/null +++ b/mkdocs/src/doc/docs/user_guide/applying/maven.md @@ -0,0 +1,243 @@ +# Using the Maven plugin + +!!! note + Dokka Maven plugin does not support multi-platform projects. + +Minimal Maven configuration is + +```xml + + org.jetbrains.dokka + dokka-maven-plugin + ${dokka.version} + + + pre-site + + dokka + + + + +``` + +By default files will be generated in `target/dokka`. + +The following goals are provided by the plugin: + +* `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 + +## Configuration options + +The available configuration options are shown below: + +```xml + + org.jetbrains.dokka + dokka-maven-plugin + ${dokka.version} + + + pre-site + + dokka + + + + + + + false + + + data + + + some/out/dir + + + + default + + + + false + + + + + packages.md + extra.md + + + + + + PUBLIC + PRIVATE + PROTECTED + INTERNAL + PACKAGE + + + + + src/test/samples + + + + false + + + + + true + + + 6 + + + false + + true + + true + + + + src/main/kotlin + + + + + + src/main/kotlin + + JVM + + + + + + + + ${project.basedir}/src/main/kotlin + + https://github.com/cy6erGn0m/vertx3-lang-kotlin/blob/master/src/main/kotlin + + #L + + + + + false + + + false + + + + + + https://example.com/docs/ + + + + + + + + + + kotlin($|\.).* + + + false + + + true + + + false + + + + + PUBLIC + PRIVATE + PROTECTED + INTERNAL + PACKAGE + + + + + + + + org.jetbrains.dokka + gfm-plugin + ${dokka.version} + + + + + + + + + + + + +``` + +## Applying plugins +You can add plugins inside the `dokkaPlugins` block: + +```xml + + org.jetbrains.dokka + dokka-maven-plugin + ${dokka.version} + + + pre-site + + dokka + + + + + + + org.jetbrains.dokka + kotlin-as-java-plugin + ${dokka.version} + + + + +``` + +Some plugins can be configured separately using plugin's fully qualified name. For example: + +```xml + + + + + + + + + + +``` + +## Example project + +Please see the [Dokka Maven example project](https://github.com/Kotlin/dokka/tree/master/examples/maven) for an example. diff --git a/mkdocs/src/doc/docs/user_guide/introduction.md b/mkdocs/src/doc/docs/user_guide/introduction.md new file mode 100644 index 00000000..cb263ebe --- /dev/null +++ b/mkdocs/src/doc/docs/user_guide/introduction.md @@ -0,0 +1,74 @@ +# Introduction + +## Plugins +Dokka can be customized with plugins. Each output format is internally a plugin. +Additionally, `kotlin-as-java` plugin can be used to generate documentation as seen from Java perspective. +Currently maintained plugins are: + +* `dokka-base` - the main plugin needed to run Dokka, contains html format +* `gfm-plugin` - configures `GFM` output format +* `jekyll-plugin` - configures `Jekyll` output format +* `javadoc-plugin` - configures `Javadoc` output format, automatically applies `kotlin-as-java-plugin` +* `kotlin-as-java-plugin` - translates Kotlin definitions to Java +* `android-documentation-plugin` - provides android specific enhancements like `@hide` support + +Please see the usage instructions for each build system on how to add plugins to Dokka. + +## Source sets +Dokka generates documentation based on source sets. + +For single-platform & multi-platform projects, source sets are the same as in Kotlin plugin: + + * One source set for each platform, eg. `jvmMain` or `jsMain`; + * One source set for each common source set, eg. the default `commonMain` and custom ones like `jsAndJvmMain`. + +When configuring multi-platform projects manually (eg. in the CLI or in Gradle without the Kotlin Gradle Plugin) +source sets must declare their dependent source sets. +Eg. in the following Kotlin plugin configuration: + +* `jsMain` and `jvmMain` both depend on `commonMain` (by default and transitively) and `jsAndJvmMain`; +* `linuxX64Main` only depends on `commonMain`. + +```kotlin +kotlin { // Kotlin plugin configuration + jvm() + js() + linuxX64() + + sourceSets { + val commonMain by getting {} + val jvmAndJsSecondCommonMain by creating { dependsOn(commonMain) } + val jvmMain by getting { dependsOn(jvmAndJsSecondCommonMain) } + val jsMain by getting { dependsOn(jvmAndJsSecondCommonMain) } + val linuxX64Main by getting { dependsOn(commonMain) } + } +} +``` + +## Output formats + Dokka documents Java classes as seen in Kotlin by default, with javadoc format being the only exception. + + * `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 + +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: + +```kotlin +dependencies{ + implementation("...") + dokkaGfmPlugin("org.jetbrains.dokka:kotlin-as-java-plugin:${dokka-version}") +} +``` + +## Platforms + +Each Dokka source set is analyzed for a specific platform. The platform should be extracted automatically from the Kotlin plugin. +In case of a manual source set configuration, you have to select one of the following: + + * `jvm` + * `js` + * `native` + * `common` diff --git a/mkdocs/src/doc/docs/user_guide/output-formats/html.md b/mkdocs/src/doc/docs/user_guide/output-formats/html.md new file mode 100644 index 00000000..9a80a5d2 --- /dev/null +++ b/mkdocs/src/doc/docs/user_guide/output-formats/html.md @@ -0,0 +1,112 @@ +# Configuration specific to HTML format + +## Prerequisites + +Dokka's HTML format requires a web server to view documentation correctly. +This can be achieved by using the one that is build in IntelliJ or providing your own. +If this requisite is not fulfilled Dokka with fail to load navigation pane and search bars. + +!!! important + Concepts specified below apply only to configuration of the Base Plugin (that contains HTML format) + and needs to be applied via pluginsConfiguration and not on the root one. + +## Modifying assets + +It is possible to change static assets that are used to generate dokka's HTML. +Currently, user can modify: + + * customAssets + * customStyleSheets + +Every file provided in those values will be applied to **every** page. + +Dokka uses 4 stylesheets: + +* `style.css` - main css file responsible for styling the page +* `jetbrains-mono.css` - fonts used across dokka +* `logo-styles.css` - logo styling +* [`prism.css`](https://github.com/Kotlin/dokka/blob/master/plugins/base/src/main/resources/dokka/styles/prism.css) - code highlighting + +Also, it uses js scripts. The actual ones are [here](https://github.com/Kotlin/dokka/tree/master/plugins/base/src/main/resources/dokka/scripts). +User can choose to add or override those files - stylesheets and js scripts. +Resources will be overridden when in `pluginConfiguration` block there is a resource with the same name. + +## Modifying footer + +Dokka supports custom messages in the footer via `footerMessage` string property on base plugin configuration. +Keep in mind that this value will be passed exactly to the output HTML, so it has to be valid and escaped correctly. + +## Separating inherited members + +By setting a boolean property `separateInheritedMembers` dokka will split inherited members (like functions, properties etc.) +from ones declared in viewed class. Separated members will have it's own tabs on the page. + +## Merging declarations with name clashing + +By setting a boolean property `mergeImplicitExpectActualDeclarations` dokka will merge declarations that do not have `expect`/`actual` keywords but have the same fully qualified name. +The declarations will be displayed on one page. +By default, it is disabled. The page names of such declaration have a prefix that is the name of source set. + +### Examples +In order to override a logo and style it accordingly a css file named `logo-styles.css` is needed: +```css +.library-name a { + position: relative; + --logo-width: 100px; + margin-left: calc(var(--logo-width) + 5px); +} + +.library-name a::before { + content: ''; + background: url("https://upload.wikimedia.org/wikipedia/commons/9/9d/Ubuntu_logo.svg") center no-repeat; + background-size: contain; + position: absolute; + width: var(--logo-width); + height: 50px; + top: -18px; + left: calc(-1 * var(--logo-width) - 5px); + /* other styles required to make your page pretty */ +} +``` + + +For build system specific instructions please visit dedicated pages: [gradle](../applying/gradle.md#applying-plugins), [maven](../applying/maven.md#applying-plugins) and [cli](../applying/cli.md#configuration-options) + +## Custom HTML pages + +Templates are taken from the folder that is defined by the `templatesDir` property. +To customize HTML output, you can use the [default template](https://github.com/Kotlin/dokka/blob/master/plugins/base/src/main/resources/dokka/templates) as a starting point. + +!!! note + To change page assets, you can set properties `customAssets` and `customStyleSheets`. + Assets are handled by Dokka itself, not FreeMaker. + +There is a template file with predefined name `base.ftl`. It defines general design of all pages to render. +`base.ftl` can import another templates that can be set by user as well: + +* `includes/header.ftl` +* `includes/footer.ftl` +* `includes/page_metadata.ftl` +* `includes/source_set_selector.ftl`. + +If `templatesDir` is defined, Dokka will find a template file there. +If the file is not found, a default one will be used. + +Variables given below are available to the template: + +* `${pageName}` - the page name +* `${footerMessage}` - text that is set by the `footerMessage` property +* `${sourceSets}` - a nullable list of source sets, only for multi-platform pages. Each source set has `name`, `platfrom` and `filter` properties. + +Also, Dokka-defined [directives](https://freemarker.apache.org/docs/ref_directive_userDefined.html) can be used: + +* `<@content/>` - main content +* `<@resources/>` - scripts, stylesheets +* `<@version/>` - version ([versioning-plugin](../plugins/versioning-plugin.md) will replace this with a version navigator) +* `<@template_cmd name="...""> ...` - is used for variables that depend on the root project (such `pathToRoot`, `projectName`). They are available only inside the directive. This is processed by a multi-module task that assembles partial outputs from modules. + Example: + ``` + <@template_cmd name="projectName"> + ${projectName} + + ``` diff --git a/mkdocs/src/doc/docs/user_guide/plugins/android-plugin.md b/mkdocs/src/doc/docs/user_guide/plugins/android-plugin.md new file mode 100644 index 00000000..d52c2e5a --- /dev/null +++ b/mkdocs/src/doc/docs/user_guide/plugins/android-plugin.md @@ -0,0 +1,8 @@ +# Android documentation plugin + +Android documentation plugin aims to improve the documentation on android platform. + +### Features: + +* `@hide` support - `@hide` javadoc tag is an equivalent of `@suppress` tag in kdoc. It hides certain entry from being + displayed in the documentation. diff --git a/mkdocs/src/doc/docs/user_guide/plugins/versioning-plugin.md b/mkdocs/src/doc/docs/user_guide/plugins/versioning-plugin.md new file mode 100644 index 00000000..876ec436 --- /dev/null +++ b/mkdocs/src/doc/docs/user_guide/plugins/versioning-plugin.md @@ -0,0 +1,86 @@ +# Versioning plugin + +Versioning plugin aims to provide users with ability to create a versioned documentation. +Therefore, users of the documentation can view different versions of the documentation by going to the main page and change versions. + +Versioning can be configured using: + +* version - a string value representing a version that should be displayed in the dropdown. +* olderVersionsDir - an optional file that represents the parent directory containing folders with previous Dokka outputs. +* olderVersions - an optional list of directories, each containing a previous Dokka output. Used after the contents of + `olderVersionsDir` + (if it's specified). +* versionsOrdering - an optional list of strings representing the ordering of versions that should be visible. + By default, Dokka will try to use semantic versioning to create such ordering. +* renderVersionsNavigationOnAllPages - a bool value. + By default, Dokka renders a versions navigation on all pages. + +!!! note + You should enable the plugin in all submodules to render a versions navigation on all pages. + +Above configuration should be placed under the `pluginsConfiguration` block specific for your build tool. +Configuration object is named `org.jetbrains.dokka.versioning.VersioningConfiguration`. + + +### Directory structure required + +If you pass previous versions using `olderVersionsDir`, a particular directory structure is required: + +``` +. +└── older_versions_dir + └── 1.4.10 + ├── + └── 1.4.20 + ├── + ... +``` + +As can be seen on the diagram, `olderVersionsDir` should be a parent directory of previous output directories. + +This can be avoided by manually specifying each past output directory with `olderVersions`, or they can be used +together. + +`olderVersions` directories need to contain a past Dokka output. For the above example, you would pass +`older_versions_dir/1.4.10, older_versions_dir/1.4.20`. + +!!! note + The previously documentations should be generated with the versioning plugin. + +### Example + +Versioning plugin in gradle can be configured in 2 ways: + +* by manually adding the versioning plugin to classpath and using `pluginsConfiguration` + +* by using `pluginsMapConfiguration` and adding the configuration serialized as json under the `org.jetbrains.dokka.versioning.VersioningPlugin` key. + + +If you choose the first method the configuration may look like this: + +```kotlin +buildscript { + dependencies { + classpath("org.jetbrains.dokka:versioning-plugin:") + } +} + +... + +pluginConfiguration { + version = "1.0" + olderVersionsDir = projectDir.resolve("olderVersionsDir") +} +``` + +Alternatively, without adding plugin to classpath: + +```kotlin +pluginsMapConfiguration.set(mapOf("org.jetbrains.dokka.versioning.VersioningPlugin" to """{ "version": "1.0" }""")) +``` + +Please consult the [Gradle documentation](../applying/gradle.md#applying-plugins) for more information about configuring Dokka with this build tool. + +Please see the [Dokka Gradle versioning multi modules example project](https://github.com/Kotlin/dokka/tree/master/examples/gradle/dokka-versioning-multimodule-example). + +Also see the [generated documentation](https://Kotlin.github.io/dokka/examples/dokka-versioning-multimodule-example/htmlMultiModule). -- cgit