diff options
| author | Ignat Beresnev <ignat.beresnev@jetbrains.com> | 2023-01-10 13:14:43 +0100 |
|---|---|---|
| committer | GitHub <noreply@github.com> | 2023-01-10 13:14:43 +0100 |
| commit | 7544a215fb580ae0c47d1f397334f150d1a1ec65 (patch) | |
| tree | a30aa62c827e3ba88a498a7406ac57fa7334b270 /docs | |
| parent | 2161c397e1b1aadcf3d39c8518258e9bdb2b431a (diff) | |
| download | dokka-7544a215fb580ae0c47d1f397334f150d1a1ec65.tar.gz dokka-7544a215fb580ae0c47d1f397334f150d1a1ec65.tar.bz2 dokka-7544a215fb580ae0c47d1f397334f150d1a1ec65.zip | |
Revise documentation (#2728)
Co-authored-by: Sarah Haggarty <sarahhaggarty@users.noreply.github.com>
Diffstat (limited to 'docs')
47 files changed, 4076 insertions, 2795 deletions
diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 00000000..686c95bd --- /dev/null +++ b/docs/README.md @@ -0,0 +1,9 @@ +# Dokka documentation + +This folder contains the Dokka documentation that is available on [kotlinlang.org](https://kotlinlang.org/). + +Our documentation is written in Markdown format with some domain specific language (DSL) constructs that are used at +JetBrains. + +If you wish to contribute to the documentation, please read through +[Kotlin documentation guidelines](https://docs.google.com/document/d/1mUuxK4xwzs3jtDGoJ5_zwYLaSEl13g_SuhODdFuh2Dc/edit). diff --git a/docs/build.gradle.kts b/docs/build.gradle.kts deleted file mode 100644 index 1a93d550..00000000 --- a/docs/build.gradle.kts +++ /dev/null @@ -1,3 +0,0 @@ -plugins { - id("ru.vyarus.mkdocs") version "2.3.0" -} diff --git a/docs/cfg/buildprofiles.xml b/docs/cfg/buildprofiles.xml new file mode 100644 index 00000000..86c3ad59 --- /dev/null +++ b/docs/cfg/buildprofiles.xml @@ -0,0 +1,10 @@ +<?xml version="1.0" encoding="UTF-8"?> + +<buildprofiles> + <variables> + <enable-browser-edits>true</enable-browser-edits> + <browser-edits-url>https://github.com/Kotlin/dokka/edit/master/docs/</browser-edits-url> + <allow-indexable-eaps>true</allow-indexable-eaps> + </variables> + <build-profile product="kl"/> +</buildprofiles> diff --git a/docs/dokka.tree b/docs/dokka.tree new file mode 100644 index 00000000..73ac277e --- /dev/null +++ b/docs/dokka.tree @@ -0,0 +1,24 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE product-profile + SYSTEM "https://resources.jetbrains.com/stardust/product-profile.dtd"> + +<product-profile id="kl" + name="dokka" + start-page="dokka-introduction.md"> + + <chunk include-id="dokka"> + <toc-element id="dokka-introduction.md"/> + <toc-element id="dokka-get-started.md"/> + <toc-element toc-title="Run Dokka"> + <toc-element id="dokka-gradle.md"/> + <toc-element id="dokka-maven.md"/> + <toc-element id="dokka-cli.md"/> + </toc-element> + <toc-element toc-title="Output formats"> + <toc-element id="dokka-html.md"/> + <toc-element id="dokka-markdown.md"/> + <toc-element id="dokka-javadoc.md"/> + </toc-element> + <toc-element id="dokka-plugins.md"/> + </chunk> +</product-profile> diff --git a/docs/images/dokkaHtmlCollector-example.png b/docs/images/dokkaHtmlCollector-example.png Binary files differnew file mode 100644 index 00000000..5bd74d8d --- /dev/null +++ b/docs/images/dokkaHtmlCollector-example.png diff --git a/docs/images/dokkaHtmlMultiModule-example.png b/docs/images/dokkaHtmlMultiModule-example.png Binary files differnew file mode 100644 index 00000000..f5091f56 --- /dev/null +++ b/docs/images/dokkaHtmlMultiModule-example.png diff --git a/docs/images/javadoc-format-example.png b/docs/images/javadoc-format-example.png Binary files differnew file mode 100644 index 00000000..45ac585c --- /dev/null +++ b/docs/images/javadoc-format-example.png diff --git a/docs/images/versioning-plugin-example.png b/docs/images/versioning-plugin-example.png Binary files differnew file mode 100644 index 00000000..cd02c558 --- /dev/null +++ b/docs/images/versioning-plugin-example.png diff --git a/docs/project.ihp b/docs/project.ihp new file mode 100644 index 00000000..f9ab9b9e --- /dev/null +++ b/docs/project.ihp @@ -0,0 +1,14 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE ihp SYSTEM "https://resources.jetbrains.com/stardust/ihp.dtd"> + +<ihp version="2.0"> +<!-- <categories src="categories.list"/>--> + <module name="dokka"/> + <topics dir="topics"/> + <images dir="images"/> + <vars src="vars.list"/> + <product src="dokka.tree" version="%dokkaVersion%" /> + <settings> + <default-property element-name="toc-element" property-name="show-structure-depth" value="2"/> + </settings> +</ihp> diff --git a/docs/src/doc/docs/community/plugins-list.md b/docs/src/doc/docs/community/plugins-list.md deleted file mode 100644 index 6ae8ce4c..00000000 --- a/docs/src/doc/docs/community/plugins-list.md +++ /dev/null @@ -1,160 +0,0 @@ -# Dokka community plugins - -On this page you can find `Dokka` plugins which are supported by both `Dokka` maintainers and community members. - -If you want to add your plugin to this list, get in touch with maintainers via [Slack](../community/slack.md) -or `GitHub`. - -If you want to learn how to develop plugins for `Dokka`, see -[Plugin development](../developer_guide/plugin-development/introduction.md) section. - -## Output Formats - -### Javadoc (Alpha) - -Javadoc plugin adds a `Javadoc` output format that looks like Java's `Javadoc`, but it's for the most part -a lookalike, so you may experience problems if you try to use it with a tool that expects native -`Javadoc` documentation generated by `Java`. - -`Javadoc` plugin does not support multiplatform projects and does not have a multi-module task. - -`Javadoc` plugin is shipped with `Dokka`, so you can start using it right away with one of the following tasks: - -* `dokkaJavadoc` - builds `Javadoc` documentation for single-module projects or for a specific module. -* `dokkaJavadocCollector` - collects generated `Javadoc` documentation from submodules and assembles it together. - -`Javadoc` plugin has its own signature provider that essentially translates `Kotlin` signatures to `Java` ones. - -**This plugin is at its early stages**, so you may experience issues and encounter bugs. Feel free to -[report](https://github.com/Kotlin/dokka/issues/new/choose) any errors you see. - -[Plugin source code on GitHub](https://github.com/Kotlin/dokka/tree/master/plugins/javadoc) - -### GFM (Alpha) - -`GFM` plugins adds the ability to generate documentation in `GitHub flavoured Markdown` format. Supports both -multimodule and multiplatform projects, and is shipped together with `Dokka`, so you can start using it -right away with one of the following tasks: - -* `dokkaGfm` - generate documentation for a non multi-module project or one specific module. -* `dokkaGfmMultiModule` - generate documentation for a multi-module project, assemble it together and - generate navigation page/menu for all the modules. - -Example: - -___ - -//[dokka-debug-kts](#gfm)/[org.jetbrains.dokka.test](#gfm)/[MyClass](#gfm) - -#### MyClass - -[jvm] -class [MyClass](#gfm) - -KDoc that describes this class - -##### Constructors - -| | | -|---|---| -| [MyClass](#gfm) | [jvm]<br>fun [MyClass](#gfm)() | - -##### Functions - -| Name | Summary | -|------------------|---| -| [function](#gfm) | [jvm]<br>fun [function](#gfm)(): [String](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-string/index.html)<br>KDoc comment on top of this function | - -##### Properties - -| Name | Summary | -|---|------------------------------------------------------------------------------------------------------------------------------------------------| -| [property](#gfm) | [jvm]<br>val [property](#gfm): [String](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-string/index.html)<br>KDoc comment for a property | - -___ - -**This plugin is at its early stages**, so you may experience issues and encounter bugs. Feel free to -[report](https://github.com/Kotlin/dokka/issues/new/choose) any errors you see. - -[Plugin source code on GitHub](https://github.com/Kotlin/dokka/tree/master/plugins/gfm) - -### Jekyll (Alpha) - -`Jekyll` plugins adds the ability to generate documentation in `Jekyll flavoured Markdown` format. Supports both -multi-module and multiplatform projects, and is shipped together with `Dokka`, so you can start using it -right away with one of the following tasks: - -* `dokkaJekyll` - generate documentation for a non multi-module project or one specific module. -* `dokkaJekyllMultiModule` - generate documentation for a multi-module project, assemble it together and - generate navigation page/menu for all the modules. - -**This plugin is at its early stages**, so you may experience issues and encounter bugs. Feel free to -[report](https://github.com/Kotlin/dokka/issues/new/choose) any errors you see. - -[Plugin source code on GitHub](https://github.com/Kotlin/dokka/tree/master/plugins/jekyll) - -## Extensions - -### Mathjax - -[MathJax](https://docs.mathjax.org/) allows you to include mathematics in your web pages. `MathJax` plugin -adds the ability to render mathematics from source code comments. - -If `MathJax` plugin encounters `@usesMathJax` `KDoc` tag, it adds `MathJax.js` (ver. 2) with `config=TeX-AMS_SVG` -to generated `HTML` pages. - -Usage example: -```kotlin -/** - * Some math \(\sqrt{3x-1}+(1+x)^2\) - * - * @usesMathJax - */ -class Foo {} -``` - -Which results in: - -{ width="400" } - -[Plugin source code on GitHub](https://github.com/Kotlin/dokka/tree/master/plugins/mathjax) - -### Mermaid - -[Mermaid JS](https://mermaid-js.github.io/mermaid/#/) lets you create diagrams and visualizations using text and code. -`Mermaid` plugin allows rendering such diagrams and visualizations found in source code documentation. - -Usage example: -```kotlin -/** - * See the graph for more details: - * \```mermaid - * graph LR - * A[Christmas] -->|Get money| B(Go shopping) - * B --> C{Let me think} - * C -->|One| D[Laptop] - * C -->|Two| E[iPhone] - * C -->|Three| F[fa:fa-car Car] - * \``` - */ -class CompositeSubscription -``` - -Which results in: - -{ width="700" } - -For more information and examples, see -[Html Mermaid Dokka plugin](https://github.com/glureau/dokka-mermaid) repository on GitHub. - -### Kotlin as Java - -With `Kotlin as Java` plugin applied, all `Kotlin` signatures will be rendered as `Java` signatures. - -For instance, `fun foo(bar: Bar): Baz` will be rendered as `public final Baz foo(Bar bar)`. - -`Kotlin as Java` plugin is published to maven central as a -[separate artifact](https://mvnrepository.com/artifact/org.jetbrains.dokka/kotlin-as-java-plugin): -`org.jetbrains.dokka:kotlin-as-java-plugin:1.7.20`. - -[Plugin source code on GitHub](https://github.com/Kotlin/dokka/tree/master/plugins/kotlin-as-java) diff --git a/docs/src/doc/docs/community/slack.md b/docs/src/doc/docs/community/slack.md deleted file mode 100644 index 290d4a18..00000000 --- a/docs/src/doc/docs/community/slack.md +++ /dev/null @@ -1,7 +0,0 @@ -# Slack channel - -`Dokka` has a dedicated `#dokka` channel in the `Kotlin Community Slack`, where you can ask questions and chat -about using, customizing or contributing to `Dokka`. - -[Follow the instructions](https://surveys.jetbrains.com/s3/kotlin-slack-sign-up) -to get an invite or [connect directly](https://kotlinlang.slack.com). diff --git a/docs/src/doc/docs/developer_guide/architecture/architecture_overview.md b/docs/src/doc/docs/developer_guide/architecture/architecture_overview.md deleted file mode 100644 index fb11f32a..00000000 --- a/docs/src/doc/docs/developer_guide/architecture/architecture_overview.md +++ /dev/null @@ -1,123 +0,0 @@ -# Architecture overview - -Normally, you would think that a tool like `Dokka` simply parses some programming language sources and generates -`HTML` pages for whatever it sees along the way, with little to no abstractions. That would be the simplest and -shortest way to implement an API documentation engine. - -However, it was clear that `Dokka` may need to generate documentation from various sources (not only `Kotlin`), that users -might request additional output formats (like `Markdown`), that users might need additional features like supporting -custom `KDoc` tags or rendering `mermaid.js` diagrams - all these things would require changing a lot of code inside -`Dokka` itself if all solutions were hardcoded. - -For this reason, `Dokka` was built from the ground up to be easily extensible and customizable by adding several layers -of abstractions to the data model, and by providing pluggable extension points, giving you the ability to introduce -selective changes on a single level. - -## Overview of data model - -Generating API documentation begins with `Input` source files (`.kts`, `.java`, etc) and ends with some `Output` files -(`.html`/`.md` pages, etc). However, to allow for extensibility and customization, several input and output independent -abstractions have been added to the data model. - -Below you can find the general pipeline of processing data gathered from sources and the explanation for each stage. - -```mermaid -flowchart TD - Input --> Documentables --> Pages --> Output -``` - -* `Input` - generalization of sources, by default `Kotlin`/`Java` sources, but could be virtually anything -* `Documentables` - unified data model that represents _any_ parsed sources as a tree, independent of the source - language. Examples of a `Documentable`: class, function, package, property, etc -* `Pages` - universal model that represents output pages (e.g a function/property page) and the content it's composed of - (lists, text, code blocks) that the users needs to see. Not to be confused with `.html` pages. Goes hand in hand - with so-called `Content` model. -* `Output` - specific output format like `HTML`/`Markdown`/`Javadoc`/etc. This is a mapping of pages/content model to - some human-readable and visual representation. For instance: - * `PageNode` is mapped as - * `.html` file for `HTML` format - * `.md` file for `Markdown` format - * `ContentList` is mapped as - * `<li>` / `<ul>` for `HTML` format - * `1.` / `*` for `Markdown` format - * `ContentCodeBlock` is mapped as - * `<code>` or `<pre>` with some CSS styles in `HTML` format - * Text wrapped in triple backticks for `Markdown` format - - -You, as a `Dokka` developer or a plugin writer, can use extension points to introduce selective changes to the -model on one particular level without touching everything else. - -For instance, if you wanted to make some annotation/function/class invisible in the final documentation, you would only -need to modify the `Documentables` model by filtering undesirable members out. If you wanted to display all overloaded -methods on the same page instead of on separate ones, you would only need to modify the `Page` model by merging multiple -pages into one, and so on. - -For a deeper dive into Dokka's model with more examples and details, -see sections about [Documentables](data_model/documentables.md) and [Page/Content](data_model/page_content.md) - -For an overview of existing extension points that let you transform Dokka's models, see -[Core extension points](extension_points/core_extensions.md) and [Base extensions](extension_points/base_extensions.md). - -## Overview of extension points - -An extension point usually represents some pluggable interface that performs an action during one of the stages of -generating documentation. An extension is therefore an implementation of that interface which is extending the -extension point. - -You can create extension points, provide your own implementations (extensions) and configure them. All of -this is possible with Dokka's plugin/extension point API. - -Here's a sneak peek of the DSL: - -```kotlin -class MyPlugin : DokkaPlugin() { - // create an extension point for other developers - val signatureProvider by extensionPoint<SignatureProvider>() - - // provide a default implementation - val defaultSignatureProvider by extending { - signatureProvider with KotlinSignatureProvider() - } - - // register our own extension in base plugin and override its default - val dokkaBasePlugin by lazy { plugin<DokkaBase>() } - val multimoduleLocationProvider by extending { - (dokkaBasePlugin.locationProviderFactory - providing MultimoduleLocationProvider::Factory - override dokkaBasePlugin.locationProvider) - } -} - -// use a registered extention, pretty much dependency injection -class MyExtension(val context: DokkaContext) { - - val signatureProvider: SignatureProvider = context.plugin<MyPlugin>().querySingle { signatureProvider } - - fun doSomething() { - signatureProvider.signature(..) - } -} - -interface SignatureProvider { - fun signature(documentable: Documentable): List<ContentNode> -} - -class KotlinSignatureProvider : SignatureProvider { - override fun signature(documentable: Documentable): List<ContentNode> = listOf() -} -``` - -For a deeper dive into extensions and extension points with more examples and details, see -[Introduction to Extensions](extension_points/introduction.md). - -For an overview of existing extension points, see [Core extension points](extension_points/core_extensions.md) and -[Base extensions](extension_points/base_extensions.md). - -## Historical context - -This is a second iteration of Dokka that was built from scratch. - -If you want to learn more about why Dokka has been designed this way, watch this great talk by Paweł Marks: -[New Dokka - Designed for Fearless Creativity](https://www.youtube.com/watch?v=OvFoTRhqaKg). The general principles -and general architecture are the same, although it may be outdated in some areas, so please double-check. diff --git a/docs/src/doc/docs/developer_guide/architecture/data_model/documentables.md b/docs/src/doc/docs/developer_guide/architecture/data_model/documentables.md deleted file mode 100644 index 5264553d..00000000 --- a/docs/src/doc/docs/developer_guide/architecture/data_model/documentables.md +++ /dev/null @@ -1,245 +0,0 @@ -# Documentables Model - -Documentables represent data that is parsed from sources. Think of this data model as of something that could be -seen or produced by a compiler frontend, it's not far off from the truth. - -By default, documentables are parsed from `Descriptor` (for `Kotlin`) -and [Psi](https://plugins.jetbrains.com/docs/intellij/psi.html) -(for `Java`) models. Code-wise, you can have a look at following classes: - -* `DefaultDescriptorToDocumentableTranslator` - responsible for `Kotlin` -> `Documentable` mapping -* `DefaultPsiToDocumentableTranslator` - responsible for `Java` -> `Documentable` mapping - -Upon creation, it's a collection of trees, each with `DModule` as root. - -Take some arbitrary `Kotlin` source code that is located within the same module: - -```kotlin -// Package 1 -class Clazz(val property: String) { - fun function(parameter: String) {} -} - -fun topLevelFunction() {} - -// Package 2 -enum class Enum { } - -val topLevelProperty: String -``` - -This would be represented roughly as the following `Documentable` tree: - -```mermaid -flowchart TD - DModule --> firstPackage[DPackage] - firstPackage --> DClass - firstPackage --> toplevelfunction[DFunction] - DClass --> DProperty - DClass --> DFunction - DFunction --> DParameter - DModule --> secondPackage[DPackage] - secondPackage --> DEnum - secondPackage --> secondPackageProperty[DProperty] -``` - -At later stages of transformation, all trees are folded into one (by `DocumentableMerger`). - -## Documentable - -The main building block of documentables model is `Documentable` class. It's the base class for all more specific types -that represent elements of parsed sources with mostly self-explanatory names (`DFunction`, `DPackage`, `DProperty`, etc) -. -`DClasslike` is the base class for class-like documentables such as `DClass`, `DEnum`, `DAnnotation`, etc. - -The contents of each documentable normally represent what you would see in source code. For instance, if you open -`DClass`, you should find that it contains references to functions, properties, companion object, constructors and so -on. -`DEnum` should have references to enum entries, and `DPackage` can have references to both classlikes and top-level -functions and properties (`Kotlin`-specific). - -Here's an example of a documentable: - -```kotlin -data class DClass( - val dri: DRI, - val name: String, - val constructors: List<DFunction>, - val functions: List<DFunction>, - val properties: List<DProperty>, - val classlikes: List<DClasslike>, - val sources: SourceSetDependent<DocumentableSource>, - val visibility: SourceSetDependent<Visibility>, - val companion: DObject?, - val generics: List<DTypeParameter>, - val supertypes: SourceSetDependent<List<TypeConstructorWithKind>>, - val documentation: SourceSetDependent<DocumentationNode>, - val expectPresentInSet: DokkaSourceSet?, - val modifier: SourceSetDependent<Modifier>, - val sourceSets: Set<DokkaSourceSet>, - val isExpectActual: Boolean, - val extra: PropertyContainer<DClass> = PropertyContainer.empty() -) : DClasslike(), WithAbstraction, WithCompanion, WithConstructors, - WithGenerics, WithSupertypes, WithExtraProperties<DClass> -``` - -___ - -There are three non-documentable classes that important for this model: - -* `DRI` -* `SourceSetDependent` -* `ExtraProperty`. - -### DRI - -`DRI` stans for _Dokka Resource Identifier_ - a unique value that identifies a specific `Documentable`. -All references and relations between documentables (other than direct ownership) are described using `DRI`. - -For example, `DFunction` with a parameter of type `Foo` has only `Foo`'s `DRI`, not the actual reference -to `Foo`'s `Documentable` object. - -#### Example - -For an example of how a `DRI` can look like, let's take the `limitedParallelism` function from `kotlinx.coroutines`: - -```kotlin -package kotlinx.coroutines - -import ... - -public abstract class MainCoroutineDispatcher : CoroutineDispatcher() { - - override fun limitedParallelism(parallelism: Int): CoroutineDispatcher { - ... - } -} -``` - -If we were to re-create the DRI of this function in code, it would look something like this: - -```kotlin -DRI( - packageName = "kotlinx.coroutines", - classNames = "MainCoroutineDispatcher", - callable = Callable( - name = "limitedParallelism", - receiver = null, - params = listOf( - TypeConstructor( - fullyQualifiedName = "kotlin.Int", - params = emptyList() - ) - ) - ), - target = PointingToDeclaration, - extra = null -) -``` - -If you format it as `String`, it would look like this: - -``` -kotlinx.coroutines/MainCoroutineDispatcher/limitedParallelism/#kotlin.Int/PointingToDeclaration/ -``` - -### SourceSetDependent - -`SourceSetDependent` helps handling multiplatform data by associating platform-specific data (declared with either -`expect` or `actual` modifier) with particular -[source sets](https://kotlinlang.org/docs/multiplatform-discover-project.html#source-sets). - -This comes in handy if `expect`/`actual` declarations differ. For instance, the default value for `actual` might differ -from that declared in `expect`, or code comments written for `expect` might be different from what's written -for `actual`. - -Under the hood, it's a `typealias` to a `Map`: - -```kotlin -typealias SourceSetDependent<T> = Map<DokkaSourceSet, T> -``` - -### ExtraProperty - -`ExtraProperty` is used to store any additional information that falls outside of the regular model. It is highly -recommended to use extras to provide any additional information when creating custom Dokka plugins. - -This element is a bit more complex, so you can read more about how to use it -[in a separate section](extra.md). - -___ - -## Documentation model - -Documentation model is used alongside Documentables to store data obtained by parsing -code comments (such as `KDoc`/`Javadoc`). - -### DocTag - -`DocTag` describes a specific documentation syntax element. - -It's universal across source languages. For instance, DocTag `B` is the same for `**bold**` in `Kotlin` and -`<b>bold</b>` in `Java`. - -However, some `DocTag` elements are specific to a certain language, there are many such examples for `Java` -because it allows HTML tags inside `Javadoc` comments, some of which are simply not possible to reproduce with `Markdown`. - -`DocTag` elements can be deeply nested with other `DocTag` children elements. - -Examples: - -```kotlin -data class H1( - override val children: List<DocTag> = emptyList(), - override val params: Map<String, String> = emptyMap() -) : DocTag() - -data class H2( - override val children: List<DocTag> = emptyList(), - override val params: Map<String, String> = emptyMap() -) : DocTag() - -data class Strikethrough( - override val children: List<DocTag> = emptyList(), - override val params: Map<String, String> = emptyMap() -) : DocTag() - -data class Strong( - override val children: List<DocTag> = emptyList(), - override val params: Map<String, String> = emptyMap() -) : DocTag() - -data class CodeBlock( - override val children: List<DocTag> = emptyList(), - override val params: Map<String, String> = emptyMap() -) : Code() - -``` - -### TagWrapper - -`TagWrapper` describes the whole comment description or a specific comment tag. -For example: `@see` / `@author` / `@return`. - -Since each such section may contain formatted text inside of it, each `TagWrapper` has `DocTag` children. - -```kotlin -/** - * @author **Ben Affleck* - * @return nothing, except _sometimes_ it may throw an [Error] - */ -fun foo() {} -``` - -### DocumentationNode - -`DocumentationNode` acts as a container for multiple `TagWrapper` elements for a specific `Documentable`, usually -used like this: - -```kotlin -data class DFunction( - ... - val documentation: SourceSetDependent<DocumentationNode>, - ... -) -``` diff --git a/docs/src/doc/docs/developer_guide/architecture/data_model/extra.md b/docs/src/doc/docs/developer_guide/architecture/data_model/extra.md deleted file mode 100644 index 0abbc70e..00000000 --- a/docs/src/doc/docs/developer_guide/architecture/data_model/extra.md +++ /dev/null @@ -1,99 +0,0 @@ -# Extra - -## Introduction - -`ExtraProperty` classes are used both by [Documentable](documentables.md) and [Content](page_content.md#content-model) -models. - -Source code for `ExtraProperty`: - -```kotlin -interface ExtraProperty<in C : Any> { - interface Key<in C : Any, T : Any> { - fun mergeStrategyFor(left: T, right: T): MergeStrategy<C> = MergeStrategy.Fail { - throw NotImplementedError("Property merging for $this is not implemented") - } - } - - val key: Key<C, *> -} -``` - -To declare a new extra, you need to implement `ExtraProperty` interface. It is advised to use following pattern -when declaring new extras: - -```kotlin -data class CustomExtra( - [any data relevant to your extra], - [any data relevant to your extra] -): ExtraProperty<Documentable> { - override val key: CustomExtra.Key<Documentable, *> = CustomExtra - companion object : CustomExtra.Key<Documentable, CustomExtra> -} -``` - -Merge strategy (`mergeStrategyFor` method) for extras is invoked during -[merging](../extension_points/core_extensions.md#documentablemerger) if documentables from different -[source sets](https://kotlinlang.org/docs/multiplatform-discover-project.html#source-sets) each -have their own `Extra` of the same type. - -## PropertyContainer - -All extras for `ContentNode` and `Documentable` classes are stored in `PropertyContainer<C : Any>` class instances. - -```kotlin -data class DFunction( - ... - override val extra: PropertyContainer<DFunction> = PropertyContainer.empty() - ... -) : WithExtraProperties<DFunction> -``` - -`PropertyContainer` has a number of convenient functions for handling extras in a collection-like manner. - -The `C` generic class parameter limits the type of properties that can be stored in the container - it must -match generic `C` class parameter from `ExtraProperty` interface. This allows creating extra properties -which can only be stored in a specific `Documentable`. - -## Usage example - -In following example we will create a `DFunction`-only property, store it and then retrieve its value: - -```kotlin -data class CustomExtra(val customExtraValue: String) : ExtraProperty<DFunction> { - override val key: ExtraProperty.Key<Documentable, *> = CustomExtra - companion object: ExtraProperty.Key<Documentable, CustomExtra> -} - -fun DFunction.withCustomExtraProperty(data: String): DFunction { - return this.copy( - extra = extra + CustomExtra(data) - ) -} - -fun DFunction.getCustomExtraPropertyValue(): String? { - return this.extra[CustomExtra]?.customExtraValue -} -``` - -___ - -You can also use extras as markers, without storing any data in them: - -```kotlin - -object MarkerExtra : ExtraProperty<Any>, ExtraProperty.Key<Any, MarkerExtra> { - override val key: ExtraProperty.Key<Any, *> = this -} - -fun Documentable.markIfFunction(): Documentable { - return when(this) { - is DFunction -> this.copy(extra = extra + MarkerExtra) - else -> this - } -} - -fun WithExtraProperties<Documentable>.isMarked(): Boolean { - return this.extra[MarkerExtra] != null -} -``` diff --git a/docs/src/doc/docs/developer_guide/architecture/data_model/page_content.md b/docs/src/doc/docs/developer_guide/architecture/data_model/page_content.md deleted file mode 100644 index 54ded235..00000000 --- a/docs/src/doc/docs/developer_guide/architecture/data_model/page_content.md +++ /dev/null @@ -1,140 +0,0 @@ -# Page / Content Model - -Even though `Page` and `Content` models reside on the same level (under `Page`), it's easier to view it as two different -models altogether, even though `Content` is only used in conjunction with and inside `Page` model. - -## Page - -Page model represents the structure of documentation pages to be generated. During rendering, each page -is processed separately, so one page corresponds to exactly one output file. - -Page model is independent of the final output format, in other words it's universal. Which extension the pages -should be created as (`.html`, `.md`, etc) and how is up to the `Renderer`. - -Subclasses of `PageNode` represent different kinds of rendered pages, such as `ModulePage`, `PackagePage`, -`ClasslikePage`, `MemberPage` (properties, functions), etc. - -The Page Model is a tree structure, with `RootPageNode` at the root. - -Here's an example of how an arbitrary `Page` tree might look like for a module with 3 packages, one of which contains -a top level function, top level property and a class, inside which there's a function and a property: - -```mermaid -flowchart TD - RootPageNode --> firstPackage[PackagePageNode] - RootPageNode --> secondPackage[PackagePageNode] - RootPageNode --> thirdPackage[PackagePageNode] - firstPackage --> firstPackageFirstMember[MemberPageNode - Function] - firstPackage --> firstPackageSecondMember[MemberPageNode - Property] - firstPackage ---> firstPackageClasslike[ClasslikePageNode - Class] - firstPackageClasslike --> firstPackageClasslikeFirstMember[MemberPageNode - Function] - firstPackageClasslike --> firstPackageClasslikeSecondMember[MemberPageNode - Property] - secondPackage --> etcOne[...] - thirdPackage --> etcTwo[...] -``` - -Almost all pages are derivatives of `ContentPage` - it's the type of `Page` that has `Content` on it. - -## Content Model - -Content model describes how the actual `Page` content is presented. The important thing to understand is that it's -also output-format independent and is universal. - -Content model is essentially a set of building blocks that you can put together to represent some content. -Have a look at subclasses of `ContentNode`: `ContentText`, `ContentList`, `ContentTable`, `ContentCodeBlock`, -`ContentHeader` and so on. You can group content together with `ContentGroup` - for instance, -to wrap all children with some style. - -```kotlin -// real example of composing content using `DocumentableContentBuilder` DSL -orderedList { - item { - text("This list contains a nested table:") - table { - header { - text("Col1") - text("Col2") - } - row { - text("Text1") - text("Text2") - } - } - } - item { - group(styles = setOf(TextStyle.Bold)) { - text("This is bald") - text("This is also bald") - } - } -} -``` - -It is then responsibility of `Renderer` (i.e specific output format) to render it the way it wants. - -For instance, `HtmlRenderer` might render `ContentCodeBlock` as `<code>text</code>`, but `CommonmarkRenderer` might -render it using backticks. - -___ - -### DCI - -Each node is identified by unique `DCI`, which stands for _Dokka Content Identifier_. `DCI` aggregates `DRI`s of all -`Documentables` that make up a specific `ContentNode`. - -```kotlin -data class DCI(val dri: Set<DRI>, val kind: Kind) -``` - -All references to other nodes (other than direct ownership) are described using `DCI`. - -### ContentKind - -`ContentKind` represents a grouping of content of one kind that can can be rendered as part of a composite -page (one tab/block within a class's page, for instance). - -For instance, on the same page that describes a class you can have multiple sections (== `ContentKind`). -One to describe functions, one to describe properties, another one to describe constructors and so on. - -### Styles - -Each `ContentNode` has `styles` property in case you want to incidate to `Renderer` that this content needs to be -displayed in a certain way. - -```kotlin -group(styles = setOf(TextStyle.Paragraph)) { - text("Text1", styles = setOf(TextStyle.Bold)) - text("Text2", styles = setOf(TextStyle.Italic)) -} -``` - -It is then responsibility of `Renderer` (i.e specific output format) to render it the way it wants. For instance, -`HtmlRenderer` might render `TextStyle.Bold` as `<b>text</b>`, but `CommonmarkRenderer` might render it as `**text**`. - -There's a number of existing styles that you can use, most of them are supported by `HtmlRenderer` out of the box: - -```kotlin -// for code highlighting -enum class TokenStyle : Style { - Keyword, Punctuation, Function, Operator, Annotation, - Number, String, Boolean, Constant, Builtin, ... -} - -enum class TextStyle : Style { - Bold, Italic, Strong, Strikethrough, Paragraph, ... -} - -enum class ContentStyle : Style { - TabbedContent, RunnableSample, Wrapped, Indented, ... -} -``` - -### Extra - -`ExtraProperty` is used to store any additional information that falls outside of the regular model. It is highly -recommended to use extras to provide any additional information when creating custom Dokka plugins. - -All `ExtraProperty` elements from `Documentable` model are propagated into `Content` model and are available -for `Renderer`. - -This element is a bit complex, so you can read more about how to use it [in a separate section](extra.md). diff --git a/docs/src/doc/docs/developer_guide/architecture/extension_points/base_extensions.md b/docs/src/doc/docs/developer_guide/architecture/extension_points/base_extensions.md deleted file mode 100644 index 16a52fab..00000000 --- a/docs/src/doc/docs/developer_guide/architecture/extension_points/base_extensions.md +++ /dev/null @@ -1,13 +0,0 @@ -# Base extensions - -`DokkaBase` class is a base plugin which defines a number of default implementations for `CoreExtensions` as well as -declares its own, more high-level extension points to be used from other plugins and output formats. - -It's very convenient to use extension points and defaults defined in `DokkaBase` if you have an idea for a simple -plugin that only needs to provide a few extensions or change a single extension point and have everything else be the -default. - -`DokkaBase` is used extensively for Dokka's own output formats such as `HTML`, `Markdown`, `Mathjax` and others. - -You can learn how to add/use/override/configure extensions and extension points in -[Introduction to Extensions](introduction.md), all the information is applicable to `DokkaBase` plugin as well. diff --git a/docs/src/doc/docs/developer_guide/architecture/extension_points/core_extensions.md b/docs/src/doc/docs/developer_guide/architecture/extension_points/core_extensions.md deleted file mode 100644 index 381a9596..00000000 --- a/docs/src/doc/docs/developer_guide/architecture/extension_points/core_extensions.md +++ /dev/null @@ -1,151 +0,0 @@ -# Core extension points - -Core extension points represent the main stages of generating documentation. - -These extension points are plugin and output format independent, meaning it's the very core functionality and as -low-level as can get. For higher-level extension functions that can be used in different output formats, have a look at -[Base extensions](base_extensions.md) defined in `DokkaBase`. - -You can find all core extensions in `CoreExtensions` class: -```kotlin -object CoreExtensions { - val preGenerationCheck by coreExtensionPoint<PreGenerationChecker>() - val generation by coreExtensionPoint<Generation>() - val sourceToDocumentableTranslator by coreExtensionPoint<SourceToDocumentableTranslator>() - val documentableMerger by coreExtensionPoint<DocumentableMerger>() - val documentableTransformer by coreExtensionPoint<DocumentableTransformer>() - val documentableToPageTranslator by coreExtensionPoint<DocumentableToPageTranslator>() - val pageTransformer by coreExtensionPoint<PageTransformer>() - val renderer by coreExtensionPoint<Renderer>() - val postActions by coreExtensionPoint<PostAction>() -} -``` - -On this page we'll go over each extension point individually. - -## PreGenerationChecker - -`PreGenerationChecker` can be used to run some checks and constraints. - -For instance, `Javadoc` plugin does not support generating documentation for multi-platform projects, so it uses -`PreGenerationChecker` to check for multi-platform -[source sets](https://kotlinlang.org/docs/multiplatform-discover-project.html#source-sets) and fails if it finds any. - -## Generation - -`Generation` is responsible for generating documentation as a whole, utilizing other extension points where applicable. - -There are two implementations at the moment: - -* `AllModulesPageGeneration` - generates multimodule documentation, for instance when `dokkaHtmlMultiModule` task is - invoked. -* `SingleModuleGeneration` - generates documentation for a single module, for instance when `dokkaHtml` task is invoked - -### AllModulesPageGeneration - -`AllModulesPageGeneration` utilizes output generated by `SingleModuleGeneration`. Under the hood it just collects all -pages generated for individual modules and assembles everything together, creating navigation pages between the -modules and so on. - -### SingleModuleGeneration stages - -When developing a feature or a plugin, it's more convenient to think that you are generating documentation for single -module projects, believing that Dokka will somehow take care of the rest in multimodule environment. - -`SingleModuleGeneration` is at heart of generating documentation and utilizes other core extension points, so -it's worth going over its stages. - -Below you can see the transformations of [Dokka's models](../architecture_overview.md#overview-of-data-model) and -extension interfaces responsible for each one. Notice how `Documentables` and `Pages` are transformed multiple times. - -```mermaid -flowchart TD - Input -- SourceToDocumentableTranslator --> doc1[Documentables] - subgraph documentables [ ] - doc1 -- PreMergeDocumentableTransformer --> doc2[Documentables] - doc2 -- DocumentableMerger --> doc3[Documentables] - doc3 -- DocumentableTransformer --> doc4[Documentables] - end - doc4 -- DocumentableToPageTranslator --> page1[Pages] - subgraph ide2 [ ] - page1 -- PageTransformer --> page2[Pages] - end - page2 -- Renderer --> Output -``` - -#### SourceToDocumentableTranslator - -`SourceToDocumentableTranslator` translates sources into documentable model. - -`Kotlin` and `Java` sources are supported by default, but you can analyze any language as long as you can map -it to the [Documentable](../data_model/documentables.md) model. - -For reference, see - -* `DefaultDescriptorToDocumentableTranslator` for `Kotlin` sources translation -* `DefaultPsiToDocumentableTranslator` for `Java` sources translation - -#### PreMergeDocumentableTransformer - -This extension point actually comes from `DokkaBase` and is not a core extension point, but it's used in -`SingleModuleGeneration` nonetheless. If you are implementing your own plugin without relying on `DokkaBase`, -you can either introduce a similar extension point or rely on [DocumentableTransformer](#documentabletransformer) which -will be discussed below. - -`PreMergeDocumentableTransformer` allows applying any transformation to -[Documentables model](../data_model/documentables.md) before different -[source sets](https://kotlinlang.org/docs/multiplatform-discover-project.html#source-sets) are merged. - -Useful if you want to filter/map existing documentables. For instance, if you want to exclude members annotated with -`@Internal`, you most likely need an implementation of `PreMergeDocumentableTransformer`. - -For simple condition-based filtering of documentables consider extending -`SuppressedByConditionDocumentableFilterTransformer` - it implements `PreMergeDocumentableTransformer` and only -requires one function to be overridden. The rest is taken care of. - -#### DocumentableMerger - -`DocumentableMerger` merges all `DModule` instances into one. Only one extension is expected of this type. - -#### DocumentableTransformer - -`DocumentableTransformer` performs the same function as `PreMergeDocumentableTransformer`, but after merging source -sets. - -Notable example is `InheritorsExtractorTransformer`, it extracts inherited classes data across -[source sets](https://kotlinlang.org/docs/multiplatform-discover-project.html#source-sets) and creates an inheritance -map. - -#### DocumentableToPageTranslator - -`DocumentableToPageTranslator` is responsible for creating pages and their content. See -[Page/Content model](../data_model/page_content.md) section for more information and examples. - -Different output formats can either use the same page structure or define their own in case it needs to be different. - -Only a single extension of this type is expected to be registered. - -#### PageTransformer - -`PageTransformer` is useful if you need to add/remove/modify generated pages or their content. - -Plugins like `mathjax` can add `.js` scripts to pages using this extension point. - -If you want all overloaded functions to be rendered on the same page (instead of separate ones), -you can also use `PageTransformer` to delete excessive pages and combine them into a new single one. - -#### Renderer - -`Renderer` - defines rules on what to do with pages and their content, which files to create and how to display -it properly. - -Output format implementations should use `Renderer` extension point. Notable examples are `HtmlRenderer` -and `CommonmarkRenderer`. - -## PostAction - -`PostAction` is useful for when you want to run some actions after the documentation has been generated - for instance -if you want to move some files around. - -[Versioning plugin](../../../user_guide/plugins/versioning-plugin.md) utilizes `PostAction` in order to move -generated documentation to versioned folders. diff --git a/docs/src/doc/docs/developer_guide/architecture/extension_points/introduction.md b/docs/src/doc/docs/developer_guide/architecture/extension_points/introduction.md deleted file mode 100644 index 877d14e9..00000000 --- a/docs/src/doc/docs/developer_guide/architecture/extension_points/introduction.md +++ /dev/null @@ -1,163 +0,0 @@ -# Introduction to extension points - -In this section you can learn how to create new extension points, how to use and configure existing ones and -how to query for extensions when generating documentation. - -## Declaring extension points - -If you are writing a plugin, you can create your own extension point that other developers (or you) can use later on -in some other part of code. - -```kotlin -class MyPlugin : DokkaPlugin() { - val sampleExtensionPoint by extensionPoint<SampleExtensionPointInterface>() -} - -interface SampleExtensionPointInterface { - fun doSomething(input: Input): List<Output> -} - -class Input -class Output -``` - -Usually you would want to provide some default implementation(s) for your extension point, you can do that -within the same plugin class by extending an extension point you've just created. -See [Extending from extension points](#extending-from-extension-points) for examples. - -## Extending from extension points - -You can use extension points to provide your own implementation(s) in order to customize plugin's behaviour. - -You can do that within the same class as the extension point itself: - -```kotlin -open class MyPlugin : DokkaPlugin() { - val sampleExtensionPoint by extensionPoint<SampleExtensionPointInterface>() - - val defaultSampleExtension by extending { - sampleExtensionPoint with DefaultSampleExtension() - } -} - -... - -class DefaultSampleExtension : SampleExtensionPointInterface { - override fun doSomething(input: Input): List<Output> = listOf() -} -``` - -___ - -If you want to extend someone else's plugin (including `DokkaBase`), you can use plugin querying API to do that. -In the example below we will extend `MyPlugin` that was created above with our own implementation of -`SampleExtensionPointInterface`. - -```kotlin -class MyExtendedPlugin : DokkaPlugin() { - val mySampleExtensionImplementation by extending { - plugin<MyPlugin>().sampleExtensionPoint with SampleExtensionImpl() - } -} - -class SampleExtensionImpl : SampleExtensionPointInterface { - override fun doSomething(input: Input): List<Output> = listOf() -} - -``` - -### Providing - -If you need to have access to `DokkaContext` in order to create an extension, you can use `providing` instead. - -```kotlin -val defaultSampleExtension by extending { - sampleExtensionPoint providing { context -> - // can use context to query other extensions or get configuration - DefaultSampleExtension() - } -} -``` - -You can read more on what you can do with `context` in [Obtaining extension instance](#obtaining-extension-instance). - -### Override - -By extending an extension point, you are registering an _additional_ extension. This behaviour is expected for some -extension points, for instance `Documentable` transformers, since all transformers do their own transformations and all -of them will be invoked before proceeding. - -However, a plugin can expect only a single registered extension for an extension point. In this case, you can `override` -existing registered extensions: - -```kotlin -class MyExtendedPlugin : DokkaPlugin() { - private val myPlugin by lazy { plugin<MyPlugin>() } - - val mySampleExtensionImplementation by extending { - (myPlugin.sampleExtensionPoint - with SampleExtensionImpl() - override myPlugin.defaultSampleExtension) - } -} -``` - -This is also useful if you wish to override some extension from `DokkaBase` to disable or alter it. - -### Order - -Sometimes the order in which extensions are invoked matters. This is something you can control as well using `order`: - -```kotlin -class MyExtendedPlugin : DokkaPlugin() { - private val myPlugin by lazy { plugin<MyPlugin>() } - - val mySampleExtensionImplementation by extending { - myPlugin.sampleExtensionPoint with SampleExtensionImpl() order { - before(myPlugin.firstExtension) - after(myPlugin.thirdExtension) - } - } -} -``` - -### Conditional apply - -If you want your extension to be registered only if some condition is `true`, you can use `applyIf`: - -```kotlin -class MyExtendedPlugin : DokkaPlugin() { - private val myPlugin by lazy { plugin<MyPlugin>() } - - val mySampleExtensionImplementation by extending { - myPlugin.sampleExtensionPoint with SampleExtensionImpl() applyIf { - Random.Default.nextBoolean() - } - } -} -``` - -## Obtaining extension instance - -After an extension point has been [created](#declaring-extension-points) and some extension has been -[registered](#extending-from-extension-points), you can use `query` and `querySingle` to find all or just a single -implementation for it. - -```kotlin -class MyExtension(context: DokkaContext) { - // returns all registered extensions for this extension point - val allSampleExtensions = context.plugin<MyPlugin>().query { sampleExtensionPoint } - - // will throw an exception if more than one extension is found - // use if you expect only a single extension to be registered for this extension point - val singleSampleExtensions = context.plugin<MyPlugin>().querySingle { sampleExtensionPoint } - - fun invoke() { - allSampleExtensions.forEach { it.doSomething(Input()) } - - singleSampleExtensions.doSomething(Input()) - } -} -``` - -In order to have access to context you can use [providing](#providing) when registering this as an extension. diff --git a/docs/src/doc/docs/developer_guide/introduction.md b/docs/src/doc/docs/developer_guide/introduction.md deleted file mode 100644 index feb601fe..00000000 --- a/docs/src/doc/docs/developer_guide/introduction.md +++ /dev/null @@ -1,19 +0,0 @@ -# Developer guides - -The purpose of `Developer guides` section is to get you acquainted with Dokka's internals so that you can start developing -your own plugins or contributing features and fixes to Dokka itself. - -If you want to start hacking on Dokka right away, the only thing you need to be aware of is the -[general workflow](workflow.md), it will teach you how to build, debug and test Dokka locally. - -If you want to get into plugin development quick, see -[Introduction to plugin development](plugin-development/introduction.md). - -If you have time to spare and want to know more about Dokka's internals, its architecture and capabilities, follow -[Architecture overview](architecture/architecture_overview.md) and subsequent sections inside `Internals`. - -Having read through all the developer guides, you'll have a pretty good unrestanding of Dokka and how to develop -for it. - -If you have any questions, feel free to get in touch with maintainers via [Slack](../community/slack.md) or -[GitHub](https://github.com/kotlin/dokka). diff --git a/docs/src/doc/docs/developer_guide/plugin-development/introduction.md b/docs/src/doc/docs/developer_guide/plugin-development/introduction.md deleted file mode 100644 index fbfb32ac..00000000 --- a/docs/src/doc/docs/developer_guide/plugin-development/introduction.md +++ /dev/null @@ -1,59 +0,0 @@ -# Introduction to plugin development - -In order to have an easier time developing plugins, it's a good idea to go through -[Dokka's internals](../architecture/architecture_overview.md) first to learn more about its -[data model](../architecture/data_model/documentables.md) and -[extensions](../architecture/extension_points/introduction.md). - -## Setup - -### Template - -The easiest way to start is to use the convenient [Dokka plugin template](https://github.com/Kotlin/dokka-plugin-template). -It has pre-configured dependencies, publishing and signing of your artifacts. - -### Manual - -At a bare minimum, Dokka requires `Kotlin Gradle Plugin` and `dokka-core` dependencies: - -```kotlin -plugins { - kotlin("jvm") version "<kotlin_version>" -} - -dependencies { - compileOnly("org.jetbrains.dokka:dokka-core:<dokka_version>") -} - -tasks.withType<KotlinCompile> { - kotlinOptions.jvmTarget = "1.8" -} -``` - -In order to load a plugin into Dokka, your class must extend `DokkaPlugin` class. A fully qualified name of that class -must be placed in a file named `org.jetbrains.dokka.plugability.DokkaPlugin` under `resources/META-INF/services`. -All instances are automatically loaded during Dokka setup using `java.util.ServiceLoader`. - -## Extension points - -Dokka provides a set of entry points for which you can create your own implementations. If you are not sure which -extension point to use, have a look at [core extensions](../architecture/extension_points/core_extensions.md) and -[base extensions](../architecture/extension_points/base_extensions.md). - -You can learn how to declare extension points and use extensions in -[Introduction to Extension points](../architecture/extension_points/introduction.md). - -In case no suitable extension point exists for your use case, do share the details - it might be added in future -versions of Dokka. - -## Example - -You can follow the [sample plugin tutorial](sample-plugin-tutorial.md) which covers creation of a simple plugin: hide members -annotated with your own `@Internal` annotation, that is exclude these members from generated documentation. - -Fore more practical examples, have a look at sources of [community plugins](../../community/plugins-list.md). - -## Help - -If you have any further questions, feel free to get in touch with maintainers via [Slack](../../community/slack.md) or -[GitHub](https://github.com/kotlin/dokka). diff --git a/docs/src/doc/docs/developer_guide/plugin-development/sample-plugin-tutorial.md b/docs/src/doc/docs/developer_guide/plugin-development/sample-plugin-tutorial.md deleted file mode 100644 index fdea0207..00000000 --- a/docs/src/doc/docs/developer_guide/plugin-development/sample-plugin-tutorial.md +++ /dev/null @@ -1,292 +0,0 @@ -# Sample plugin tutorial - -We'll go over creating a simple plugin that covers a very common use case: generate documentation for everything except -for members annotated with a custom `@Internal` annotation - they should be hidden. - -The plugin will be tested with the following code: - -```kotlin -package org.jetbrains.dokka.internal.test - -annotation class Internal - -fun shouldBeVisible() {} - -@Internal -fun shouldBeExcludedFromDocumentation() {} -``` - -Expected behavior: function `shouldBeExcludedFromDocumentation` should not be visible in generated documentation. - -Full source code of this tutorial can be found in Dokka's examples under -[hide-internal-api](https://github.com/Kotlin/dokka/examples/plugin/hide-internal-api). - -## Preparing the project - -We'll begin by using [Dokka plugin template](https://github.com/Kotlin/dokka-plugin-template). Press the -`Use this template` button and -[open this project in IntelliJ IDEA](https://www.jetbrains.com/idea/guide/tutorials/working-with-gradle/opening-a-gradle-project/). - -First, let's rename the pre-made `template` package and `MyAwesomeDokkaPlugin` class to something of our own. - -For instance, package can be renamed to `org.example.dokka.plugin` and the class to `HideInternalApiPlugin`: - -```kotlin -package org.example.dokka.plugin - -import org.jetbrains.dokka.plugability.DokkaPlugin - -class HideInternalApiPlugin : DokkaPlugin() { - -} -``` - -After you do that, make sure to update the path to this class in -`resources/META-INF/services/org.jetbrains.dokka.plugability.DokkaPlugin`: -```kotlin -org.example.dokka.plugin.HideInternalApiPlugin -``` - -At this point you can also change project name in `settings.gradle.kts` (to `hide-internal-api` in our case) -and `groupId` in `build.gradle.kts`. - -## Extending Dokka - -After preparing the project we can begin extending Dokka with our own extension. - -Having read through [Core extensions](../architecture/extension_points/core_extensions.md), it's clear that we need -a `PreMergeDocumentableTransformer` extension in order to filter out undesired documentables. - -Moreover, the article mentioned a convenient abstract transformer `SuppressedByConditionDocumentableFilterTransformer` -which is perfect for our use case, so we can try to implement it. - -Create a new class, place it next to your plugin and implement the abstract method. You should end up with this: - -```kotlin -package org.example.dokka.plugin - -import org.jetbrains.dokka.base.transformers.documentables.SuppressedByConditionDocumentableFilterTransformer -import org.jetbrains.dokka.model.Documentable -import org.jetbrains.dokka.plugability.DokkaContext -import org.jetbrains.dokka.plugability.DokkaPlugin - -class HideInternalApiPlugin : DokkaPlugin() {} - -class HideInternalApiTransformer(context: DokkaContext) : SuppressedByConditionDocumentableFilterTransformer(context) { - - override fun shouldBeSuppressed(d: Documentable): Boolean { - return false - } -} -``` - -Now we somehow need to find all annotations applied to `d: Documentable` and see if our `@Internal` annotation is present. -However, it's not very clear how to do that. What usually helps is stopping in debugger and having a look at what fields -and values a given `Documentable` has. - -To do that, we'll need to register our extension point first, then we can publish our plugin and set the breakpoint. - -Having read through [Introduction to extensions](../architecture/extension_points/introduction.md), we now know -how to register our extensions: - -```kotlin -class HideInternalApiPlugin : DokkaPlugin() { - val myFilterExtension by extending { - plugin<DokkaBase>().preMergeDocumentableTransformer providing ::HideInternalApiTransformer - } -} -``` - -At this point we're ready to debug our plugin locally, it should already work, but do nothing. - -## Debugging - -Please read through [Debugging Dokka](../workflow.md#debugging-dokka), it goes over the same steps in more detail -and with examples. Below you will find rough instructions. - -First, let's begin by publishing our plugin to `mavenLocal()`. - -```bash -./gradlew publishToMavenLocal -``` - -This will publish your plugin under the `groupId`, `artifactId` and `version` that you've specified in your -`build.gradle.kts`. In our case it's `org.example:hide-internal-api:1.0-SNAPSHOT`. - -Open a debug project of your choosing that has Dokka configured, and add our plugin to dependencies: - -```kotlin -dependencies { - dokkaPlugin("org.example:hide-internal-api:1.0-SNAPSHOT") -} -``` - -Next, in that project let's run `dokkaHtml` with debug enabled: - -```bash -./gradlew clean dokkaHtml -Dorg.gradle.debug=true --no-daemon -``` - -Switch to the plugin project, set a breakpoint inside `shouldBeSuppressed` and run jvm remote debug. - -If you've done everything correctly, it should stop in debugger and you should be able to observe the values contained -inside `d: Documentable`. - -## Implementing plugin logic - -Now that we've stopped at our breakpoint, let's skip until we see `shouldBeExcludedFromDocumentation` function in the -place of `d: Documentable` (observe the changing `name` property). - -Looking at what's inside the object, you might notice it has 3 values in `extra`, one of which is `Annotations`. -Sounds like something we need! - -Having poked around, we come up with the following monstrosity of a code for determining if a given documentable has -`@Internal` annotation (it can of course be refactored.. later): - -```kotlin -override fun shouldBeSuppressed(d: Documentable): Boolean { - - val annotations: List<Annotations.Annotation> = - (d as? WithExtraProperties<*>) - ?.extra - ?.allOfType<Annotations>() - ?.flatMap { it.directAnnotations.values.flatten() } - ?: emptyList() - - return annotations.any { isInternalAnnotation(it) } -} - -private fun isInternalAnnotation(annotation: Annotations.Annotation): Boolean { - return annotation.dri.packageName == "org.jetbrains.dokka.internal.test" - && annotation.dri.classNames == "Internal" -} -``` - -Seems like we're done with writing our plugin and can begin testing it manually. - -## Manual testing - -At this point, the implementation of your plugin should look roughly like this: - -```kotlin -package org.example.dokka.plugin - -import org.jetbrains.dokka.base.DokkaBase -import org.jetbrains.dokka.base.transformers.documentables.SuppressedByConditionDocumentableFilterTransformer -import org.jetbrains.dokka.model.Annotations -import org.jetbrains.dokka.model.Documentable -import org.jetbrains.dokka.model.properties.WithExtraProperties -import org.jetbrains.dokka.plugability.DokkaContext -import org.jetbrains.dokka.plugability.DokkaPlugin - -class HideInternalApiPlugin : DokkaPlugin() { - val myFilterExtension by extending { - plugin<DokkaBase>().preMergeDocumentableTransformer providing ::HideInternalApiTransformer - } -} - -class HideInternalApiTransformer(context: DokkaContext) : SuppressedByConditionDocumentableFilterTransformer(context) { - - override fun shouldBeSuppressed(d: Documentable): Boolean { - val annotations: List<Annotations.Annotation> = - (d as? WithExtraProperties<*>) - ?.extra - ?.allOfType<Annotations>() - ?.flatMap { it.directAnnotations.values.flatten() } - ?: emptyList() - - return annotations.any { isInternalAnnotation(it) } - } - - private fun isInternalAnnotation(annotation: Annotations.Annotation): Boolean { - return annotation.dri.packageName == "org.jetbrains.dokka.internal.test" - && annotation.dri.classNames == "Internal" - } -} -``` - -Bump plugin version in `gradle.build.kts`, publish it to maven local, open the debug project and run `dokkaHtml` -(without debug this time). It should work, you should **not** be able to see `shouldBeExcludedFromDocumentation` -function in generated documentation. - -Manual testing is cool and all, but wouldn't it be better if we could somehow write unit tests for it? Indeed! - -## Unit testing - -You might've noticed that plugin template comes with a pre-made test class. Feel free to move it to another package -and rename it. - -We are mostly interested in a single test case - functions annotated with `@Internal` should be hidden, while all other -public functions should be visible. - -Plugin API comes with a set of convenient test utilities that are used to test Dokka itself, so it covers a wide range -of use cases. When in doubt, see Dokka's tests for reference. - -Below you will find a complete unit test that passes, and the main takeaways below that. - -```kotlin -package org.example.dokka.plugin - -import org.jetbrains.dokka.base.testApi.testRunner.BaseAbstractTest -import org.junit.Test -import kotlin.test.assertEquals - -class HideInternalApiPluginTest : BaseAbstractTest() { - - @Test - fun `should hide annotated functions`() { - val configuration = dokkaConfiguration { - sourceSets { - sourceSet { - sourceRoots = listOf("src/main/kotlin/basic/Test.kt") - } - } - } - val hideInternalPlugin = HideInternalApiPlugin() - - testInline( - """ - |/src/main/kotlin/basic/Test.kt - |package org.jetbrains.dokka.internal.test - | - |annotation class Internal - | - |fun shouldBeVisible() {} - | - |@Internal - |fun shouldBeExcludedFromDocumentation() {} - """.trimMargin(), - configuration = configuration, - pluginOverrides = listOf(hideInternalPlugin) - ) { - preMergeDocumentablesTransformationStage = { modules -> - val testModule = modules.single { it.name == "root" } - val testPackage = testModule.packages.single { it.name == "org.jetbrains.dokka.internal.test" } - - val packageFunctions = testPackage.functions - assertEquals(1, packageFunctions.size) - assertEquals("shouldBeVisible", packageFunctions[0].name) - } - } - } -} -``` - -Note that the package of the tested code (inside `testInline` function) is the same as the package that we have -hardcoded in our plugin. Make sure to change that to your own if you are following along, otherwise it will fail. - -Things to note and remember: - -1. Your test class should extend `BaseAbstractTest`, which contains base utility methods for testing. -2. You can configure Dokka to your liking, enable some specific settings, configure - [source sets](https://kotlinlang.org/docs/multiplatform-discover-project.html#source-sets), etc. All done via - `dokkaConfiguration` DSL. -3. `testInline` function is the main entry point for unit tests -4. You can pass plugins to be used in a test, notice `pluginOverrides` parameter -5. You can write asserts for different stages of generating documentation, the main ones being `Documentables` model - generation, `Pages` generation and `Output` generation. Since we implemented our plugin to work during - `PreMergeDocumentableTransformer` stage, we can test it on the same level (that is - `preMergeDocumentablesTransformationStage`). -6. You will need to write asserts using the model of whatever stage you choose. For `Documentable` transformation stage - it's `Documentable`, for `Page` generation stage you would have `Page` model, and for `Output` you can have `.html` - files that you will need to parse with `JSoup` (there are also utilities for that). diff --git a/docs/src/doc/docs/developer_guide/workflow.md b/docs/src/doc/docs/developer_guide/workflow.md deleted file mode 100644 index ddf37459..00000000 --- a/docs/src/doc/docs/developer_guide/workflow.md +++ /dev/null @@ -1,100 +0,0 @@ -# Workflow - -Whether you're contributing a feature/fix to Dokka itself or developing a separate plugin, there's 3 things -you'll be doing: - -1. Building Dokka / Plugins -2. Using/Testing locally built Dokka in a (debug) project -3. Debugging Dokka / Plugin code - -We'll go over each step individually in this section. - -Examples below will be specific to Gradle and [Gradle’s Kotlin DSL](https://docs.gradle.org/current/userguide/kotlin_dsl.html), -but you can apply the same principles and run/test/debug with CLI/Maven runners and build configurations if you wish. - -## Building Dokka - -Building Dokka is pretty straightforward, with one small caveat: when you run `./gradlew build`, it will run -integration tests as well, which might take some time and will consume a lot of RAM, so you would usually want -to exclude integration tests when building locally. - -```shell -./gradlew build -x integrationTest -``` - -Unit tests which are run as part of `build` should not take much time, but you can also skip it with `-x test`. - -### Troubleshooting build - -#### API check failed for project .. - -If you see messages like `API check failed for project ..` during `build` phase, it indicates that -[binary compatibility check](https://github.com/Kotlin/binary-compatibility-validator) has failed, meaning you've -changed/added/removed some public API. - -If the change was intentional, run `./gradlew apiDump` - it will re-generate `.api` files with signatures, -and you should be able to `build` Dokka with no errors. These updated files need to be committed as well. Maintainers -will review API changes thoroughly, so please make sure it's intentional and rational. - -## Using/testing locally built Dokka - -Having built Dokka locally, you can publish it to `mavenLocal()`. This will allow you to test your changes in another -project as well as debug code remotely. - -1. Change `dokka_version` in `gradle.properties` to something that you will use later on as the dependency version. - For instance, you can set it to something like `1.7.20-my-fix-SNAPSHOT`. This version will be propagated to plugins - that reside inside Dokka's project (such as `mathjax`, `kotlin-as-java`, etc). -2. Publish it to maven local (`./gradlew publishToMavenLocal`). Corresponding artifacts should appear in `~/.m2` -3. In the project you want to generate documentation for or debug on, add maven local as a plugin/dependency - repository: -```kotlin -repositories { - mavenLocal() -} -``` -4. Update your dokka dependency to the version you've just published: -```kotlin -plugins { - id("org.jetbrains.dokka") version "1.7.20-my-fix-SNAPSHOT" -} -``` - -After completing these steps, you should be able to build documentation using your own version of Dokka. - -## Debugging Dokka - -Dokka is essentially a gradle plugin, so you can debug it the same way you would any other gradle plugin. - -Below you'll find instructions on how to debug Dokka's internal logic, but you can apply the same principles if you -wish to debug a plugin which resides in a separate project. - -1. Choose a project to debug on, it needs to have some code for which documentation will be generated. - Prefer using smaller projects that reproduce the exact problem or behaviour you want - since the less code you have, the easier it will be to understand what's going on. You can use example projects - found in [dokka/examples/gradle](https://github.com/Kotlin/dokka/tree/master/examples/gradle), there's both simple - single-module and more complex multimodule/multiplatform examples. -2. For the debug project, set `org.gradle.debug` to `true` in one of the following ways: - - * In your `gradle.properties` add `org.gradle.debug=true` - * When running Dokka tasks:<br/>`./gradlew dokkaHtml -Dorg.gradle.debug=true --no-daemon` - -3. Run desired Dokka task with `--no-daemon`. Gradle should wait until you attach with debugger before proceeding - with the task, so no need to hurry here. - <br/>Example: `./gradlew dokkaHtml -Dorg.gradle.debug=true --no-daemon`. - -4. Open Dokka in IntelliJ IDEA, set a breakpoint and, using remote debug in IntelliJ IDEA, - [Attach to process](https://www.jetbrains.com/help/idea/attaching-to-local-process.html#attach-to-remote) - running on the default port 5005. You can do that either by creating a `Remote JVM Debug` Run/Debug configuration - or by attaching to the process via `Run` -> `Attach to process` - -!!! note - The reason for `--no-daemon` is that - [Gradle daemons](https://docs.gradle.org/current/userguide/gradle_daemon.html) continue to exist even after the task - has completed execution, so you might hang in debug or experience issues with `port was already in use` if you try - to run it again. - - If you previously ran Dokka with daemons and you are already encountering problems with it, try killing - gradle daemons. For instance, via `pkill -f gradle.*daemon` - -In case you need to debug some other part of the build - consult the official Gradle -tutorials on [Troubleshooting Builds](https://docs.gradle.org/current/userguide/troubleshooting.html). diff --git a/docs/src/doc/docs/dokka_colors.css b/docs/src/doc/docs/dokka_colors.css deleted file mode 100644 index 69a24359..00000000 --- a/docs/src/doc/docs/dokka_colors.css +++ /dev/null @@ -1,3 +0,0 @@ -.md-header, .md-tabs { - background-color: #27282c -} diff --git a/docs/src/doc/docs/faq.md b/docs/src/doc/docs/faq.md deleted file mode 100644 index ef728ca0..00000000 --- a/docs/src/doc/docs/faq.md +++ /dev/null @@ -1,2 +0,0 @@ -# FAQ -If you encounter any problems, please see [FAQ](https://github.com/Kotlin/dokka/wiki/faq). diff --git a/docs/src/doc/docs/favicon.svg b/docs/src/doc/docs/favicon.svg deleted file mode 100755 index 1fea0877..00000000 --- a/docs/src/doc/docs/favicon.svg +++ /dev/null @@ -1,10 +0,0 @@ -<svg width="64" height="64" viewBox="0 0 64 64" fill="none" xmlns="http://www.w3.org/2000/svg"> - <path d="M64 64H0V0H64L31.3373 31.5369L64 64Z" fill="url(#paint0_radial)"/> - <defs> - <radialGradient id="paint0_radial" cx="0" cy="0" r="1" gradientUnits="userSpaceOnUse" gradientTransform="translate(61.8732 2.63097) scale(73.3111)"> - <stop offset="0.00343514" stop-color="#EF4857"/> - <stop offset="0.4689" stop-color="#D211EC"/> - <stop offset="1" stop-color="#7F52FF"/> - </radialGradient> - </defs> -</svg>
\ No newline at end of file diff --git a/docs/src/doc/docs/images/mathjax_demo.png b/docs/src/doc/docs/images/mathjax_demo.png Binary files differdeleted file mode 100644 index 9b14a704..00000000 --- a/docs/src/doc/docs/images/mathjax_demo.png +++ /dev/null diff --git a/docs/src/doc/docs/images/mermaid_demo.png b/docs/src/doc/docs/images/mermaid_demo.png Binary files differdeleted file mode 100644 index 0d0e27b6..00000000 --- a/docs/src/doc/docs/images/mermaid_demo.png +++ /dev/null diff --git a/docs/src/doc/docs/index.md b/docs/src/doc/docs/index.md deleted file mode 100644 index 0f106c04..00000000 --- a/docs/src/doc/docs/index.md +++ /dev/null @@ -1,38 +0,0 @@ -# Dokka - -`Dokka` is an API documentation engine for `Kotlin` that performs the same function as the `Javadoc` tool for `Java`, -but it's modern and highly pluggable. - -Just like `Kotlin` itself, `Dokka` supports mixed-language projects (`Kotlin`/`Java`). It understands -[KDoc comments](https://kotlinlang.org/docs/reference/kotlin-doc.html) in `Kotlin` source files as well -as [Javadoc comments](https://www.oracle.com/technical-resources/articles/java/javadoc-tool.html#format) in `Java` -files, and can generate documentation in multiple formats including its own `HTML` format, Java's `Javadoc` lookalike -and `Markdown`. - -Some libraries that use `Dokka` for API reference docs: - -* [kotlinx.coroutines](https://kotlinlang.org/api/kotlinx.coroutines/) -* [kotlinx.serialization](https://kotlinlang.org/api/kotlinx.serialization/) -* [Ktor](https://api.ktor.io/) -* [Spring Framework](https://docs.spring.io/spring-framework/docs/current/kdoc-api/) - -___ - -`Dokka` provides support for the following build systems: - -* [Gradle](user_guide/applying/gradle.md) (preferred) -* [Maven](user_guide/applying/maven.md) -* [Command line](user_guide/applying/cli.md) - -___ - -`Dokka` is also very pluggable and comes with convenient plugin and extension point API. - -You can write a plugin to support [mermaid.js](community/plugins-list.md#mermaid) diagrams, -[mathjax](community/plugins-list.md#mathjax) formulas or even write custom processing of your own tags and annotations. - -For more info, see: - -* [Sample plugin tutorial](developer_guide/plugin-development/sample-plugin-tutorial.md) -* [Community plugins](community/plugins-list.md) -* [Developer guides](developer_guide/introduction.md) diff --git a/docs/src/doc/docs/survey_banner.js b/docs/src/doc/docs/survey_banner.js deleted file mode 100644 index 2feec82e..00000000 --- a/docs/src/doc/docs/survey_banner.js +++ /dev/null @@ -1,8 +0,0 @@ -window.addEventListener('load', () => { - const appended = document.createElement("a") - appended.style = "display: block;text-decoration: none !important;color: #E8F0FE !important;font-family: Inter, Arial, sans-serif !important;font-size: 18px;font-weight: 500;line-height: 24px;padding: 6px 0;position: relative;text-align: center;background-color: #7F52FF;z-index: 5000000;" - appended.href = "https://surveys.jetbrains.com/s3/dokka-survey" - appended.innerText = "Take part in our Dokka devX survey. It helps us a lot, and gives you a chance to win a prize! -->" - document.body.prepend(appended) - window.scrollTo(0, 0); -})
\ No newline at end of file diff --git a/docs/src/doc/docs/user_guide/applying/cli.md b/docs/src/doc/docs/user_guide/applying/cli.md deleted file mode 100644 index 3b02add2..00000000 --- a/docs/src/doc/docs/user_guide/applying/cli.md +++ /dev/null @@ -1,158 +0,0 @@ -# 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 <arguments> -``` - -## 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 `<path>=<url>[#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 <dokka_cli.jar> <path_to_config.json> - ``` - -## 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/docs/src/doc/docs/user_guide/applying/gradle.md b/docs/src/doc/docs/user_guide/applying/gradle.md deleted file mode 100644 index 435824f9..00000000 --- a/docs/src/doc/docs/user_guide/applying/gradle.md +++ /dev/null @@ -1,380 +0,0 @@ -# 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<DokkaTask>("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", "<kotlin-version>"))` resp. `implementation("org.jetbrains.kotlin:kotlin-gradle-plugin:<kotlin-version>")`). - -## 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<PluginClass, ConfigurationClass>{ - // 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<DokkaTask>().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<DokkaBase, DokkaBaseConfiguration> { - customAssets = listOf(file("<path to asset>")) - customStyleSheets = listOf(file("<path to custom stylesheet>")) -} -``` - -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("<plugin coordinates>:<plugin version>") - 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("<fully qualified plugin's name>" to """<json configuration>""")) -``` -## 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/docs/src/doc/docs/user_guide/applying/maven.md b/docs/src/doc/docs/user_guide/applying/maven.md deleted file mode 100644 index cde6e927..00000000 --- a/docs/src/doc/docs/user_guide/applying/maven.md +++ /dev/null @@ -1,243 +0,0 @@ -# Using the Maven plugin - -!!! note - Dokka Maven plugin does not support multi-platform projects. - -Minimal Maven configuration is - -```xml -<plugin> - <groupId>org.jetbrains.dokka</groupId> - <artifactId>dokka-maven-plugin</artifactId> - <version>${dokka.version}</version> - <executions> - <execution> - <phase>pre-site</phase> - <goals> - <goal>dokka</goal> - </goals> - </execution> - </executions> -</plugin> -``` - -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 -<plugin> - <groupId>org.jetbrains.dokka</groupId> - <artifactId>dokka-maven-plugin</artifactId> - <version>${dokka.version}</version> - <executions> - <execution> - <phase>pre-site</phase> - <goals> - <goal>dokka</goal> - </goals> - </execution> - </executions> - <configuration> - - <!-- Set to true to skip dokka task, default: false --> - <skip>false</skip> - - <!-- Default: ${project.artifactId} --> - <moduleName>data</moduleName> - - <!-- Default: ${project.basedir}/target/dokka --> - <outputDir>some/out/dir</outputDir> - - <!-- Use default or set to custom path to cache directory to enable package-list caching. --> - <!-- When set to default, caches stored in $USER_HOME/.cache/dokka --> - <cacheRoot>default</cacheRoot> - - <!-- Set to true to to prevent resolving package-lists online. --> - <!-- When this option is set to true, only local files are resolved, default: false --> - <offlineMode>false</offlineMode> - - <!-- List of '.md' files with package and module docs --> - <!-- https://kotlinlang.org/docs/reference/kotlin-doc.html#module-and-package-documentation --> - <includes> - <include>packages.md</include> - <include>extra.md</include> - </includes> - - <!-- A list of visibility modifiers that should be documented --> - <!-- If set by user, overrides includeNonPublic. Default is PUBLIC --> - <documentedVisibilities> - <visibility>PUBLIC</visibility> <!-- Same for both kotlin and java --> - <visibility>PRIVATE</visibility> <!-- Same for both kotlin and java --> - <visibility>PROTECTED</visibility> <!-- Same for both kotlin and java --> - <visibility>INTERNAL</visibility> <!-- Kotlin-specific internal modifier --> - <visibility>PACKAGE</visibility> <!-- Java-specific package-private visibility (default) --> - </documentedVisibilities> - - <!-- List of sample roots --> - <samples> - <dir>src/test/samples</dir> - </samples> - - <!-- Suppress obvious functions like default toString or equals. Defaults to true --> - <suppressObviousFunctions>false</suppressObviousFunctions> - - <!-- 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>true</suppressInheritedMembers> - - <!-- Used for linking to JDK, default: 6 --> - <jdkVersion>6</jdkVersion> - - <!-- Do not output deprecated members, applies globally, can be overridden by packageOptions --> - <skipDeprecated>false</skipDeprecated> - <!-- Emit warnings about not documented members, applies globally, also can be overridden by packageOptions --> - <reportUndocumented>true</reportUndocumented> - <!-- Do not create index pages for empty packages --> - <skipEmptyPackages>true</skipEmptyPackages> - - <!-- Short form list of sourceRoots, by default, set to ${project.compileSourceRoots} --> - <sourceDirectories> - <dir>src/main/kotlin</dir> - </sourceDirectories> - - <!-- Full form list of sourceRoots --> - <sourceRoots> - <root> - <path>src/main/kotlin</path> - <!-- See platforms section of documentation --> - <platforms>JVM</platforms> - </root> - </sourceRoots> - - <!-- Specifies the location of the project source code on the Web. If provided, Dokka generates "source" links - for each declaration. --> - <sourceLinks> - <link> - <!-- Source directory --> - <path>${project.basedir}/src/main/kotlin</path> - <!-- URL showing where the source code can be accessed through the web browser --> - <url>https://github.com/cy6erGn0m/vertx3-lang-kotlin/blob/master/src/main/kotlin</url> <!-- //remove src/main/kotlin if you use "./" above --> - <!--Suffix which is used to append the line number to the URL. Use #L for GitHub --> - <lineSuffix>#L</lineSuffix> - </link> - </sourceLinks> - - <!-- Disable linking to online kotlin-stdlib documentation --> - <noStdlibLink>false</noStdlibLink> - - <!-- Disable linking to online JDK documentation --> - <noJdkLink>false</noJdkLink> - - <!-- Allows linking to documentation of the project's dependencies (generated with Javadoc or Dokka) --> - <externalDocumentationLinks> - <link> - <!-- Root URL of the generated documentation to link with. The trailing slash is required! --> - <url>https://example.com/docs/</url> - <!-- If package-list file located in non-standard location --> - <!-- <packageListUrl>file:///home/user/localdocs/package-list</packageListUrl> --> - </link> - </externalDocumentationLinks> - - <!-- Allows to customize documentation generation options on a per-package basis --> - <perPackageOptions> - <packageOptions> - <!-- Will match kotlin and all sub-packages of it --> - <matchingRegex>kotlin($|\.).*</matchingRegex> - - <!-- All options are optional, default values are below: --> - <skipDeprecated>false</skipDeprecated> - - <!-- Emit warnings about not documented members --> - <reportUndocumented>true</reportUndocumented> - - <!-- Deprecated. Prefer using documentedVisibilities --> - <includeNonPublic>false</includeNonPublic> - - <!-- A list of visibility modifiers that should be documented --> - <!-- If set by user, overrides includeNonPublic. Default is PUBLIC --> - <documentedVisibilities> - <visibility>PUBLIC</visibility> <!-- Same for both kotlin and java --> - <visibility>PRIVATE</visibility> <!-- Same for both kotlin and java --> - <visibility>PROTECTED</visibility> <!-- Same for both kotlin and java --> - <visibility>INTERNAL</visibility> <!-- Kotlin-specific internal modifier --> - <visibility>PACKAGE</visibility> <!-- Java-specific package-private visibility (default) --> - </documentedVisibilities> - </packageOptions> - </perPackageOptions> - - <!-- Allows to use any dokka plugin, eg. GFM format --> - <dokkaPlugins> - <plugin> - <groupId>org.jetbrains.dokka</groupId> - <artifactId>gfm-plugin</artifactId> - <version>${dokka.version}</version> - </plugin> - </dokkaPlugins> - - <!-- Configures a plugin separately --> - <pluginsConfiguration> - <fullyQualifiedPluginName> - <!-- Configuration --> - </fullyQualifiedPluginName> - </pluginsConfiguration> - - </configuration> -</plugin> -``` - -## Applying plugins -You can add plugins inside the `dokkaPlugins` block: - -```xml -<plugin> - <groupId>org.jetbrains.dokka</groupId> - <artifactId>dokka-maven-plugin</artifactId> - <version>${dokka.version}</version> - <executions> - <execution> - <phase>pre-site</phase> - <goals> - <goal>dokka</goal> - </goals> - </execution> - </executions> - <configuration> - <dokkaPlugins> - <plugin> - <groupId>org.jetbrains.dokka</groupId> - <artifactId>kotlin-as-java-plugin</artifactId> - <version>${dokka.version}</version> - </plugin> - </dokkaPlugins> - </configuration> -</plugin> -``` - -Some plugins can be configured separately using plugin's fully qualified name. For example: - -```xml -<pluginsConfiguration> - <org.jetbrains.dokka.base.DokkaBase> - <customStyleSheets> - <customStyleSheet><!-- path to custom stylesheet --></customStyleSheet> - </customStyleSheets> - <customAssets> - <customAsset><!-- path to custom asset --></customAsset> - </customAssets> - </org.jetbrains.dokka.base.DokkaBase> -</pluginsConfiguration> -``` - -## Example project - -Please see the [Dokka Maven example project](https://github.com/Kotlin/dokka/tree/master/examples/maven) for an example. diff --git a/docs/src/doc/docs/user_guide/introduction.md b/docs/src/doc/docs/user_guide/introduction.md deleted file mode 100644 index cb263ebe..00000000 --- a/docs/src/doc/docs/user_guide/introduction.md +++ /dev/null @@ -1,74 +0,0 @@ -# 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/docs/src/doc/docs/user_guide/output-formats/html.md b/docs/src/doc/docs/user_guide/output-formats/html.md deleted file mode 100644 index 9a80a5d2..00000000 --- a/docs/src/doc/docs/user_guide/output-formats/html.md +++ /dev/null @@ -1,112 +0,0 @@ -# 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="...""> ...</@template_cmd>` - 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"> - <span>${projectName}</span> - </@template_cmd> - ``` diff --git a/docs/src/doc/docs/user_guide/plugins/android-plugin.md b/docs/src/doc/docs/user_guide/plugins/android-plugin.md deleted file mode 100644 index d52c2e5a..00000000 --- a/docs/src/doc/docs/user_guide/plugins/android-plugin.md +++ /dev/null @@ -1,8 +0,0 @@ -# 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/docs/src/doc/docs/user_guide/plugins/versioning-plugin.md b/docs/src/doc/docs/user_guide/plugins/versioning-plugin.md deleted file mode 100644 index 876ec436..00000000 --- a/docs/src/doc/docs/user_guide/plugins/versioning-plugin.md +++ /dev/null @@ -1,86 +0,0 @@ -# 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 - ├── <dokka output> - └── 1.4.20 - ├── <dokka output> - ... -``` - -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:<dokka_version>") - } -} - -... - -pluginConfiguration<org.jetbrains.dokka.versioning.VersioningPlugin, org.jetbrains.dokka.versioning.VersioningConfiguration> { - 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). diff --git a/docs/src/doc/mkdocs.yml b/docs/src/doc/mkdocs.yml deleted file mode 100644 index 9e101c00..00000000 --- a/docs/src/doc/mkdocs.yml +++ /dev/null @@ -1,99 +0,0 @@ -site_name: Dokka documentation - -# Meta tags (placed in header) -site_description: Dokka is an API documentation engine for Kotlin, performing the same function as the Javadoc tool for Java -site_author: JetBrains -site_url: https://github.com/Kotlin/dokka - -# Repository (add link to repository on each page) -repo_name: dokka -repo_url: https://github.com/Kotlin/dokka -edit_uri: edit/master/docs/src/doc/docs/ - -# Copyright (shown at the footer) -copyright: 'Copyright © 2022 JetBrains' - -# Material theme -theme: - name: 'material' - favicon: favicon.svg - social: - - type: 'github' - link: 'https://github.com/Kotlin/dokka' - features: - - navigation.expand - - navigation.tabs - - navigation.instant - - navigation.indexes - - navigation.top - -# Extensions -markdown_extensions: - - admonition - - codehilite: - guess_lang: false - - footnotes - - meta - - def_list - - toc: - permalink: true - - pymdownx.betterem: - smart_enable: all - - pymdownx.caret - - pymdownx.inlinehilite - - pymdownx.magiclink - - pymdownx.smartsymbols - - attr_list - - md_in_html - - pymdownx.superfences: - custom_fences: - - name: mermaid - class: mermaid - format: !!python/name:pymdownx.superfences.fence_code_format - -# Dev server binding -#dev_addr: 127.0.0.1:3001 - -nav: - - Home: - - index.md - - User guides: user_guide/introduction.md - - Developer guides: developer_guide/introduction.md - - Community: community/slack.md - - FAQ: faq.md - - User guides: - - User guides: user_guide/introduction.md - - Applying Dokka: - - Gradle: user_guide/applying/gradle.md - - Maven: user_guide/applying/maven.md - - Command line: user_guide/applying/cli.md - - Output formats: - - HTML: user_guide/output-formats/html.md - - Plugins: - - Versioning plugin: user_guide/plugins/versioning-plugin.md - - Android plugin: user_guide/plugins/android-plugin.md - - Developer guides: - - Developer guides: developer_guide/introduction.md - - Workflow: developer_guide/workflow.md - - Internals: - - Architecture: developer_guide/architecture/architecture_overview.md - - Data model: - - Documentables: developer_guide/architecture/data_model/documentables.md - - Page & Content: developer_guide/architecture/data_model/page_content.md - - Extra properties: developer_guide/architecture/data_model/extra.md - - Extension points: - - Extension points: developer_guide/architecture/extension_points/introduction.md - - Core extension points: developer_guide/architecture/extension_points/core_extensions.md - - Base extensions: developer_guide/architecture/extension_points/base_extensions.md - - Plugin development: - - Plugin development: developer_guide/plugin-development/introduction.md - - Sample plugin tutorial: developer_guide/plugin-development/sample-plugin-tutorial.md - - Community: - - Slack: community/slack.md - - Community plugins: community/plugins-list.md - - FAQ: faq.md - -extra_css: - - dokka_colors.css -extra_javascript: - - survey_banner.js
\ No newline at end of file diff --git a/docs/topics/dokka-get-started.md b/docs/topics/dokka-get-started.md new file mode 100644 index 00000000..df4ab7e5 --- /dev/null +++ b/docs/topics/dokka-get-started.md @@ -0,0 +1,95 @@ +[//]: # (title: Get started) + +Below you can find simple instructions to help you get started with Dokka. + +<tabs group="build-script"> +<tab title="Gradle Kotlin DSL" group-key="kotlin"> + +Apply the Gradle plugin for Dokka in the root build script of your project: + +```kotlin +plugins { + id("org.jetbrains.dokka") version "%dokkaVersion%" +} +``` + +When documenting [multi-project](https://docs.gradle.org/current/userguide/multi_project_builds.html) builds, you need +to apply the Gradle plugin within subprojects as well: + +```kotlin +subprojects { + apply(plugin = "org.jetbrains.dokka") +} +``` + +To generate documentation, run the following Gradle tasks: + +* `dokkaHtml` for single-project builds +* `dokkaHtmlMultiModule` for multi-project builds + +By default, the output directory is set to `/build/dokka/html` and `/build/dokka/htmlMultiModule`. + +To learn more about using Dokka with Gradle, see [Gradle](dokka-gradle.md). + +</tab> +<tab title="Gradle Groovy DSL" group-key="groovy"> + +Apply the Gradle plugin for Dokka in the root build script of your project: + +```groovy +plugins { + id 'org.jetbrains.dokka' version '%dokkaVersion%' +} +``` + +When documenting [multi-project](https://docs.gradle.org/current/userguide/multi_project_builds.html) builds, you need +to apply the Gradle plugin within subprojects as well: + +```groovy +subprojects { + apply plugin: 'org.jetbrains.dokka' +} +``` + +To generate documentation, run the following Gradle tasks: + +* `dokkaHtml` for single-project builds +* `dokkaHtmlMultiModule` for multi-project builds + +By default, the output directory is set to `/build/dokka/html` and `/build/dokka/htmlMultiModule`. + +To learn more about using Dokka with Gradle, see [Gradle](dokka-gradle.md). + +</tab> +<tab title="Maven" group-key="mvn"> + +Add the Maven plugin for Dokka to the `plugins` section of your POM file: + +```xml +<build> + <plugins> + <plugin> + <groupId>org.jetbrains.dokka</groupId> + <artifactId>dokka-maven-plugin</artifactId> + <version>%dokkaVersion%</version> + <executions> + <execution> + <phase>pre-site</phase> + <goals> + <goal>dokka</goal> + </goals> + </execution> + </executions> + </plugin> + </plugins> +</build> +``` + +To generate documentation, run the `dokka:dokka` goal. + +By default, the output directory is set to `target/dokka`. + +To learn more about using Dokka with Maven, see [Maven](dokka-maven.md). + +</tab> +</tabs> diff --git a/docs/topics/dokka-introduction.md b/docs/topics/dokka-introduction.md new file mode 100644 index 00000000..cc5cef78 --- /dev/null +++ b/docs/topics/dokka-introduction.md @@ -0,0 +1,28 @@ +[//]: # (title: Introduction) + +Dokka is an API documentation engine for Kotlin. + +Just like Kotlin itself, Dokka supports mixed-language projects. It understands Kotlin's +[KDoc comments](https://kotlinlang.org/docs/kotlin-doc.html#kdoc-syntax) and Java's +[Javadoc comments](https://www.oracle.com/technical-resources/articles/java/javadoc-tool.html). + +Dokka can generate documentation in multiple formats, including its own modern [HTML format](dokka-html.md), +multiple flavors of [Markdown](dokka-markdown.md), and Java's [Javadoc HTML](dokka-javadoc.md). + +Here are some libraries that use Dokka for their API reference documentation: + +* [kotlinx.coroutines](https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/) +* [Bitmovin](https://cdn.bitmovin.com/player/android/3/docs/index.html) +* [Hexagon](https://hexagonkt.com/api/index.html) +* [Ktor](https://api.ktor.io/) +* [OkHttp](https://square.github.io/okhttp/4.x/okhttp/okhttp3/) (Markdown) + +You can run Dokka using [Gradle](dokka-gradle.md), [Maven](dokka-maven.md) or from the [command line](dokka-cli.md). It is also +[highly pluggable](dokka-plugins.md). + +See [Get started](dokka-get-started.md) to take your first steps in using Dokka. + +## Community + +Dokka has a dedicated `#dokka` channel in [Kotlin Community Slack](https://surveys.jetbrains.com/s3/kotlin-slack-sign-up) +where you can chat about Dokka, its plugins and how to develop them, as well as get in touch with maintainers. diff --git a/docs/topics/dokka-plugins.md b/docs/topics/dokka-plugins.md new file mode 100644 index 00000000..5d3501ac --- /dev/null +++ b/docs/topics/dokka-plugins.md @@ -0,0 +1,278 @@ +[//]: # (title: Dokka plugins) + +Dokka was built from the ground up to be easily extensible and highly customizable, which allows the community +to implement plugins for missing or very specific features that are not provided out of the box. + +Dokka plugins range anywhere from supporting other programming language sources to exotic output formats. You can add +support for your own KDoc tags or annotations, teach Dokka how to render different DSLs that are found in KDoc +descriptions, visually redesign Dokka's pages to be seamlessly integrated into your company's website, integrate it +with other tools and so much more. + +If you want to learn how to create Dokka plugins, see +[Developer guides](https://kotlin.github.io/dokka/%dokkaVersion%/developer_guide/introduction/). + +## Apply Dokka plugins + +Dokka plugins are published as separate artifacts, so to apply a Dokka plugin you only need to add it as a dependency. +From there, the plugin extends Dokka by itself - no further action is needed. + +> Plugins that use the same extension points or work in a similar way can interfere with each other. +> This may lead to visual bugs, general undefined behaviour or even failed builds. However, it should not lead to +> concurrency issues since Dokka does not expose any mutable data structures or objects. +> +> If you notice problems like this, it's a good idea to check which plugins are applied and what they do. +> +{type="note"} + +Let's have a look at how you can apply the [mathjax plugin](https://github.com/Kotlin/dokka/tree/master/plugins/mathjax) +to your project: + +<tabs group="build-script"> +<tab title="Kotlin" group-key="kotlin"> + +The Gradle plugin for Dokka creates convenient dependency configurations that allow you to apply plugins universally or +for a specific output format only. + +```kotlin +dependencies { + // Is applied universally + dokkaPlugin("org.jetbrains.dokka:mathjax-plugin:%dokkaVersion%") + + // Is applied for the single-module dokkaHtml task only + dokkaHtmlPlugin("org.jetbrains.dokka:kotlin-as-java-plugin:%dokkaVersion%") + + // Is applied for HTML format in multi-project builds + dokkaHtmlPartialPlugin("org.jetbrains.dokka:kotlin-as-java-plugin:%dokkaVersion%") +} +``` + +> When documenting [multi-project](dokka-gradle.md#multi-project-builds) builds, you need to apply Dokka plugins within +> subprojects as well as in their parent project. +> +{type="note"} + +</tab> +<tab title="Groovy" group-key="groovy"> + +The Gradle plugin for Dokka creates convenient dependency configurations that allow you to apply Dokka plugins universally or +for a specific output format only. + +```groovy +dependencies { + // Is applied universally + dokkaPlugin 'org.jetbrains.dokka:mathjax-plugin:%dokkaVersion%' + + // Is applied for the single-module dokkaHtml task only + dokkaHtmlPlugin 'org.jetbrains.dokka:kotlin-as-java-plugin:%dokkaVersion%' + + // Is applied for HTML format in multi-project builds + dokkaHtmlPartialPlugin 'org.jetbrains.dokka:kotlin-as-java-plugin:%dokkaVersion%' +} +``` + +> When documenting [multi-project](dokka-gradle.md#multi-project-builds) builds, you need to apply Dokka plugins within +> subprojects as well as in their parent project. +> +{type="note"} + +</tab> +<tab title="Maven" group-key="mvn"> + +```xml +<plugin> + <groupId>org.jetbrains.dokka</groupId> + <artifactId>dokka-maven-plugin</artifactId> + ... + <configuration> + <dokkaPlugins> + <plugin> + <groupId>org.jetbrains.dokka</groupId> + <artifactId>mathjax-plugin</artifactId> + <version>%dokkaVersion%</version> + </plugin> + </dokkaPlugins> + </configuration> +</plugin> +``` + +</tab> +<tab title="CLI" group-key="cli"> + +If you are using the [CLI](dokka-cli.md) runner with [command line options](dokka-cli.md#run-with-command-line-options), +Dokka plugins should be passed as `.jar` files to `-pluginsClasspath`: + +```Shell +java -jar dokka-cli-%dokkaVersion%.jar \ + -pluginsClasspath "./dokka-base-%dokkaVersion%.jar;...;./mathjax-plugin-%dokkaVersion%.jar" \ + ... +``` + +If you are using [JSON configuration](dokka-cli.md#run-with-json-configuration), Dokka plugins should be specified under +`pluginsClasspath`. + +```json +{ + ... + "pluginsClasspath": [ + "./dokka-base-%dokkaVersion%.jar", + "...", + "./mathjax-plugin-%dokkaVersion%.jar" + ], + ... +} +``` + +</tab> +</tabs> + +## Configure Dokka plugins + +Dokka plugins can also have configuration options of their own. To see which options are available, consult +the documentation of the plugins you are using. + +Let's have a look at how you can configure the `DokkaBase` plugin, which is responsible for generating [HTML](dokka-html.md) +documentation, by adding a custom image to the assets (`customAssets` option), by adding custom style sheets +(`customStyleSheets` option), and by modifying the footer message (`footerMessage` option): + +<tabs group="build-script"> +<tab title="Kotlin" group-key="kotlin"> + +Gradle's Kotlin DSL allows for type-safe plugin configuration. This is achievable by adding the plugin's artifact to +the classpath dependencies in the `buildscript` block, and then importing plugin and configuration classes: + +```kotlin +import org.jetbrains.dokka.base.DokkaBase +import org.jetbrains.dokka.gradle.DokkaTask +import org.jetbrains.dokka.base.DokkaBaseConfiguration + +buildscript { + dependencies { + classpath("org.jetbrains.dokka:dokka-base:%dokkaVersion%") + } +} + +tasks.withType<DokkaTask>().configureEach { + pluginConfiguration<DokkaBase, DokkaBaseConfiguration> { + customAssets = listOf(file("my-image.png")) + customStyleSheets = listOf(file("my-styles.css")) + footerMessage = "(c) 2022 MyOrg" + } +} +``` + +Alternatively, plugins can be configured via JSON. With this method, no additional dependencies are needed. + +```kotlin +import org.jetbrains.dokka.gradle.DokkaTask + +tasks.withType<DokkaTask>().configureEach { + val dokkaBaseConfiguration = """ + { + "customAssets": ["${file("assets/my-image.png")}"], + "customStyleSheets": ["${file("assets/my-styles.css")}"], + "footerMessage": "(c) 2022 MyOrg" + } + """ + pluginsMapConfiguration.set( + mapOf( + // fully qualified plugin name to json configuration + "org.jetbrains.dokka.base.DokkaBase" to dokkaBaseConfiguration + ) + ) +} +``` + +</tab> +<tab title="Groovy" group-key="groovy"> + +```groovy +import org.jetbrains.dokka.gradle.DokkaTask + +tasks.withType(DokkaTask.class) { + String dokkaBaseConfiguration = """ + { + "customAssets": ["${file("assets/my-image.png")}"], + "customStyleSheets": ["${file("assets/my-styles.css")}"], + "footerMessage": "(c) 2022 MyOrg" + } + """ + pluginsMapConfiguration.set( + // fully qualified plugin name to json configuration + ["org.jetbrains.dokka.base.DokkaBase": dokkaBaseConfiguration] + ) +} +``` + +</tab> +<tab title="Maven" group-key="mvn"> + +```xml +<plugin> + <groupId>org.jetbrains.dokka</groupId> + <artifactId>dokka-maven-plugin</artifactId> + ... + <configuration> + <pluginsConfiguration> + <!-- Fully qualified plugin name --> + <org.jetbrains.dokka.base.DokkaBase> + <!-- Options by name --> + <customAssets> + <asset>${project.basedir}/my-image.png</asset> + </customAssets> + <customStyleSheets> + <stylesheet>${project.basedir}/my-styles.css</stylesheet> + </customStyleSheets> + <footerMessage>(c) MyOrg 2022 Maven</footerMessage> + </org.jetbrains.dokka.base.DokkaBase> + </pluginsConfiguration> + </configuration> +</plugin> +``` + +</tab> +<tab title="CLI" group-key="cli"> + +If you are using the [CLI](dokka-cli.md) runner with [command line options](dokka-cli.md#run-with-command-line-options), +use the `-pluginsConfiguration` option that accepts JSON configuration in the form of `fullyQualifiedPluginName=json`. + +If you need to configure multiple plugins, you can pass multiple values separated by `^^`. + +```Bash +java -jar dokka-cli-%dokkaVersion%.jar \ + ... + -pluginsConfiguration "org.jetbrains.dokka.base.DokkaBase={\"customAssets\": [\"my-image.png\"], \"customStyleSheets\": [\"my-styles.css\"], \"footerMessage\": \"(c) 2022 MyOrg CLI\"}" +``` + +If you are using [JSON configuration](dokka-cli.md#run-with-json-configuration), there exists a similar +`pluginsConfiguration` array that accepts JSON configuration in `values`. + +```json +{ + "moduleName": "Dokka Example", + "pluginsConfiguration": [ + { + "fqPluginName": "org.jetbrains.dokka.base.DokkaBase", + "serializationFormat": "JSON", + "values": "{\"customAssets\": [\"my-image.png\"], \"customStyleSheets\": [\"my-styles.css\"], \"footerMessage\": \"(c) 2022 MyOrg\"}" + } + ] +} +``` + +</tab> +</tabs> + +## Notable plugins + +Here are some notable Dokka plugins that you might find useful: + +| **Name** | **Description** | +|-----------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------| +| [Android documentation plugin](https://github.com/Kotlin/dokka/tree/master/plugins/android-documentation) | Improves the documentation experience on Android | +| [Versioning plugin](https://github.com/Kotlin/dokka/tree/master/plugins/versioning) | Adds version selector and helps to organize documentation for different versions of your application/library | +| [MermaidJS HTML plugin](https://github.com/glureau/dokka-mermaid) | Renders [MermaidJS](https://mermaid-js.github.io/mermaid/#/) diagrams and visualizations found in KDocs | +| [Mathjax HTML plugin](https://github.com/Kotlin/dokka/tree/master/plugins/mathjax) | Pretty prints mathematics found in KDocs | +| [Kotlin as Java plugin](https://github.com/Kotlin/dokka/tree/master/plugins/kotlin-as-java) | Renders Kotlin signatures as seen from Java's perspective | + +If you are a Dokka plugin author and would like to add your plugin to this list, get in touch with maintainers +via [Slack](dokka-introduction.md#community) or [GitHub](https://github.com/Kotlin/dokka/).
\ No newline at end of file diff --git a/docs/topics/formats/dokka-html.md b/docs/topics/formats/dokka-html.md new file mode 100644 index 00000000..dd81b2d9 --- /dev/null +++ b/docs/topics/formats/dokka-html.md @@ -0,0 +1,282 @@ +[//]: # (title: HTML) + +HTML is Dokka's default and recommended output format. You can see an example of the final result by browsing documentation +for [kotlinx.coroutines](https://kotlinlang.org/api/kotlinx.coroutines/). + +## Generate HTML documentation + +HTML as an output format is supported by all runners. To generate HTML documentation, follow these steps depending on +your build tool or runner: + +* For [Gradle](dokka-gradle.md#generate-documentation), run `dokkaHtml` or `dokkaHtmlMultiModule` tasks. +* For [Maven](dokka-maven.md#generate-documentation), run the `dokka:dokka` goal. +* For [CLI runner](dokka-cli.md#generate-documentation), run with HTML dependencies set. + +> HTML pages generated by this format need to be hosted on a web server in order to render everything correctly. +> +> You can use any free static site hosting service, such as +> [GitHub Pages](https://docs.github.com/en/pages/getting-started-with-github-pages/about-github-pages). +> +> Locally, you can use the [built-in IntelliJ web server](https://www.jetbrains.com/help/idea/php-built-in-web-server.html). +> +{type="note"} + +## Configuration + +HTML format is Dokka's base format, so it is configurable through `DokkaBase` and `DokkaBaseConfiguration` +classes: + +<tabs group="build-script"> +<tab title="Kotlin" group-key="kotlin"> + +Via type-safe Kotlin DSL: + +```kotlin +import org.jetbrains.dokka.base.DokkaBase +import org.jetbrains.dokka.gradle.DokkaTask +import org.jetbrains.dokka.base.DokkaBaseConfiguration + +buildscript { + dependencies { + classpath("org.jetbrains.dokka:dokka-base:%dokkaVersion%") + } +} + +tasks.withType<DokkaTask>().configureEach { + pluginConfiguration<DokkaBase, DokkaBaseConfiguration> { + customAssets = listOf(file("my-image.png")) + customStyleSheets = listOf(file("my-styles.css")) + footerMessage = "(c) 2022 MyOrg" + separateInheritedMembers = false + templatesDir = file("dokka/templates") + mergeImplicitExpectActualDeclarations = false + } +} +``` + +Via JSON: + +```kotlin +import org.jetbrains.dokka.gradle.DokkaTask + +tasks.withType<DokkaTask>().configureEach { + val dokkaBaseConfiguration = """ + { + "customAssets": ["${file("assets/my-image.png")}"], + "customStyleSheets": ["${file("assets/my-styles.css")}"], + "footerMessage": "(c) 2022 MyOrg", + "separateInheritedMembers": false, + "templatesDir": "${file("dokka/templates")}", + "mergeImplicitExpectActualDeclarations": false + } + """ + pluginsMapConfiguration.set( + mapOf( + // fully qualified plugin name to json configuration + "org.jetbrains.dokka.base.DokkaBase" to dokkaBaseConfiguration + ) + ) +} +``` + +</tab> +<tab title="Groovy" group-key="groovy"> + +```groovy +import org.jetbrains.dokka.gradle.DokkaTask + +tasks.withType(DokkaTask.class) { + String dokkaBaseConfiguration = """ + { + "customAssets": ["${file("assets/my-image.png")}"], + "customStyleSheets": ["${file("assets/my-styles.css")}"], + "footerMessage": "(c) 2022 MyOrg" + "separateInheritedMembers": false, + "templatesDir": "${file("dokka/templates")}", + "mergeImplicitExpectActualDeclarations": false + } + """ + pluginsMapConfiguration.set( + // fully qualified plugin name to json configuration + ["org.jetbrains.dokka.base.DokkaBase": dokkaBaseConfiguration] + ) +} +``` + +</tab> +<tab title="Maven" group-key="mvn"> + +```xml +<plugin> + <groupId>org.jetbrains.dokka</groupId> + <artifactId>dokka-maven-plugin</artifactId> + ... + <configuration> + <pluginsConfiguration> + <!-- Fully qualified plugin name --> + <org.jetbrains.dokka.base.DokkaBase> + <!-- Options by name --> + <customAssets> + <asset>${project.basedir}/my-image.png</asset> + </customAssets> + <customStyleSheets> + <stylesheet>${project.basedir}/my-styles.css</stylesheet> + </customStyleSheets> + <footerMessage>(c) MyOrg 2022 Maven</footerMessage> + <separateInheritedMembers>false</separateInheritedMembers> + <templatesDir>${project.basedir}/dokka/templates</templatesDir> + <mergeImplicitExpectActualDeclarations>false</mergeImplicitExpectActualDeclarations> + </org.jetbrains.dokka.base.DokkaBase> + </pluginsConfiguration> + </configuration> +</plugin> +``` + +</tab> +<tab title="CLI" group-key="cli"> + +Via [command line options](dokka-cli.md#run-with-command-line-options): + +```Bash +java -jar dokka-cli-%dokkaVersion%.jar \ + ... + -pluginsConfiguration "org.jetbrains.dokka.base.DokkaBase={\"customAssets\": [\"my-image.png\"], \"customStyleSheets\": [\"my-styles.css\"], \"footerMessage\": \"(c) 2022 MyOrg\", \"separateInheritedMembers\": false, \"templatesDir\": \"dokka/templates\", \"mergeImplicitExpectActualDeclarations\": false} +" +``` + +Via [JSON configuration](dokka-cli.md#run-with-json-configuration): + +```json +{ + "moduleName": "Dokka Example", + "pluginsConfiguration": [ + { + "fqPluginName": "org.jetbrains.dokka.base.DokkaBase", + "serializationFormat": "JSON", + "values": "{\"customAssets\": [\"my-image.png\"], \"customStyleSheets\": [\"my-styles.css\"], \"footerMessage\": \"(c) 2022 MyOrg\", \"separateInheritedMembers\": false, \"templatesDir\": \"dokka/templates\", \"mergeImplicitExpectActualDeclarations\": false}" + } + ] +} +``` + +</tab> +</tabs> + +### Configuration options + +The table below contains all of the possible configuration options and their purpose. + +| **Option** | **Description** | +|-----------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `customAssets` | List of paths for image assets to be bundled with documentation. The image assets can have any file extension. For more information, see [Customizing assets](#customize-assets). | +| `customStyleSheets` | List of paths for `.css` stylesheets to be bundled with documentation and used for rendering. For more information, see [Customizing styles](#customize-styles). | +| `templatesDir` | Path to the directory containing custom HTML templates. For more information, see [Templates](#templates). | +| `footerMessage` | The text displayed in the footer. | +| `separateInheritedMembers` | This is a boolean option. If set to `true`, Dokka renders properties/functions and inherited properties/inherited functions separately. This is disabled by default. | +| `mergeImplicitExpectActualDeclarations` | This is a boolean option. If set to `true`, Dokka merges declarations that are not declared as [expect/actual](https://kotlinlang.org/docs/multiplatform-connect-to-apis.html), but have the same fully qualified name. This can be useful for legacy codebases. This is disabled by default. | + +For more information about configuring Dokka plugins, see [Configuring Dokka plugins](dokka-plugins.md#configure-dokka-plugins). + +## Customization + +To help you add your own look and feel to your documentation, the HTML format supports a number of customization options. + +### Customize styles + +You can use your own stylesheets by using the `customStyleSheets` +[configuration option](#configuration). These are applied to every page. + +It's also possible to override Dokka's default stylesheets by providing files with the same name: + +| **Stylesheet name** | **Description** | +|----------------------|--------------------------------------------------------------------| +| `style.css` | Main stylesheet, contains most of the styles used across all pages | +| `logo-styles.css` | Header logo styling | +| `prism.css` | Styles for [PrismJS](https://prismjs.com/) syntax highlighter | +| `jetbrains-mono.css` | Font styling | + +The source code for all of Dokka's stylesheets is +[available on GitHub](https://github.com/Kotlin/dokka/tree/%dokkaVersion%/plugins/base/src/main/resources/dokka/styles). + +### Customize assets + +You can provide your own images to be bundled with documentation by using the `customAssets` +[configuration option](#configuration). + +These files are copied to the `<output>/images` directory. + +It's possible to override Dokka's images and icons by providing files with the same name. The most +useful and relevant one being `logo-icon.svg`, which is the image that's used in the header. The rest is mostly icons. + +You can find all images used by Dokka on +[GitHub](https://github.com/Kotlin/dokka/tree/%dokkaVersion%/plugins/base/src/main/resources/dokka/images). + +### Change the logo + +To customize the logo, you can begin by [providing your own asset](#customize-assets) for `logo-icon.svg`. + +If you don't like how it looks, or you want to use a `.png` file instead of the default `.svg` file, +you can [override the `logo-styles.css` stylesheet](#customize-styles) to customize it. + +For an example of how to do this, see our +[custom format example project](https://github.com/Kotlin/dokka/tree/%dokkaVersion%/examples/gradle/dokka-customFormat-example). + +### Modify the footer + +You can modify text in the footer by using the `footerMessage` [configuration option](#configuration). + +### Templates + +Dokka provides the ability to modify [FreeMarker](https://freemarker.apache.org/) templates used for generating +documentation pages. + +You can change the header completely, add your own banners/menus/search, load analytics, change body styling and so on. + +Dokka uses the following templates: + +| **Template** | **Description** | +|-----------------------------------|-----------------------------------------------------------------------------------------------------------------------| +| `base.ftl` | Defines the general design of all pages to be rendered. | +| `includes/header.ft` | The page header that by default contains the logo, version, source set selector, light/dark theme switch, and search. | +| `includes/footer.ft` | The page footer that contains the `footerMessage` [configuration option](#configuration) and copyright. | +| `includes/page_metadata.ft` | Metadata used within `<head>` container. | +| `includes/source_set_selector.ft` | [The source set](https://kotlinlang.org/docs/multiplatform-discover-project.html#source-sets) selector in the header. | + +The base template is `base.ftl` and it includes all of the remaining listed templates. You can find the source code for all of Dokka's templates +[on GitHub](https://github.com/Kotlin/dokka/tree/%dokkaVersion%/plugins/base/src/main/resources/dokka/templates). + +You can override any template by using the `templatesDir` [configuration option](#configuration). Dokka searches +for the exact template names within the given directory. If it fails to find user-defined templates, it uses the +default templates. + +#### Variables + +The following variables are available inside all templates: + +| **Variable** | **Description** | +|--------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `${pageName}` | The page name | +| `${footerMessage}` | The text which is set by the `footerMessage` [configuration option](#configuration) | +| `${sourceSets}` | A nullable list of [source sets](https://kotlinlang.org/docs/multiplatform-discover-project.html#source-sets) for multi-platform pages. Each item has `name`, `platform`, and `filter` properties. | +| `${projectName}` | The project name. It's available only within the `template_cmd` directive. | +| `${pathToRoot}` | The path to root from the current page. It's useful for locating assets and is available only within the `template_cmd` directive. | + +Variables `projectName` and `pathToRoot` are available only within the `template_cmd` directive as they require more +context and thus they need to be resolved at later stages by the [MultiModule](dokka-gradle.md#multi-project-builds) task: + +```html +<@template_cmd name="projectName"> + <span>${projectName}</span> +</@template_cmd> +``` + +#### Directives + +You can also use the following Dokka-defined [directives](https://freemarker.apache.org/docs/ref_directive_userDefined.html): + +| **Variable** | **Description** | +|-----------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `<@content/>` | The main page content. | +| `<@resources/>` | Resources such as scripts and stylesheets. | +| `<@version/>` | The module version taken from configuration. If the [versioning plugin](https://github.com/Kotlin/dokka/tree/master/plugins/versioning) is applied, it is replaced with a version navigator. | + diff --git a/docs/topics/formats/dokka-javadoc.md b/docs/topics/formats/dokka-javadoc.md new file mode 100644 index 00000000..4781afcb --- /dev/null +++ b/docs/topics/formats/dokka-javadoc.md @@ -0,0 +1,93 @@ +[//]: # (title: Javadoc) + +> The Javadoc output format is still in Alpha so you may find bugs and experience migration issues when using it. +> Successful integration with tools that accept Java's Javadoc HTML as input is not guaranteed. +> **You use it at your own risk.** +> +{type="warning"} + +Dokka's Javadoc output format is a lookalike of Java's +[Javadoc HTML format](https://docs.oracle.com/en/java/javase/19/docs/api/index.html). + +It tries to visually mimic HTML pages generated by the Javadoc tool, but it's not a direct implementation +or an exact copy. + +{height=750} + +All Kotlin code and signatures are rendered as seen from Java's perspective. This is achieved with our +[Kotlin as Java Dokka plugin](https://github.com/Kotlin/dokka/tree/master/plugins/kotlin-as-java), which comes bundled and +applied by default for this format. + +The Javadoc output format is implemented as a [Dokka plugin](dokka-plugins.md), and it is maintained by the Dokka team. +It is open source and you can find the source code on [GitHub](https://github.com/Kotlin/dokka/tree/master/plugins/javadoc). + +## Generate Javadoc documentation + +> The Javadoc format does not support multiplatform projects. +> +{type="warning"} + + +<tabs group="build-script"> +<tab title="Gradle" group-key="kotlin"> + +The [Gradle plugin for Dokka](dokka-gradle.md) comes with the Javadoc output format included. You can use the following tasks: + +| **Task** | **Description** | +|-------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `dokkaJavadoc` | Generates Javadoc documentation for a single project. | +| `dokkaJavadocCollector` | A [`Collector`](dokka-gradle.md#collector-tasks) task created only for parent projects in multi-project builds. It calls `dokkaJavadoc` for every subproject and merges all outputs into a single virtual project. | + +The `javadoc.jar` file can be generated separately. For more information, see [Building `javadoc.jar`](dokka-gradle.md#build-javadoc-jar). + +</tab> +<tab title="Maven" group-key="groovy"> + +The [Maven plugin for Dokka](dokka-maven.md) comes with the Javadoc output format built in. You can generate documentation +by using the following goals: + +| **Goal** | **Description** | +|--------------------|------------------------------------------------------------------------------| +| `dokka:javadoc` | Generates documentation in Javadoc format | +| `dokka:javadocJar` | Generates a `javadoc.jar` file that contains documentation in Javadoc format | + + +</tab> +<tab title="CLI" group-key="cli"> + +Since the Javadoc output format is a [Dokka plugin](dokka-plugins.md#apply-dokka-plugins), you need to +download the plugin's [JAR file](https://mvnrepository.com/artifact/org.jetbrains.dokka/javadoc-plugin/%dokkaVersion%). + +The Javadoc output format has two dependencies that you need to provide as additional JAR files: + +* [kotlin-as-java plugin](https://mvnrepository.com/artifact/org.jetbrains.dokka/kotlin-as-java-plugin/%dokkaVersion%) +* [korte-jvm](https://mvnrepository.com/artifact/com.soywiz.korlibs.korte/korte-jvm/3.3.0) + +Via [command line options](dokka-cli.md#run-with-command-line-options): + +```Bash +java -jar dokka-cli-%dokkaVersion%.jar \ + -pluginsClasspath "./dokka-base-%dokkaVersion%.jar;...;./javadoc-plugin-%dokkaVersion%.jar" \ + ... +``` + +Via [JSON configuration](dokka-cli.md#run-with-json-configuration): + +```json +{ + ... + "pluginsClasspath": [ + "./dokka-base-%dokkaVersion%.jar", + "...", + "./kotlin-as-java-plugin-%dokkaVersion%.jar", + "./korte-jvm-3.3.0.jar", + "./javadoc-plugin-%dokkaVersion%.jar" + ], + ... +} +``` + +For more information, see [Other output formats](dokka-cli.md#other-output-formats) in the CLI runner's documentation. + +</tab> +</tabs> diff --git a/docs/topics/formats/dokka-markdown.md b/docs/topics/formats/dokka-markdown.md new file mode 100644 index 00000000..d4919a5c --- /dev/null +++ b/docs/topics/formats/dokka-markdown.md @@ -0,0 +1,172 @@ +[//]: # (title: Markdown) + +> The Markdown output formats are still in Alpha so you may find bugs and experience migration issues when using them. **You use them at your own risk.** +> +{type="warning"} + +Dokka is able to generate documentation in [GitHub Flavored](#gfm) and [Jekyll](#jekyll) compatible Markdown. + +These formats give you more freedom in terms of hosting documentation as the output can be embedded right into your +documentation website. For example, see [OkHttp's API reference](https://square.github.io/okhttp/4.x/okhttp/okhttp3/) +pages. + +Markdown output formats are implemented as [Dokka plugins](dokka-plugins.md), maintained by the Dokka team, and +they are open source. + +## GFM + +The GFM output format generates documentation in [GitHub Flavored Markdown](https://github.github.com/gfm/). + +<tabs group="build-script"> +<tab title="Gradle" group-key="kotlin"> + +The [Gradle plugin for Dokka](dokka-gradle.md) comes with the GFM output format included. You can use the following tasks with it: + +| **Task** | **Description** | +|-----------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `dokkaGfm` | Generates GFM documentation for a single project. | +| `dokkaGfmMultiModule` | A [`MultiModule`](dokka-gradle.md#multi-project-builds) task created only for parent projects in multi-project builds. It generates documentation for subprojects and collects all outputs in a single place with a common table of contents. | +| `dokkaGfmCollector` | A [`Collector`](dokka-gradle.md#collector-tasks) task created only for parent projects in multi-project builds. It calls `dokkaGfm` for every subproject and merges all outputs into a single virtual project. | + +</tab> +<tab title="Maven" group-key="groovy"> + +Since GFM format is implemented as a [Dokka plugin](dokka-plugins.md#apply-dokka-plugins), you need to apply it as a plugin +dependency: + +```xml +<plugin> + <groupId>org.jetbrains.dokka</groupId> + <artifactId>dokka-maven-plugin</artifactId> + ... + <configuration> + <dokkaPlugins> + <plugin> + <groupId>org.jetbrains.dokka</groupId> + <artifactId>gfm-plugin</artifactId> + <version>%dokkaVersion%</version> + </plugin> + </dokkaPlugins> + </configuration> +</plugin> +``` + +After configuring this, running the `dokka:dokka` goal produces documentation in GFM format. + +For more information, see the Mavin plugin documentation for [Other output formats](dokka-maven.md#other-output-formats). + +</tab> +<tab title="CLI" group-key="cli"> + +Since GFM format is implemented as a [Dokka plugin](dokka-plugins.md#apply-dokka-plugins), you need to download the +[JAR file](https://mvnrepository.com/artifact/org.jetbrains.dokka/gfm-plugin/%dokkaVersion%) and pass it to +`pluginsClasspath`. + +Via [command line options](dokka-cli.md#run-with-command-line-options): + +```Bash +java -jar dokka-cli-%dokkaVersion%.jar \ + -pluginsClasspath "./dokka-base-%dokkaVersion%.jar;...;./gfm-plugin-%dokkaVersion%.jar" \ + ... +``` + +Via [JSON configuration](dokka-cli.md#run-with-json-configuration): + +```json +{ + ... + "pluginsClasspath": [ + "./dokka-base-%dokkaVersion%.jar", + "...", + "./gfm-plugin-%dokkaVersion%.jar" + ], + ... +} +``` + +For more information, see the CLI runner's documentation for [Other output formats](dokka-cli.md#other-output-formats). + +</tab> +</tabs> + +You can find the source code [on GitHub](https://github.com/Kotlin/dokka/tree/%dokkaVersion%/plugins/gfm). + +## Jekyll + +The Jekyll output format generates documentation in [Jekyll](https://jekyllrb.com/) compatible Markdown. + +<tabs group="build-script"> +<tab title="Gradle" group-key="kotlin"> + +The [Gradle plugin for Dokka](dokka-gradle.md) comes with the Jekyll output format included. You can use the following tasks with it: + +| **Task** | **Description** | +|--------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `dokkaJekyll` | Generates Jekyll documentation for a single project. | +| `dokkaJekyllMultiModule` | A [`MultiModule`](dokka-gradle.md#multi-project-builds) task created only for parent projects in multi-project builds. It generates documentation for subprojects and collects all outputs in a single place with a common table of contents. | +| `dokkaJekyllCollector` | A [`Collector`](dokka-gradle.md#collector-tasks) task created only for parent projects in multi-project builds. It calls `dokkaJekyll` for every subproject and merges all outputs into a single virtual project. | + +</tab> +<tab title="Maven" group-key="groovy"> + +Since Jekyll format is implemented as a [Dokka plugin](dokka-plugins.md#apply-dokka-plugins), you need to apply it as a plugin +dependency: + +```xml +<plugin> + <groupId>org.jetbrains.dokka</groupId> + <artifactId>dokka-maven-plugin</artifactId> + ... + <configuration> + <dokkaPlugins> + <plugin> + <groupId>org.jetbrains.dokka</groupId> + <artifactId>jekyll-plugin</artifactId> + <version>%dokkaVersion%</version> + </plugin> + </dokkaPlugins> + </configuration> +</plugin> +``` + +After configuring this, running the `dokka:dokka` goal produces documentation in GFM format. + +For more information, see the Maven plugin's documentation for [Other output formats](dokka-maven.md#other-output-formats). + +</tab> +<tab title="CLI" group-key="cli"> + +Since Jekyll format is implemented as a [Dokka plugin](dokka-plugins.md#apply-dokka-plugins), you need to download the +[JAR file](https://mvnrepository.com/artifact/org.jetbrains.dokka/jekyll-plugin/%dokkaVersion%). This format is also +based on [GFM](#gfm) format, so you need to provide it as a dependency as well. Both JARs need to be passed to +`pluginsClasspath`: + +Via [command line options](dokka-cli.md#run-with-command-line-options): + +```Bash +java -jar dokka-cli-%dokkaVersion%.jar \ + -pluginsClasspath "./dokka-base-%dokkaVersion%.jar;...;./gfm-plugin-%dokkaVersion%.jar;./jekyll-plugin-%dokkaVersion%.jar" \ + ... +``` + +Via [JSON configuration](dokka-cli.md#run-with-json-configuration): + +```json +{ + ... + "pluginsClasspath": [ + "./dokka-base-%dokkaVersion%.jar", + "...", + "./gfm-plugin-%dokkaVersion%.jar", + "./jekyll-plugin-%dokkaVersion%.jar" + ], + ... +} +``` + +For more information, see the CLI runner's documentation for [Other output formats](dokka-cli.md#other-output-formats). + +</tab> +</tabs> + +You can find the source code on [GitHub](https://github.com/Kotlin/dokka/tree/%dokkaVersion%/plugins/jekyll). 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" + ] +} +``` + +<deflist collapsible="true"> + <def title="moduleName"> + <p>The display name used to refer to the module. It is used for the table of contents, navigation, logging, etc.</p> + <p>Default: <code>root</code></p> + </def> + <def title="moduleVersion"> + <p>The module version.</p> + <p>Default: empty</p> + </def> + <def title="outputDirectory"> + <p>The directory to where documentation is generated, regardless of output format.</p> + <p>Default: <code>./dokka</code></p> + </def> + <def title="failOnWarning"> + <p> + 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. + </p> + <p>This setting works well with <code>reportUndocumented</code></p> + <p>Default: <code>false</code></p> + </def> + <def title="suppressObviousFunctions"> + <p>Whether to suppress obvious functions.</p> + <p> + A function is considered to be obvious if it is: + <list> + <li> + Inherited from <code>kotlin.Any</code>, <code>Kotlin.Enum</code>, <code>java.lang.Object</code> or + <code>java.lang.Enum</code>, such as <code>equals</code>, <code>hashCode</code>, <code>toString</code>. + </li> + <li> + Synthetic (generated by the compiler) and does not have any documentation, such as + <code>dataClass.componentN</code> or <code>dataClass.copy</code>. + </li> + </list> + </p> + <p>Default: <code>true</code></p> + </def> + <def title="suppressInheritedMembers"> + <p>Whether to suppress inherited members that aren't explicitly overridden in a given class.</p> + <p> + Note: This can suppress functions such as <code>equals</code> / <code>hashCode</code> / <code>toString</code>, + but cannot suppress synthetic functions such as <code>dataClass.componentN</code> and + <code>dataClass.copy</code>. Use <code>suppressObviousFunctions</code> + for that. + </p> + <p>Default: <code>false</code></p> + </def> + <def title="offlineMode"> + <p>Whether to resolve remote files/links over your network.</p> + <p> + This includes package-lists used for generating external documentation links. + For example, to make classes from the standard library clickable. + </p> + <p> + Setting this to <code>true</code> 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. + </p> + <p> + Note: You can cache fetched files locally and provide them to + Dokka as local paths. See <code>externalDocumentationLinks</code> section. + </p> + <p>Default: <code>false</code></p> + </def> + <def title="includes"> + <p> + A list of Markdown files that contain + <a href="https://kotlinlang.org/docs/reference/kotlin-doc.html#module-and-package-documentation">module and package documentation</a>. + </p> + <p>The contents of specified files are parsed and embedded into documentation as module and package descriptions.</p> + <p>This can be configured on per-package basis.</p> + </def> + <def title="sourceSets"> + <p> + Individual and additional configuration of Kotlin + <a href="https://kotlinlang.org/docs/multiplatform-discover-project.html#source-sets">source sets</a>. + </p> + <p>For a list of possible options, see <a href="#source-set-configuration">source set configuration</a>.</p> + </def> + <def title="sourceLinks"> + <p>The global configuration of source links that is applied for all source sets.</p> + <p>For a list of possible options, see <a href="#source-link-configuration">source link configuration</a>.</p> + </def> + <def title="perPackageOptions"> + <p>The global configuration of matched packages, regardless of the source set they are in.</p> + <p>For a list of possible options, see <a href="#per-package-configuration">per-package configuration</a>.</p> + </def> + <def title="externalDocumentationLinks"> + <p>The global configuration of external documentation links, regardless of the source set they are used in.</p> + <p>For a list of possible options, see <a href="#external-documentation-configuration">external documentation configuration</a>.</p> + </def> + <def title="pluginsClasspath"> + <p>A list of JAR files with Dokka plugins and their dependencies.</p> + </def> +</deflist> + +### 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" } + ] + } + ] +} +``` + +<deflist collapsible="true"> + <def title="displayName"> + <p>The display name used to refer to this source set.</p> + <p> + 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 <code>reportUndocumented</code>). + </p> + <p>The platform name can be used if you don't have a better alternative.</p> + </def> + <def title="sourceSetID"> + <p>The technical ID of the source set</p> + </def> + <def title="documentedVisibilities"> + <p>The set of visibility modifiers that should be documented.</p> + <p> + 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. + </p> + <p>This can be configured on per-package basis.</p> + <p> + Possible values: + <list> + <li><code>PUBLIC</code></li> + <li><code>PRIVATE</code></li> + <li><code>PROTECTED</code></li> + <li><code>INTERNAL</code></li> + <li><code>PACKAGE</code></li> + </list> + </p> + <p>Default: <code>PUBLIC</code></p> + </def> + <def title="reportUndocumented"> + <p> + Whether to emit warnings about visible undocumented declarations, that is declarations without KDocs + after they have been filtered by <code>documentedVisibilities</code> and other filters. + </p> + <p>This setting works well with <code>failOnWarning</code>.</p> + <p>This can be configured on per-package basis.</p> + <p>Default: <code>false</code></p> + </def> + <def title="skipEmptyPackages"> + <p> + Whether to skip packages that contain no visible declarations after + various filters have been applied. + </p> + <p> + For example, if <code>skipDeprecated</code> is set to <code>true</code> and your package contains only + deprecated declarations, it is considered to be empty. + </p> + <p>Default for CLI runner is <code>false</code>.</p> + </def> + <def title="skipDeprecated"> + <p>Whether to document declarations annotated with <code>@Deprecated</code>.</p> + <p>This can be configured on per-package basis.</p> + <p>Default: <code>false</code></p> + </def> + <def title="jdkVersion"> + <p>The JDK version to use when generating external documentation links for Java types.</p> + <p> + For example, if you use <code>java.util.UUID</code> in some public declaration signature, + and this option is set to <code>8</code>, Dokka generates an external documentation link + to <a href="https://docs.oracle.com/javase/8/docs/api/java/util/UUID.html">JDK 8 Javadocs</a> for it. + </p> + </def> + <def title="languageVersion"> + <p> + <a href="https://kotlinlang.org/docs/compatibility-modes.html">The Kotlin language version</a> + used for setting up analysis and <a href="https://kotlinlang.org/docs/kotlin-doc.html#sample-identifier">@sample</a> + environment. + </p> + </def> + <def title="apiVersion"> + <p> + <a href="https://kotlinlang.org/docs/compatibility-modes.html">The Kotlin API version</a> + used for setting up analysis and <a href="https://kotlinlang.org/docs/kotlin-doc.html#sample-identifier">@sample</a> + environment. + </p> + </def> + <def title="noStdlibLink"> + <p> + Whether to generate external documentation links that lead to the API reference + documentation of Kotlin's standard library. + </p> + <p>Note: Links <b>are</b> generated when <code>noStdLibLink</code> is set to <code>false</code>.</p> + <p>Default: <code>false</code></p> + </def> + <def title="noJdkLink"> + <p>Whether to generate external documentation links to JDK's Javadocs.</p> + <p>The version of JDK Javadocs is determined by the <code>jdkVersion</code> option.</p> + <p>Note: Links <b>are</b> generated when <code>noJdkLink</code> is set to <code>false</code>.</p> + <p>Default: <code>false</code></p> + </def> + <def title="includes"> + <p> + A list of Markdown files that contain + <a href="https://kotlinlang.org/docs/reference/kotlin-doc.html#module-and-package-documentation">module and package documentation</a>. + </p> + <p>The contents of the specified files are parsed and embedded into documentation as module and package descriptions.</p> + </def> + <def title="analysisPlatform"> + <p> + Platform to be used for setting up code analysis and + <a href="https://kotlinlang.org/docs/kotlin-doc.html#sample-identifier">@sample</a> environment. + </p> + <p> + Possible values: + <list> + <li><code>jvm</code></li> + <li><code>common</code></li> + <li><code>js</code></li> + <li><code>native</code></li> + </list> + </p> + </def> + <def title="sourceRoots"> + <p> + The source code roots to be analyzed and documented. + Acceptable inputs are directories and individual <code>.kt</code> / <code>.java</code> files. + </p> + </def> + <def title="classpath"> + <p>The classpath for analysis and interactive samples.</p> + <p>This is useful if some types that come from dependencies are not resolved/picked up automatically.</p> + <p>This option accepts both <code>.jar</code> and <code>.klib</code> files.</p> + </def> + <def title="samples"> + <p> + A list of directories or files that contain sample functions which are referenced via the + <a href="https://kotlinlang.org/docs/kotlin-doc.html#sample-identifier">@sample</a> KDoc tag. + </p> + </def> + <def title="suppressedFiles"> + <p>The files to be suppressed when generating documentation.</p> + </def> + <def title="sourceLinks"> + <p>A set of parameters for source links that is applied only for this source set.</p> + <p>For a list of possible options, see <a href="#source-link-configuration">source link configuration</a>.</p> + </def> + <def title="perPackageOptions"> + <p>A set of parameters specific to matched packages within this source set.</p> + <p>For a list of possible options, see <a href="#per-package-configuration">per-package configuration</a>.</p> + </def> + <def title="externalDocumentationLinks"> + <p>A set of parameters for external documentation links that is applied only for this source set.</p> + <p>For a list of possible options, see <a href="#external-documentation-configuration">external documentation configuration</a>.</p> + </def> +</deflist> + +### 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" + } + ] +} +``` + +<deflist collapsible="true"> + <def title="localDirectory"> + <p>The path to the local source directory.</p> + </def> + <def title="remoteUrl"> + <p> + 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. + </p> + </def> + <def title="remoteLineSuffix"> + <p> + 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. + </p> + <p> + The number itself is appended to the specified suffix. For example, + if this option is set to <code>#L</code> and the line number is 10, the resulting URL suffix + is <code>#L10</code>. + </p> + <p> + Suffixes used by popular services: + <list> + <li>GitHub: <code>#L</code></li> + <li>GitLab: <code>#L</code></li> + <li>Bitbucket: <code>#lines-</code></li> + </list> + </p> + <p>Default: empty (no suffix)</p> + </def> +</deflist> + +### 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"] + } + ] +} +``` + +<deflist collapsible="true"> + <def title="matchingRegex"> + <p>The regular expression that is used to match the package.</p> + </def> + <def title="suppress"> + <p>Whether this package should be skipped when generating documentation.</p> + <p>Default: <code>false</code></p> + </def> + <def title="skipDeprecated"> + <p>Whether to document declarations annotated with <code>@Deprecated</code>.</p> + <p>This can be set on project/module level.</p> + <p>Default: <code>false</code></p> + </def> + <def title="reportUndocumented"> + <p> + Whether to emit warnings about visible undocumented declarations, that is declarations without KDocs + after they have been filtered by <code>documentedVisibilities</code> and other filters. + </p> + <p>This setting works well with <code>failOnWarning</code>.</p> + <p>This can be configured on source set level.</p> + <p>Default: <code>false</code></p> + </def> + <def title="documentedVisibilities"> + <p>The set of visibility modifiers that should be documented.</p> + <p> + 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. + </p> + <p>Can be configured on source set level.</p> + <p>Default: <code>PUBLIC</code></p> + </def> +</deflist> + +### 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" + } + ] +} +``` + +<deflist collapsible="true"> + <def title="url"> + <p>The root URL of documentation to link to. It <b>must</b> contain a trailing slash.</p> + <p> + Dokka does its best to automatically find <code>package-list</code> for the given URL, + and link declarations together. + </p> + <p> + If automatic resolution fails or if you want to use locally cached files instead, + consider setting the <code>packageListUrl</code> option. + </p> + </def> + <def title="packageListUrl"> + <p> + The exact location of a <code>package-list</code>. This is an alternative to relying on Dokka + automatically resolving it. + </p> + <p> + Package lists contain information about the documentation and the project itself, + such as module and package names. + </p> + <p>This can also be a locally cached file to avoid network calls.</p> + </def> +</deflist> + +### 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): + +<tabs group="build-script"> +<tab title="Kotlin" group-key="kotlin"> + +```kotlin +plugins { + id("org.jetbrains.dokka") version "%dokkaVersion%" +} +``` + +</tab> +<tab title="Groovy" group-key="groovy"> + +```groovy +plugins { + id 'org.jetbrains.dokka' version '%dokkaVersion%' +} +``` + +</tab> +</tabs> + +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: + +<tabs group="build-script"> +<tab title="Gradle Kotlin DSL" group-key="kotlin"> + +```kotlin +subprojects { + apply(plugin = "org.jetbrains.dokka") +} +``` + +</tab> +<tab title="Gradle Groovy DSL" group-key="groovy"> + +```groovy +subprojects { + apply plugin: 'org.jetbrains.dokka' +} +``` + +</tab> +</tabs> + +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: +> +> <tabs group="build-script"> +> <tab title="Kotlin" group-key="kotlin"> +> +> ```kotlin +> implementation(kotlin("gradle-plugin", "%kotlinVersion%")) +> ``` +> +> </tab> +> <tab title="Groovy" group-key="groovy"> +> +> ```groovy +> implementation 'org.jetbrains.kotlin:kotlin-gradle-plugin:%kotlinVersion%' +> ``` +> +> </tab> +> </tabs> +> +{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`: + +{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`: + +{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: + +<tabs group="build-script"> +<tab title="Kotlin" group-key="kotlin"> + +```kotlin +tasks.register<Jar>("dokkaHtmlJar") { + dependsOn(tasks.dokkaHtml) + from(tasks.dokkaHtml.flatMap { it.outputDirectory }) + archiveClassifier.set("html-docs") +} + +tasks.register<Jar>("dokkaJavadocJar") { + dependsOn(tasks.dokkaJavadoc) + from(tasks.dokkaJavadoc.flatMap { it.outputDirectory }) + archiveClassifier.set("javadoc") +} +``` + +</tab> +<tab title="Groovy" group-key="groovy"> + +```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") +} +``` + +</tab> +</tabs> + +> 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: + +<tabs group="build-script"> +<tab title="Kotlin" group-key="kotlin"> + +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 +``` + +</tab> +<tab title="Groovy" group-key="groovy"> + +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 +``` + +</tab> +</tabs> + +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: + +<tabs group="build-script"> +<tab title="Kotlin" group-key="kotlin"> + +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")) +} +``` + +</tab> +<tab title="Groovy" group-key="groovy"> + +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")) +} +``` + +</tab> +</tabs> + +Or you can configure all tasks and output formats at the same time: + +<tabs group="build-script"> +<tab title="Kotlin" group-key="kotlin"> + +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<DokkaTask>().configureEach { + dokkaSourceSets.configureEach { + documentedVisibilities.set( + setOf( + Visibility.PUBLIC, + Visibility.PROTECTED, + ) + ) + + perPackageOption { + matchingRegex.set(".*internal.*") + suppress.set(true) + } + } +} +``` + +</tab> +<tab title="Groovy" group-key="groovy"> + +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) + } + } +} +``` + +</tab> +</tabs> + +### 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: + +<tabs group="build-script"> +<tab title="Kotlin" group-key="kotlin"> + +```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 +``` + +</tab> +<tab title="Groovy" group-key="groovy"> + +```text +. +├── build.gradle +├── settings.gradle +├── subproject-A + └── build.gradle + └── src + └── main + └── kotlin + └── HelloFromA.kt +├── subproject-B + └── build.gradle + └── src + └── main + └── kotlin + └── HelloFromB.kt +``` + +</tab> +</tabs> + +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: + +<tabs group="build-script"> +<tab title="Kotlin" group-key="kotlin"> + +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<DokkaTaskPartial>().configureEach { + dokkaSourceSets.configureEach { + includes.from("README.md") + } + } +} +``` + +</tab> +<tab title="Groovy" group-key="groovy"> + +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") + } + } +} +``` + +</tab> +</tabs> + +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`: + +<tabs group="build-script"> +<tab title="Kotlin" group-key="kotlin"> + +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")) +} +``` + +</tab> +<tab title="Groovy" group-key="groovy"> + +Inside `./subproject-A/build.gradle`: + +```groovy +apply plugin: 'org.jetbrains.dokka' + +// configuration for subproject-A only. +dokkaHtmlPartial { + outputDirectory.set(file("build/docs/partial")) +} +``` + +</tab> +</tabs> + +#### 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: + +<tabs group="build-script"> +<tab title="Kotlin" group-key="kotlin"> + +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") +} +``` + +</tab> +<tab title="Groovy" group-key="groovy"> + +In the root `./build.gradle` file: + +```groovy +plugins { + id 'org.jetbrains.dokka' version '%dokkaVersion%' +} + +dokkaHtmlMultiModule { + moduleName.set("WHOLE PROJECT NAME USED IN THE HEADER") +} +``` + +</tab> +</tabs> + +## 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: + +<tabs group="build-script"> +<tab title="Kotlin" group-key="kotlin"> + +```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<DokkaTask>().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) + + // .. + // source set configuration section + // .. +} +``` + +</tab> +<tab title="Groovy" group-key="groovy"> + +```groovy +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(DokkaTask.class) { + moduleName.set(project.name) + moduleVersion.set(project.version.toString()) + outputDirectory.set(file("build/dokka/$name")) + failOnWarning.set(false) + suppressObviousFunctions.set(true) + suppressInheritedMembers.set(false) + offlineMode.set(false) + + // .. + // source set configuration section + // .. +} +``` + +</tab> +</tabs> + +<deflist collapsible="true"> + <def title="moduleName"> + <p>The display name used to refer to the module. It is used for the table of contents, navigation, logging, etc.</p> + <p>If set for a single-project build or a <code>MultiModule</code> task, it is used as the project name.</p> + <p>Default: Gradle project name</p> + </def> + <def title="moduleVersion"> + <p> + The module version. If set for a single-project build or a <code>MultiModule</code> task, it is used as the + project version. + </p> + <p>Default: Gradle project version</p> + </def> + <def title="outputDirectory"> + <p>The directory to where documentation is generated, regardless of format. It can be set on a per-task basis.</p> + <p> + The default is <code>{project}/{buildDir}/{format}</code>, where <code>{format}</code> is the task name with + the "dokka" prefix removed. For the <code>dokkaHtmlMultiModule</code> task, it is + <code>project/buildDir/htmlMultiModule</code>. + </p> + </def> + <def title="failOnWarning"> + <p> + 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. + </p> + <p>This setting works well with <code>reportUndocumented</code>.</p> + <p>Default: <code>false</code></p> + </def> + <def title="suppressObviousFunctions"> + <p>Whether to suppress obvious functions.</p> + <p> + A function is considered to be obvious if it is: + <list> + <li> + Inherited from <code>kotlin.Any</code>, <code>Kotlin.Enum</code>, <code>java.lang.Object</code> or + <code>java.lang.Enum</code>, such as <code>equals</code>, <code>hashCode</code>, <code>toString</code>. + </li> + <li> + Synthetic (generated by the compiler) and does not have any documentation, such as + <code>dataClass.componentN</code> or <code>dataClass.copy</code>. + </li> + </list> + </p> + <p>Default: <code>true</code></p> + </def> + <def title="suppressInheritedMembers"> + <p>Whether to suppress inherited members that aren't explicitly overridden in a given class.</p> + <p> + Note: This can suppress functions such as <code>equals</code> / <code>hashCode</code> / <code>toString</code>, + but cannot suppress synthetic functions such as <code>dataClass.componentN</code> and + <code>dataClass.copy</code>. Use <code>suppressObviousFunctions</code> + for that. + </p> + <p>Default: <code>false</code></p> + </def> + <def title="offlineMode"> + <p>Whether to resolve remote files/links over your network.</p> + <p> + This includes package-lists used for generating external documentation links. + For example, to make classes from the standard library clickable. + </p> + <p> + Setting this to <code>true</code> 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. + </p> + <p> + Note: You can cache fetched files locally and provide them to + Dokka as local paths. See <code>externalDocumentationLinks</code> section. + </p> + <p>Default: <code>false</code></p> + </def> +</deflist> + +### Source set configuration + +Dokka allows configuring some options for +[Kotlin source sets](https://kotlinlang.org/docs/multiplatform-discover-project.html#source-sets): + +<tabs group="build-script"> +<tab title="Kotlin" group-key="kotlin"> + +```kotlin +import org.jetbrains.dokka.DokkaConfiguration.Visibility +import org.jetbrains.dokka.gradle.DokkaTask +import org.jetbrains.dokka.Platform +import java.net.URL + +// Note: To configure multi-project builds, you need +// to configure Partial tasks of the subprojects. +// See "Configuration example" section of documentation. +tasks.withType<DokkaTask>().configureEach { + // .. + // general configuration section + // .. + + // configuration exclusive to the 'linux' source set + named("linux") { + dependsOn("native") + sourceRoots.from(file("linux/src")) + } + + dokkaSourceSets.configureEach { + suppress.set(false) + displayName.set(name) + documentedVisibilities.set(setOf(Visibility.PUBLIC)) + reportUndocumented.set(false) + skipEmptyPackages.set(true) + skipDeprecated.set(false) + suppressGeneratedFiles.set(true) + jdkVersion.set(8) + languageVersion.set("1.7") + apiVersion.set("1.7") + noStdlibLink.set(false) + noJdkLink.set(false) + noAndroidSdkLink.set(false) + includes.from(project.files(), "packages.md", "extra.md") + platform.set(Platform.DEFAULT) + sourceRoots.from(file("src")) + classpath.from(project.files(), file("libs/dependency.jar")) + samples.from(project.files(), "samples/Basic.kt", "samples/Advanced.kt") + + sourceLink { + // Source link section + } + externalDocumentationLink { + // External documentation link section + } + perPackageOption { + // Package options section + } + } +} +``` + +</tab> +<tab title="Groovy" group-key="groovy"> + +```groovy +import org.jetbrains.dokka.DokkaConfiguration.Visibility +import org.jetbrains.dokka.gradle.DokkaTask +import org.jetbrains.dokka.Platform +import java.net.URL + +// Note: To configure multi-project builds, you need +// to configure Partial tasks of the subprojects. +// See "Configuration example" section of documentation. +tasks.withType(DokkaTask.class) { + // .. + // general configuration section + // .. + + // configuration exclusive to the 'linux' source set + named("linux") { + dependsOn("native") + sourceRoots.from(file("linux/src")) + } + + dokkaSourceSets.configureEach { + suppress.set(false) + displayName.set(name) + documentedVisibilities.set([Visibility.PUBLIC]) + reportUndocumented.set(false) + skipEmptyPackages.set(true) + skipDeprecated.set(false) + suppressGeneratedFiles.set(true) + jdkVersion.set(8) + languageVersion.set("1.7") + apiVersion.set("1.7") + noStdlibLink.set(false) + noJdkLink.set(false) + noAndroidSdkLink.set(false) + includes.from(project.files(), "packages.md", "extra.md") + platform.set(Platform.DEFAULT) + sourceRoots.from(file("src")) + classpath.from(project.files(), file("libs/dependency.jar")) + samples.from(project.files(), "samples/Basic.kt", "samples/Advanced.kt") + + sourceLink { + // Source link section + } + externalDocumentationLink { + // External documentation link section + } + perPackageOption { + // Package options section + } + } +} +``` + +</tab> +</tabs> + +<deflist collapsible="true"> + <def title="suppress"> + <p>Whether this source set should be skipped when generating documentation.</p> + <p>Default: <code>false</code></p> + </def> + <def title="displayName"> + <p>The display name used to refer to this source set.</p> + <p> + The name is used both externally (for example, as source set name visible to documentation readers) and + internally (for example, for logging messages of <code>reportUndocumented</code>). + </p> + <p>By default, the value is deduced from information provided by the Kotlin Gradle plugin.</p> + </def> + <def title="documentedVisibilities"> + <p>The set of visibility modifiers that should be documented.</p> + <p> + 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. + </p> + <p>This can be configured on per-package basis.</p> + <p>Default: <code>DokkaConfiguration.Visibility.PUBLIC</code></p> + </def> + <def title="reportUndocumented"> + <p> + Whether to emit warnings about visible undocumented declarations, that is declarations without KDocs + after they have been filtered by <code>documentedVisibilities</code> and other filters. + </p> + <p>This setting works well with <code>failOnWarning</code>.</p> + <p>This can be configured on per-package basis.</p> + <p>Default: <code>false</code></p> + </def> + <def title="skipEmptyPackages"> + <p> + Whether to skip packages that contain no visible declarations after + various filters have been applied. + </p> + <p> + For example, if <code>skipDeprecated</code> is set to <code>true</code> and your package contains only + deprecated declarations, it is considered to be empty. + </p> + <p>Default: <code>true</code></p> + </def> + <def title="skipDeprecated"> + <p>Whether to document declarations annotated with <code>@Deprecated</code>.</p> + <p>This can be configured on per-package basis.</p> + <p>Default: <code>false</code></p> + </def> + <def title="suppressGeneratedFiles"> + <p>Whether to document/analyze generated files.</p> + <p> + Generated files are expected to be present under the <code>{project}/{buildDir}/generated</code> directory. + </p> + <p> + If set to <code>true</code>, it effectively adds all files from that directory to the + <code>suppressedFiles</code> option, so you can configure it manually. + </p> + <p>Default: <code>true</code></p> + </def> + <def title="jdkVersion"> + <p>The JDK version to use when generating external documentation links for Java types.</p> + <p> + For example, if you use <code>java.util.UUID</code> in some public declaration signature, + and this option is set to <code>8</code>, Dokka generates an external documentation link + to <a href="https://docs.oracle.com/javase/8/docs/api/java/util/UUID.html">JDK 8 Javadocs</a> for it. + </p> + <p>Default: JDK 8</p> + </def> + <def title="languageVersion"> + <p> + <a href="https://kotlinlang.org/docs/compatibility-modes.html">The Kotlin language version</a> + used for setting up analysis and <a href="https://kotlinlang.org/docs/kotlin-doc.html#sample-identifier">@sample</a> + environment. + </p> + <p>By default, the latest language version available to Dokka's embedded compiler is used.</p> + </def> + <def title="apiVersion"> + <p> + <a href="https://kotlinlang.org/docs/compatibility-modes.html">The Kotlin API version</a> + used for setting up analysis and <a href="https://kotlinlang.org/docs/kotlin-doc.html#sample-identifier">@sample</a> + environment. + </p> + <p>By default, it is deduced from <code>languageVersion</code>.</p> + </def> + <def title="noStdlibLink"> + <p> + Whether to generate external documentation links that lead to the API reference + documentation of Kotlin's standard library. + </p> + <p>Note: Links <b>are</b> generated when <code>noStdLibLink</code> is set to <code>false</code>.</p> + <p>Default: <code>false</code></p> + </def> + <def title="noJdkLink"> + <p>Whether to generate external documentation links to JDK's Javadocs.</p> + <p>The version of JDK Javadocs is determined by the <code>jdkVersion</code> option.</p> + <p>Note: Links <b>are</b> generated when <code>noJdkLink</code> is set to <code>false</code>.</p> + <p>Default: <code>false</code></p> + </def> + <def title="noAndroidSdkLink"> + <p>Whether to generate external documentation links to the Android SDK API reference</p> + <p>This is only relevant in Android projects, ignored otherwise.</p> + <p>Note: Links <b>are</b> generated when <code>noAndroidSdkLink</code> is set to <code>false</code>.</p> + <p>Default: <code>false</code></p> + </def> + <def title="includes"> + <p> + A list of Markdown files that contain + <a href="https://kotlinlang.org/docs/reference/kotlin-doc.html#module-and-package-documentation">module and package documentation</a>. + </p> + <p>The contents of the specified files are parsed and embedded into documentation as module and package descriptions.</p> + <p> + See <a href="https://github.com/Kotlin/dokka/tree/master/examples/gradle/dokka-gradle-example">Dokka gradle example</a> + for an example of what it looks like and how to use it. + </p> + </def> + <def title="platform"> + <p> + The platform to be used for setting up code analysis and + <a href="https://kotlinlang.org/docs/kotlin-doc.html#sample-identifier">@sample</a> environment. + </p> + <p>The default value is deduced from information provided by the Kotlin Gradle plugin.</p> + </def> + <def title="sourceRoots"> + <p> + The source code roots to be analyzed and documented. + Acceptable inputs are directories and individual <code>.kt</code> / <code>.java</code> files. + </p> + <p>By default, source roots are deduced from information provided by the Kotlin Gradle plugin.</p> + </def> + <def title="classpath"> + <p>The classpath for analysis and interactive samples.</p> + <p>This is useful if some types that come from dependencies are not resolved/picked up automatically.</p> + <p>This option accepts both <code>.jar</code> and <code>.klib</code> files.</p> + <p>By default, classpath is deduced from information provided by the Kotlin Gradle plugin.</p> + </def> + <def title="samples"> + <p> + A list of directories or files that contain sample functions which are referenced via the + <a href="https://kotlinlang.org/docs/kotlin-doc.html#sample-identifier">@sample</a> KDoc tag. + </p> + </def> +</deflist> + +### 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`. + +<tabs group="build-script"> +<tab title="Kotlin" group-key="kotlin"> + +```kotlin +import org.jetbrains.dokka.gradle.DokkaTask +import java.net.URL + +// Note: To configure multi-project builds, you need +// to configure Partial tasks of the subprojects. +// See "Configuration example" section of documentation. +tasks.withType<DokkaTask>().configureEach { + // .. + // general configuration section + // .. + + dokkaSourceSets.configureEach { + // .. + // source set configuration section + // .. + + sourceLink { + localDirectory.set(projectDir.resolve("src")) + remoteUrl.set(URL("https://github.com/kotlin/dokka/tree/master/src")) + remoteLineSuffix.set("#L") + } + } +} +``` + +</tab> +<tab title="Groovy" group-key="groovy"> + +```groovy +import org.jetbrains.dokka.gradle.DokkaTask +import java.net.URL + +// Note: To configure multi-project builds, you need +// to configure Partial tasks of the subprojects. +// See "Configuration example" section of documentation. +tasks.withType(DokkaTask.class) { + // .. + // general configuration section + // .. + + dokkaSourceSets.configureEach { + // .. + // source set configuration section + // .. + + sourceLink { + localDirectory.set(file("src")) + remoteUrl.set(new URL("https://github.com/kotlin/dokka/tree/master/src")) + remoteLineSuffix.set("#L") + } + } +} +``` + +</tab> +</tabs> + +<deflist collapsible="true"> + <def title="localDirectory"> + <p> + The path to the local source directory. The path must be relative to the root of + the current project. + </p> + </def> + <def title="remoteUrl"> + <p> + 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. + </p> + </def> + <def title="remoteLineSuffix"> + <p> + 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. + </p> + <p> + The number itself is appended to the specified suffix. For example, + if this option is set to <code>#L</code> and the line number is 10, the resulting URL suffix + is <code>#L10</code>. + </p> + <p> + Suffixes used by popular services: + <list> + <li>GitHub: <code>#L</code></li> + <li>GitLab: <code>#L</code></li> + <li>Bitbucket: <code>#lines-</code></li> + </list> + </p> + <p>Default: <code>#L</code></p> + </def> +</deflist> + +### Package options + +The `perPackageOption` configuration block allows setting some options for specific packages matched by `matchingRegex`. + +<tabs group="build-script"> +<tab title="Kotlin" group-key="kotlin"> + +```kotlin +import org.jetbrains.dokka.DokkaConfiguration.Visibility +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<DokkaTask>().configureEach { + // .. + // general configuration section + // .. + + dokkaSourceSets.configureEach { + // .. + // source set configuration section + // .. + + perPackageOption { + matchingRegex.set(".*api.*") + suppress.set(false) + skipDeprecated.set(false) + reportUndocumented.set(false) + documentedVisibilities.set(setOf(Visibility.PUBLIC)) + } + } +} +``` + +</tab> +<tab title="Groovy" group-key="groovy"> + +```groovy +import org.jetbrains.dokka.DokkaConfiguration.Visibility +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(DokkaTask.class) { + // .. + // general configuration section + // .. + + dokkaSourceSets.configureEach { + // .. + // Source set configuration section + // .. + + perPackageOption { + matchingRegex.set(".*api.*") + suppress.set(false) + skipDeprecated.set(false) + reportUndocumented.set(false) + documentedVisibilities.set([Visibility.PUBLIC]) + } + } +} +``` + +</tab> +</tabs> + +<deflist collapsible="true"> + <def title="matchingRegex"> + <p>The regular expression that is used to match the package.</p> + <p>Default: <code>.*</code></p> + </def> + <def title="suppress"> + <p>Whether this package should be skipped when generating documentation.</p> + <p>Default: <code>false</code></p> + </def> + <def title="skipDeprecated"> + <p>Whether to document declarations annotated with <code>@Deprecated</code>.</p> + <p>This can be configured on source set level.</p> + <p>Default: <code>false</code></p> + </def> + <def title="reportUndocumented"> + <p> + Whether to emit warnings about visible undocumented declarations, that is declarations without KDocs + after they have been filtered by <code>documentedVisibilities</code> and other filters. + </p> + <p>This setting works well with <code>failOnWarning</code>.</p> + <p>This can be configured on source set level.</p> + <p>Default: <code>false</code></p> + </def> + <def title="documentedVisibilities"> + <p>The set of visibility modifiers that should be documented.</p> + <p> + 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. + </p> + <p>This can be configured on source set level.</p> + <p>Default: <code>DokkaConfiguration.Visibility.PUBLIC</code></p> + </def> +</deflist> + +### External documentation links 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. + +By default, external documentation links for Kotlin standard library, JDK, Android SDK and AndroidX are configured. + +<tabs group="build-script"> +<tab title="Kotlin" group-key="kotlin"> + +```kotlin +import org.jetbrains.dokka.gradle.DokkaTask +import java.net.URL + +// Note: To configure multi-project builds, you need +// to configure Partial tasks of the subprojects. +// See "Configuration example" section of documentation. +tasks.withType<DokkaTask>().configureEach { + // .. + // general configuration section + // .. + + dokkaSourceSets.configureEach { + // .. + // source set configuration section + // .. + + externalDocumentationLink { + url.set(URL("https://kotlinlang.org/api/kotlinx.serialization/")) + packageListUrl.set( + rootProject.projectDir.resolve("serialization.package.list").toURL() + ) + } + } +} +``` + +</tab> +<tab title="Groovy" group-key="groovy"> + +```groovy +import org.jetbrains.dokka.gradle.DokkaTask +import java.net.URL + +// Note: To configure multi-project builds, you need +// to configure Partial tasks of the subprojects. +// See "Configuration example" section of documentation. +tasks.withType(DokkaTask.class) { + // .. + // general configuration section + // .. + + dokkaSourceSets.configureEach { + // .. + // source set configuration section + // .. + + externalDocumentationLink { + url.set(new URL("https://kotlinlang.org/api/kotlinx.serialization/")) + packageListUrl.set( + file("serialization.package.list").toURL() + ) + } + } +} +``` + +</tab> +</tabs> + +<deflist collapsible="true"> + <def title="url"> + <p>The root URL of documentation to link to. It <b>must</b> contain a trailing slash.</p> + <p> + Dokka does its best to automatically find <code>package-list</code> for the given URL, + and link declarations together. + </p> + <p> + If automatic resolution fails or if you want to use locally cached files instead, + consider setting the <code>packageListUrl</code> option. + </p> + </def> + <def title="packageListUrl"> + <p> + The exact location of a <code>package-list</code>. This is an alternative to relying on Dokka + automatically resolving it. + </p> + <p> + Package lists contain information about the documentation and the project itself, + such as module and package names. + </p> + <p>This can also be a locally cached file to avoid network calls.</p> + </def> +</deflist> + +### Complete configuration + +Below you can see all possible configuration options applied at the same time. + +<tabs group="build-script"> +<tab title="Kotlin" group-key="kotlin"> + +```kotlin +import org.jetbrains.dokka.DokkaConfiguration.Visibility +import org.jetbrains.dokka.gradle.DokkaTask +import org.jetbrains.dokka.Platform +import java.net.URL + +// Note: To configure multi-project builds, you need +// to configure Partial tasks of the subprojects. +// See "Configuration example" section of documentation. +tasks.withType<DokkaTask>().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) + + dokkaSourceSets { + named("linux") { + dependsOn("native") + sourceRoots.from(file("linux/src")) + } + configureEach { + suppress.set(false) + displayName.set(name) + documentedVisibilities.set(setOf(Visibility.PUBLIC)) + reportUndocumented.set(false) + skipEmptyPackages.set(true) + skipDeprecated.set(false) + suppressGeneratedFiles.set(true) + jdkVersion.set(8) + languageVersion.set("1.7") + apiVersion.set("1.7") + noStdlibLink.set(false) + noJdkLink.set(false) + noAndroidSdkLink.set(false) + includes.from(project.files(), "packages.md", "extra.md") + platform.set(Platform.DEFAULT) + sourceRoots.from(file("src")) + classpath.from(project.files(), file("libs/dependency.jar")) + samples.from(project.files(), "samples/Basic.kt", "samples/Advanced.kt") + + sourceLink { + localDirectory.set(projectDir.resolve("src")) + remoteUrl.set(URL("https://github.com/kotlin/dokka/tree/master/src")) + remoteLineSuffix.set("#L") + } + + externalDocumentationLink { + url.set(URL("https://kotlinlang.org/api/latest/jvm/stdlib/")) + packageListUrl.set( + rootProject.projectDir.resolve("stdlib.package.list").toURL() + ) + } + + perPackageOption { + matchingRegex.set(".*api.*") + suppress.set(false) + skipDeprecated.set(false) + reportUndocumented.set(false) + documentedVisibilities.set( + setOf( + Visibility.PUBLIC, + Visibility.PRIVATE, + Visibility.PROTECTED, + Visibility.INTERNAL, + Visibility.PACKAGE + ) + ) + } + } + } +} +``` + +</tab> +<tab title="Groovy" group-key="groovy"> + +```groovy +import org.jetbrains.dokka.DokkaConfiguration.Visibility +import org.jetbrains.dokka.gradle.DokkaTask +import org.jetbrains.dokka.Platform +import java.net.URL + +// Note: To configure multi-project builds, you need +// to configure Partial tasks of the subprojects. +// See "Configuration example" section of documentation. +tasks.withType(DokkaTask.class) { + moduleName.set(project.name) + moduleVersion.set(project.version.toString()) + outputDirectory.set(file("build/dokka/$name")) + failOnWarning.set(false) + suppressObviousFunctions.set(true) + suppressInheritedMembers.set(false) + offlineMode.set(false) + + dokkaSourceSets { + named("linux") { + dependsOn("native") + sourceRoots.from(file("linux/src")) + } + configureEach { + suppress.set(false) + displayName.set(name) + documentedVisibilities.set([Visibility.PUBLIC]) + reportUndocumented.set(false) + skipEmptyPackages.set(true) + skipDeprecated.set(false) + suppressGeneratedFiles.set(true) + jdkVersion.set(8) + languageVersion.set("1.7") + apiVersion.set("1.7") + noStdlibLink.set(false) + noJdkLink.set(false) + noAndroidSdkLink.set(false) + includes.from(project.files(), "packages.md", "extra.md") + platform.set(Platform.DEFAULT) + sourceRoots.from(file("src")) + classpath.from(project.files(), file("libs/dependency.jar")) + samples.from(project.files(), "samples/Basic.kt", "samples/Advanced.kt") + + sourceLink { + localDirectory.set(file("src")) + remoteUrl.set(new URL("https://github.com/kotlin/dokka/tree/master/src")) + remoteLineSuffix.set("#L") + } + + externalDocumentationLink { + url.set(new URL("https://kotlinlang.org/api/latest/jvm/stdlib/")) + packageListUrl.set( + file("stdlib.package.list").toURL() + ) + } + + perPackageOption { + matchingRegex.set(".*api.*") + suppress.set(false) + skipDeprecated.set(false) + reportUndocumented.set(false) + documentedVisibilities.set([Visibility.PUBLIC]) + } + } + } +} +``` + +</tab> +</tabs> diff --git a/docs/topics/runners/dokka-maven.md b/docs/topics/runners/dokka-maven.md new file mode 100644 index 00000000..9bedc517 --- /dev/null +++ b/docs/topics/runners/dokka-maven.md @@ -0,0 +1,646 @@ +[//]: # (title: Maven) + +To generate documentation for a Maven-based project, you can use the Maven plugin for Dokka. + +> Compared to the [Gradle plugin for Dokka](dokka-gradle.md), the Maven plugin has only basic features and +> does not provide support for multi-module builds. +> +{type="note"} + +You can play around with Dokka and see how it can be configured for a Maven project by visiting +our [Maven example](https://github.com/Kotlin/dokka/tree/%dokkaVersion%/examples/maven) project. + +## Apply Dokka + +To apply Dokka, you need to add `dokka-maven-plugin` to the `plugins` section of your POM file: + +```xml +<build> + <plugins> + <plugin> + <groupId>org.jetbrains.dokka</groupId> + <artifactId>dokka-maven-plugin</artifactId> + <version>%dokkaVersion%</version> + <executions> + <execution> + <phase>pre-site</phase> + <goals> + <goal>dokka</goal> + </goals> + </execution> + </executions> + </plugin> + </plugins> +</build> +``` + +## Generate documentation + +The following goals are provided by the Maven plugin: + +### Stable + +| **Goal** | **Description** | +|---------------|----------------------------------------------------------------------------------------| +| `dokka:dokka` | Generates documentation with Dokka plugins applied. [HTML](dokka-html.md) format by default. | + +### Experimental + +| **Goal** | **Description** | +|--------------------|---------------------------------------------------------------------------------------------| +| `dokka:javadoc` | Generates documentation in [Javadoc](dokka-javadoc.md) format. | +| `dokka:javadocJar` | Generates a `javadoc.jar` file that contains documentation in [Javadoc](dokka-javadoc.md) format. | + +### Other output formats + +By default, the Maven plugin for Dokka builds documentation in [HTML](dokka-html.md) output format. + +All other output formats are implemented as [Dokka plugins](dokka-plugins.md). In order to generate documentation in the +desired format, you have to add it as a Dokka plugin to the configuration. + +For example, to use the experimental [GFM](dokka-markdown.md#gfm) format, you have to add `gfm-plugin` artifact: + +```xml +<plugin> + <groupId>org.jetbrains.dokka</groupId> + <artifactId>dokka-maven-plugin</artifactId> + ... + <configuration> + <dokkaPlugins> + <plugin> + <groupId>org.jetbrains.dokka</groupId> + <artifactId>gfm-plugin</artifactId> + <version>%dokkaVersion%</version> + </plugin> + </dokkaPlugins> + </configuration> +</plugin> +``` + +With this configuration, running the `dokka:dokka` goal produces documentation in GFM format. + +To learn more about Dokka plugins, see [Dokka plugins](dokka-plugins.md). + +## 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. + +Unlike the [Gradle plugin for Dokka](dokka-gradle.md#build-javadoc-jar), the Maven plugin comes with a ready-to-use `dokka:javadocJar` +goal. By default, it generates documentation in [Javadoc](dokka-javadoc.md) output format in the`target` folder. + +If you are not satisfied with the built-in goal or want to customize the output (for example, you want to generate +documentation in [HTML](dokka-html.md) format instead of Javadoc), similar behavior can be achieved by adding the +Maven JAR plugin with the following configuration: + +```xml +<plugin> + <groupId>org.apache.maven.plugins</groupId> + <artifactId>maven-jar-plugin</artifactId> + <version>3.3.0</version> + <executions> + <execution> + <goals> + <goal>test-jar</goal> + </goals> + </execution> + <execution> + <id>dokka-jar</id> + <phase>package</phase> + <goals> + <goal>jar</goal> + </goals> + <configuration> + <classifier>dokka</classifier> + <classesDirectory>${project.build.directory}/dokka</classesDirectory> + <skipIfEmpty>true</skipIfEmpty> + </configuration> + </execution> + </executions> +</plugin> +``` + +The documentation and the `.jar` archive for it are then generated by running `dokka:dokka` and `jar:jar@dokka-jar` goals: + +```Bash +mvn dokka:dokka jar:jar@dokka-jar +``` + +> 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 example + +Maven's plugin configuration block can be used to configure Dokka. + +Here is an example of a basic configuration that only changes the output location of your documentation: + +```xml +<plugin> + <groupId>org.jetbrains.dokka</groupId> + <artifactId>dokka-maven-plugin</artifactId> + ... + <configuration> + <outputDir>${project.basedir}/target/documentation/dokka</outputDir> + </configuration> +</plugin> +``` + +## 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. + +### General configuration + +```xml +<plugin> + <groupId>org.jetbrains.dokka</groupId> + <artifactId>dokka-maven-plugin</artifactId> + <!-- ... --> + <configuration> + <skip>false</skip> + <moduleName>${project.artifactId}</moduleName> + <outputDir>${project.basedir}/target/documentation</outputDir> + <failOnWarning>false</failOnWarning> + <suppressObviousFunctions>true</suppressObviousFunctions> + <suppressInheritedMembers>false</suppressInheritedMembers> + <offlineMode>false</offlineMode> + <sourceDirectories> + <dir>${project.basedir}/src</dir> + </sourceDirectories> + <documentedVisibilities> + <visibility>PUBLIC</visibility> + <visibility>PROTECTED</visibility> + </documentedVisibilities> + <reportUndocumented>false</reportUndocumented> + <skipDeprecated>false</skipDeprecated> + <skipEmptyPackages>true</skipEmptyPackages> + <suppressedFiles> + <file>/path/to/dir</file> + <file>/path/to/file</file> + </suppressedFiles> + <jdkVersion>8</jdkVersion> + <languageVersion>1.7</languageVersion> + <apiVersion>1.7</apiVersion> + <noStdlibLink>false</noStdlibLink> + <noJdkLink>false</noJdkLink> + <includes> + <include>packages.md</include> + <include>extra.md</include> + </includes> + <classpath>${project.compileClasspathElements}</classpath> + <samples> + <dir>${project.basedir}/samples</dir> + </samples> + <sourceLinks> + <!-- Separate section --> + </sourceLinks> + <externalDocumentationLinks> + <!-- Separate section --> + </externalDocumentationLinks> + <perPackageOptions> + <!-- Separate section --> + </perPackageOptions> + </configuration> +</plugin> +``` + +<deflist collapsible="true"> + <def title="skip"> + <p>Whether to skip documentation generation.</p> + <p>Default: <code>false</code></p> + </def> + <def title="moduleName"> + <p>The display name used to refer to the project/module. It's used for the table of contents, navigation, logging, etc.</p> + <p>Default: <code>{project.artifactId}</code></p> + </def> + <def title="outputDir"> + <p>The directory to where documentation is generated, regardless of format.</p> + <p>Default: <code>{project.basedir}/target/dokka</code></p> + </def> + <def title="failOnWarning"> + <p> + 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. + </p> + <p>This setting works well with <code>reportUndocumented</code>.</p> + <p>Default: <code>false</code></p> + </def> + <def title="suppressObviousFunctions"> + <p>Whether to suppress obvious functions.</p> + <p> + A function is considered to be obvious if it is: + <list> + <li> + Inherited from <code>kotlin.Any</code>, <code>Kotlin.Enum</code>, <code>java.lang.Object</code> or + <code>java.lang.Enum</code>, such as <code>equals</code>, <code>hashCode</code>, <code>toString</code>. + </li> + <li> + Synthetic (generated by the compiler) and does not have any documentation, such as + <code>dataClass.componentN</code> or <code>dataClass.copy</code>. + </li> + </list> + </p> + <p>Default: <code>true</code></p> + </def> + <def title="suppressInheritedMembers"> + <p>Whether to suppress inherited members that aren't explicitly overridden in a given class.</p> + <p> + Note: This can suppress functions such as <code>equals</code>/<code>hashCode</code>/<code>toString</code>, + but cannot suppress synthetic functions such as <code>dataClass.componentN</code> and + <code>dataClass.copy</code>. Use <code>suppressObviousFunctions</code> for that. + </p> + <p>Default: <code>false</code></p> + </def> + <def title="offlineMode"> + <p>Whether to resolve remote files/links over your network.</p> + <p> + This includes package-lists used for generating external documentation links. + For example, to make classes from the standard library clickable. + </p> + <p> + Setting this to <code>true</code> 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. + </p> + <p> + Note: You can cache fetched files locally and provide them to + Dokka as local paths. See <code>externalDocumentationLinks</code> section. + </p> + <p>Default: <code>false</code></p> + </def> + <def title="sourceDirectories"> + <p> + The source code roots to be analyzed and documented. + Acceptable inputs are directories and individual <code>.kt</code> / <code>.java</code> files. + </p> + <p>Default: <code>{project.compileSourceRoots}</code></p> + </def> + <def title="documentedVisibilities"> + <p>The set of visibility modifiers that should be documented.</p> + <p> + 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. + </p> + <p>Can be configured on per-package basis.</p> + <p>Default: <code>PUBLIC</code></p> + </def> + <def title="reportUndocumented"> + <p> + Whether to emit warnings about visible undocumented declarations, that is declarations without KDocs + after they have been filtered by <code>documentedVisibilities</code> and other filters. + </p> + <p>This setting works well with <code>failOnWarning</code>.</p> + <p>This can be overridden at package level.</p> + <p>Default: <code>false</code></p> + </def> + <def title="skipDeprecated"> + <p>Whether to document declarations annotated with <code>@Deprecated</code>.</p> + <p>This can be overridden at package level.</p> + <p>Default: <code>false</code></p> + </def> + <def title="skipEmptyPackages"> + <p> + Whether to skip packages that contain no visible declarations after + various filters have been applied. + </p> + <p> + For example, if <code>skipDeprecated</code> is set to <code>true</code> and your package contains only + deprecated declarations, it is considered to be empty. + </p> + <p>Default: <code>true</code></p> + </def> + <def title="suppressedFiles"> + <p> + The directories or individual files that should be suppressed, meaning that declarations from them + are not documented. + </p> + </def> + <def title="jdkVersion"> + <p>The JDK version to use when generating external documentation links for Java types.</p> + <p> + For example, if you use <code>java.util.UUID</code> in some public declaration signature, + and this option is set to <code>8</code>, Dokka generates an external documentation link + to <a href="https://docs.oracle.com/javase/8/docs/api/java/util/UUID.html">JDK 8 Javadocs</a> for it. + </p> + <p>Default: JDK 8</p> + </def> + <def title="languageVersion"> + <p> + <a href="https://kotlinlang.org/docs/compatibility-modes.html">The Kotlin language version</a> + used for setting up analysis and <a href="https://kotlinlang.org/docs/kotlin-doc.html#sample-identifier">@sample</a> + environment. + </p> + <p>By default, the latest language version available to Dokka's embedded compiler is used.</p> + </def> + <def title="apiVersion"> + <p> + <a href="https://kotlinlang.org/docs/compatibility-modes.html">The Kotlin API version</a> + used for setting up analysis and <a href="https://kotlinlang.org/docs/kotlin-doc.html#sample-identifier">@sample</a> + environment. + </p> + <p>By default, it is deduced from <code>languageVersion</code>.</p> + </def> + <def title="noStdlibLink"> + <p> + Whether to generate external documentation links that lead to the API reference + documentation of Kotlin's standard library. + </p> + <p>Note: Links <b>are</b> generated when <code>noStdLibLink</code> is set to <code>false</code>.</p> + <p>Default: <code>false</code></p> + </def> + <def title="noJdkLink"> + <p>Whether to generate external documentation links to JDK's Javadocs.</p> + <p>The version of JDK Javadocs is determined by the <code>jdkVersion</code> option.</p> + <p>Note: Links <b>are</b> generated when <code>noJdkLink</code> is set to <code>false</code>.</p> + <p>Default: <code>false</code></p> + </def> + <def title="includes"> + <p> + A list of Markdown files that contain + <a href="https://kotlinlang.org/docs/reference/kotlin-doc.html#module-and-package-documentation">module and package documentation</a> + </p> + <p>The contents of specified files are parsed and embedded into documentation as module and package descriptions.</p> + </def> + <def title="classpath"> + <p>The classpath for analysis and interactive samples.</p> + <p> + This is useful if some types that come from dependencies are not resolved/picked up automatically. + This option accepts both <code>.jar</code> and <code>.klib</code> files. + </p> + <p>Default: <code>{project.compileClasspathElements}</code></p> + </def> + <def title="samples"> + <p> + A list of directories or files that contain sample functions which are referenced via + <a href="https://kotlinlang.org/docs/kotlin-doc.html#sample-identifier">@sample KDoc tag.</a> + </p> + </def> +</deflist> + +### Source link configuration + +The `sourceLinks` configuration block allows you to add a `source` link to each signature +that leads to the `url` with a specific line number. (The line number is configurable by setting `lineSuffix`). + +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`. + +```xml +<plugin> + <groupId>org.jetbrains.dokka</groupId> + <artifactId>dokka-maven-plugin</artifactId> + <!-- ... --> + <configuration> + <sourceLinks> + <link> + <path>${project.basedir}/src</path> + <url>https://github.com/kotlin/dokka/tree/master/src</url> + <lineSuffix>#L</lineSuffix> + </link> + </sourceLinks> + </configuration> +</plugin> +``` + +<deflist collapsible="true"> + <def title="path"> + <p> + The path to the local source directory. The path must be relative to the root of the + current module. + </p> + </def> + <def title="url"> + <p> + 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. + </p> + </def> + <def title="lineSuffix"> + <p> + The suffix used to append 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. + </p> + <p> + The number itself is appended to the specified suffix. For example, if this option is set + to <code>#L</code> and the line number is 10, the resulting URL suffix is <code>#L10</code>. + </p> + <p> + Suffixes used by popular services: + <list> + <li>GitHub: <code>#L</code></li> + <li>GitLab: <code>#L</code></li> + <li>Bitbucket: <code>#lines-</code></li> + </list> + </p> + </def> +</deflist> + +#### External documentation links 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. + +By default, external documentation links for Kotlin standard library and JDK are configured. + +```xml +<plugin> + <groupId>org.jetbrains.dokka</groupId> + <artifactId>dokka-maven-plugin</artifactId> + <!-- ... --> + <configuration> + <externalDocumentationLinks> + <link> + <url>https://kotlinlang.org/api/kotlinx.serialization/</url> + <packageListUrl>file:/${project.basedir}/serialization.package.list</packageListUrl> + </link> + </externalDocumentationLinks> + </configuration> +</plugin> +``` + +<deflist collapsible="true"> + <def title="url"> + <p>The root URL of documentation to link to. It <b>must</b> contain a trailing slash.</p> + <p> + Dokka does its best to automatically find the <code>package-list</code> for the given URL, + and link declarations together. + </p> + <p> + If automatic resolution fails or if you want to use locally cached files instead, + consider setting the <code>packageListUrl</code> option. + </p> + </def> + <def title="packageListUrl"> + <p> + The exact location of a <code>package-list</code>. This is an alternative to relying on Dokka + automatically resolving it. + </p> + <p> + Package lists contain information about the documentation and the project itself, + such as module and package names. + </p> + <p>This can also be a locally cached file to avoid network calls.</p> + </def> +</deflist> + +### Package options + +The `perPackageOptions` configuration block allows setting some options for specific packages matched by `matchingRegex`. + +```xml +<plugin> + <groupId>org.jetbrains.dokka</groupId> + <artifactId>dokka-maven-plugin</artifactId> + <!-- ... --> + <configuration> + <perPackageOptions> + <packageOptions> + <matchingRegex>.*api.*</matchingRegex> + <suppress>false</suppress> + <reportUndocumented>false</reportUndocumented> + <skipDeprecated>false</skipDeprecated> + <documentedVisibilities> + <visibility>PUBLIC</visibility> + <visibility>PRIVATE</visibility> + <visibility>PROTECTED</visibility> + <visibility>INTERNAL</visibility> + <visibility>PACKAGE</visibility> + </documentedVisibilities> + </packageOptions> + </perPackageOptions> + </configuration> +</plugin> +``` + +<deflist collapsible="true"> + <def title="matchingRegex"> + <p>The regular expression that is used to match the package.</p> + <p>Default: <code>.*</code></p> + </def> + <def title="suppress"> + <p>Whether this package should be skipped when generating documentation.</p> + <p>Default: <code>false</code></p> + </def> + <def title="documentedVisibilities"> + <p>The set of visibility modifiers that should be documented.</p> + <p> + 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. + </p> + <p>Default: <code>PUBLIC</code></p> + </def> + <def title="skipDeprecated"> + <p>Whether to document declarations annotated with <code>@Deprecated</code>.</p> + <p>This can be set on project/module level.</p> + <p>Default: <code>false</code></p> + </def> + <def title="reportUndocumented"> + <p> + Whether to emit warnings about visible undocumented declarations, that is declarations without KDocs + after they have been filtered by <code>documentedVisibilities</code> and other filters. + </p> + <p>This setting works well with <code>failOnWarning</code>.</p> + <p>Default: <code>false</code></p> + </def> +</deflist> + +### Complete configuration + +Below you can see all the possible configuration options applied at the same time. + +```xml +<plugin> + <groupId>org.jetbrains.dokka</groupId> + <artifactId>dokka-maven-plugin</artifactId> + <!-- ... --> + <configuration> + <skip>false</skip> + <moduleName>${project.artifactId}</moduleName> + <outputDir>${project.basedir}/target/documentation</outputDir> + <failOnWarning>false</failOnWarning> + <suppressObviousFunctions>true</suppressObviousFunctions> + <suppressInheritedMembers>false</suppressInheritedMembers> + <offlineMode>false</offlineMode> + <sourceDirectories> + <dir>${project.basedir}/src</dir> + </sourceDirectories> + <documentedVisibilities> + <visibility>PUBLIC</visibility> + <visibility>PRIVATE</visibility> + <visibility>PROTECTED</visibility> + <visibility>INTERNAL</visibility> + <visibility>PACKAGE</visibility> + </documentedVisibilities> + <reportUndocumented>false</reportUndocumented> + <skipDeprecated>false</skipDeprecated> + <skipEmptyPackages>true</skipEmptyPackages> + <suppressedFiles> + <file>/path/to/dir</file> + <file>/path/to/file</file> + </suppressedFiles> + <jdkVersion>8</jdkVersion> + <languageVersion>1.7</languageVersion> + <apiVersion>1.7</apiVersion> + <noStdlibLink>false</noStdlibLink> + <noJdkLink>false</noJdkLink> + <includes> + <include>packages.md</include> + <include>extra.md</include> + </includes> + <classpath>${project.compileClasspathElements}</classpath> + <samples> + <dir>${project.basedir}/samples</dir> + </samples> + <sourceLinks> + <link> + <path>${project.basedir}/src</path> + <url>https://github.com/kotlin/dokka/tree/master/src</url> + <lineSuffix>#L</lineSuffix> + </link> + </sourceLinks> + <externalDocumentationLinks> + <link> + <url>https://kotlinlang.org/api/latest/jvm/stdlib/</url> + <packageListUrl>file:/${project.basedir}/stdlib.package.list</packageListUrl> + </link> + </externalDocumentationLinks> + <perPackageOptions> + <packageOptions> + <matchingRegex>.*api.*</matchingRegex> + <suppress>false</suppress> + <reportUndocumented>false</reportUndocumented> + <skipDeprecated>false</skipDeprecated> + <documentedVisibilities> + <visibility>PUBLIC</visibility> + <visibility>PRIVATE</visibility> + <visibility>PROTECTED</visibility> + <visibility>INTERNAL</visibility> + <visibility>PACKAGE</visibility> + </documentedVisibilities> + </packageOptions> + </perPackageOptions> + </configuration> +</plugin> +``` diff --git a/docs/vars.list b/docs/vars.list new file mode 100644 index 00000000..bd5bcfc5 --- /dev/null +++ b/docs/vars.list @@ -0,0 +1,9 @@ +<?xml version="1.0" encoding="UTF-8"?> +<vars> + <var name="dokkaVersion" + value="1.7.20" + type="string"/> + <var name="kotlinVersion" + value="1.7.20" + type="string"/> +</vars> |
