diff options
Diffstat (limited to 'mkdocs/src/doc/docs')
27 files changed, 2693 insertions, 0 deletions
diff --git a/mkdocs/src/doc/docs/community/plugins-list.md b/mkdocs/src/doc/docs/community/plugins-list.md new file mode 100644 index 00000000..6ae8ce4c --- /dev/null +++ b/mkdocs/src/doc/docs/community/plugins-list.md @@ -0,0 +1,160 @@ +# 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/mkdocs/src/doc/docs/community/slack.md b/mkdocs/src/doc/docs/community/slack.md new file mode 100644 index 00000000..290d4a18 --- /dev/null +++ b/mkdocs/src/doc/docs/community/slack.md @@ -0,0 +1,7 @@ +# 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/mkdocs/src/doc/docs/developer_guide/architecture/architecture_overview.md b/mkdocs/src/doc/docs/developer_guide/architecture/architecture_overview.md new file mode 100644 index 00000000..fb11f32a --- /dev/null +++ b/mkdocs/src/doc/docs/developer_guide/architecture/architecture_overview.md @@ -0,0 +1,123 @@ +# 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/mkdocs/src/doc/docs/developer_guide/architecture/data_model/documentables.md b/mkdocs/src/doc/docs/developer_guide/architecture/data_model/documentables.md new file mode 100644 index 00000000..5264553d --- /dev/null +++ b/mkdocs/src/doc/docs/developer_guide/architecture/data_model/documentables.md @@ -0,0 +1,245 @@ +# 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/mkdocs/src/doc/docs/developer_guide/architecture/data_model/extra.md b/mkdocs/src/doc/docs/developer_guide/architecture/data_model/extra.md new file mode 100644 index 00000000..0abbc70e --- /dev/null +++ b/mkdocs/src/doc/docs/developer_guide/architecture/data_model/extra.md @@ -0,0 +1,99 @@ +# 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/mkdocs/src/doc/docs/developer_guide/architecture/data_model/page_content.md b/mkdocs/src/doc/docs/developer_guide/architecture/data_model/page_content.md new file mode 100644 index 00000000..54ded235 --- /dev/null +++ b/mkdocs/src/doc/docs/developer_guide/architecture/data_model/page_content.md @@ -0,0 +1,140 @@ +# 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/mkdocs/src/doc/docs/developer_guide/architecture/extension_points/base_extensions.md b/mkdocs/src/doc/docs/developer_guide/architecture/extension_points/base_extensions.md new file mode 100644 index 00000000..16a52fab --- /dev/null +++ b/mkdocs/src/doc/docs/developer_guide/architecture/extension_points/base_extensions.md @@ -0,0 +1,13 @@ +# 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/mkdocs/src/doc/docs/developer_guide/architecture/extension_points/core_extensions.md b/mkdocs/src/doc/docs/developer_guide/architecture/extension_points/core_extensions.md new file mode 100644 index 00000000..381a9596 --- /dev/null +++ b/mkdocs/src/doc/docs/developer_guide/architecture/extension_points/core_extensions.md @@ -0,0 +1,151 @@ +# 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/mkdocs/src/doc/docs/developer_guide/architecture/extension_points/introduction.md b/mkdocs/src/doc/docs/developer_guide/architecture/extension_points/introduction.md new file mode 100644 index 00000000..877d14e9 --- /dev/null +++ b/mkdocs/src/doc/docs/developer_guide/architecture/extension_points/introduction.md @@ -0,0 +1,163 @@ +# 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/mkdocs/src/doc/docs/developer_guide/introduction.md b/mkdocs/src/doc/docs/developer_guide/introduction.md new file mode 100644 index 00000000..feb601fe --- /dev/null +++ b/mkdocs/src/doc/docs/developer_guide/introduction.md @@ -0,0 +1,19 @@ +# 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/mkdocs/src/doc/docs/developer_guide/plugin-development/introduction.md b/mkdocs/src/doc/docs/developer_guide/plugin-development/introduction.md new file mode 100644 index 00000000..fbfb32ac --- /dev/null +++ b/mkdocs/src/doc/docs/developer_guide/plugin-development/introduction.md @@ -0,0 +1,59 @@ +# 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/mkdocs/src/doc/docs/developer_guide/plugin-development/sample-plugin-tutorial.md b/mkdocs/src/doc/docs/developer_guide/plugin-development/sample-plugin-tutorial.md new file mode 100644 index 00000000..fdea0207 --- /dev/null +++ b/mkdocs/src/doc/docs/developer_guide/plugin-development/sample-plugin-tutorial.md @@ -0,0 +1,292 @@ +# 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/mkdocs/src/doc/docs/developer_guide/workflow.md b/mkdocs/src/doc/docs/developer_guide/workflow.md new file mode 100644 index 00000000..ddf37459 --- /dev/null +++ b/mkdocs/src/doc/docs/developer_guide/workflow.md @@ -0,0 +1,100 @@ +# 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/mkdocs/src/doc/docs/dokka_colors.css b/mkdocs/src/doc/docs/dokka_colors.css new file mode 100644 index 00000000..69a24359 --- /dev/null +++ b/mkdocs/src/doc/docs/dokka_colors.css @@ -0,0 +1,3 @@ +.md-header, .md-tabs { + background-color: #27282c +} diff --git a/mkdocs/src/doc/docs/faq.md b/mkdocs/src/doc/docs/faq.md new file mode 100644 index 00000000..ef728ca0 --- /dev/null +++ b/mkdocs/src/doc/docs/faq.md @@ -0,0 +1,2 @@ +# FAQ +If you encounter any problems, please see [FAQ](https://github.com/Kotlin/dokka/wiki/faq). diff --git a/mkdocs/src/doc/docs/favicon.svg b/mkdocs/src/doc/docs/favicon.svg new file mode 100755 index 00000000..1fea0877 --- /dev/null +++ b/mkdocs/src/doc/docs/favicon.svg @@ -0,0 +1,10 @@ +<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/mkdocs/src/doc/docs/images/mathjax_demo.png b/mkdocs/src/doc/docs/images/mathjax_demo.png Binary files differnew file mode 100644 index 00000000..9b14a704 --- /dev/null +++ b/mkdocs/src/doc/docs/images/mathjax_demo.png diff --git a/mkdocs/src/doc/docs/images/mermaid_demo.png b/mkdocs/src/doc/docs/images/mermaid_demo.png Binary files differnew file mode 100644 index 00000000..0d0e27b6 --- /dev/null +++ b/mkdocs/src/doc/docs/images/mermaid_demo.png diff --git a/mkdocs/src/doc/docs/index.md b/mkdocs/src/doc/docs/index.md new file mode 100644 index 00000000..0f106c04 --- /dev/null +++ b/mkdocs/src/doc/docs/index.md @@ -0,0 +1,38 @@ +# 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/mkdocs/src/doc/docs/survey_banner.js b/mkdocs/src/doc/docs/survey_banner.js new file mode 100644 index 00000000..b4592f1f --- /dev/null +++ b/mkdocs/src/doc/docs/survey_banner.js @@ -0,0 +1,8 @@ +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); +}) diff --git a/mkdocs/src/doc/docs/user_guide/applying/cli.md b/mkdocs/src/doc/docs/user_guide/applying/cli.md new file mode 100644 index 00000000..3b02add2 --- /dev/null +++ b/mkdocs/src/doc/docs/user_guide/applying/cli.md @@ -0,0 +1,158 @@ +# Using command line + +To run Dokka from the command line, download the [Dokka CLI runner](https://mvnrepository.com/artifact/org.jetbrains.dokka/dokka-cli). +To generate documentation, run the following command: +``` +java -jar dokka-cli.jar <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/mkdocs/src/doc/docs/user_guide/applying/gradle.md b/mkdocs/src/doc/docs/user_guide/applying/gradle.md new file mode 100644 index 00000000..435824f9 --- /dev/null +++ b/mkdocs/src/doc/docs/user_guide/applying/gradle.md @@ -0,0 +1,380 @@ +# Using the Gradle plugin + +!!! important + If you are upgrading from 0.10.x to a current release of Dokka, please have a look at our + [migration guide](https://github.com/Kotlin/dokka/blob/master/runners/gradle-plugin/MIGRATION.md) + +### Supported versions +Dokka should work on gradle newer than 5.6 + +### Setup + +The preferred way is to use `plugins` block. + +build.gradle.kts: +```kotlin +plugins { + id("org.jetbrains.dokka") version "1.7.20" +} + +repositories { + mavenCentral() +} +``` + +You can also use the legacy plugin application method with `buildscript` block. +Note that by using the `buildscript` way type-safe accessors are not available in Gradle Kotlin DSL, +eg. you'll have to use `named<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/mkdocs/src/doc/docs/user_guide/applying/maven.md b/mkdocs/src/doc/docs/user_guide/applying/maven.md new file mode 100644 index 00000000..cde6e927 --- /dev/null +++ b/mkdocs/src/doc/docs/user_guide/applying/maven.md @@ -0,0 +1,243 @@ +# Using the Maven plugin + +!!! note + Dokka Maven plugin does not support multi-platform projects. + +Minimal Maven configuration is + +```xml +<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/mkdocs/src/doc/docs/user_guide/introduction.md b/mkdocs/src/doc/docs/user_guide/introduction.md new file mode 100644 index 00000000..cb263ebe --- /dev/null +++ b/mkdocs/src/doc/docs/user_guide/introduction.md @@ -0,0 +1,74 @@ +# Introduction + +## Plugins +Dokka can be customized with plugins. Each output format is internally a plugin. +Additionally, `kotlin-as-java` plugin can be used to generate documentation as seen from Java perspective. +Currently maintained plugins are: + +* `dokka-base` - the main plugin needed to run Dokka, contains html format +* `gfm-plugin` - configures `GFM` output format +* `jekyll-plugin` - configures `Jekyll` output format +* `javadoc-plugin` - configures `Javadoc` output format, automatically applies `kotlin-as-java-plugin` +* `kotlin-as-java-plugin` - translates Kotlin definitions to Java +* `android-documentation-plugin` - provides android specific enhancements like `@hide` support + +Please see the usage instructions for each build system on how to add plugins to Dokka. + +## Source sets +Dokka generates documentation based on source sets. + +For single-platform & multi-platform projects, source sets are the same as in Kotlin plugin: + + * One source set for each platform, eg. `jvmMain` or `jsMain`; + * One source set for each common source set, eg. the default `commonMain` and custom ones like `jsAndJvmMain`. + +When configuring multi-platform projects manually (eg. in the CLI or in Gradle without the Kotlin Gradle Plugin) +source sets must declare their dependent source sets. +Eg. in the following Kotlin plugin configuration: + +* `jsMain` and `jvmMain` both depend on `commonMain` (by default and transitively) and `jsAndJvmMain`; +* `linuxX64Main` only depends on `commonMain`. + +```kotlin +kotlin { // Kotlin plugin configuration + jvm() + js() + linuxX64() + + sourceSets { + val commonMain by getting {} + val jvmAndJsSecondCommonMain by creating { dependsOn(commonMain) } + val jvmMain by getting { dependsOn(jvmAndJsSecondCommonMain) } + val jsMain by getting { dependsOn(jvmAndJsSecondCommonMain) } + val linuxX64Main by getting { dependsOn(commonMain) } + } +} +``` + +## Output formats + Dokka documents Java classes as seen in Kotlin by default, with javadoc format being the only exception. + + * `html` - HTML format used by default + * `javadoc` - looks like JDK's Javadoc, Kotlin classes are translated to Java + * `gfm` - GitHub flavored markdown + * `jekyll` - Jekyll compatible markdown + +If you want to generate the documentation as seen from Java perspective, you can add the `kotlin-as-java` plugin +to the Dokka plugins classpath, eg. in Gradle: + +```kotlin +dependencies{ + implementation("...") + dokkaGfmPlugin("org.jetbrains.dokka:kotlin-as-java-plugin:${dokka-version}") +} +``` + +## Platforms + +Each Dokka source set is analyzed for a specific platform. The platform should be extracted automatically from the Kotlin plugin. +In case of a manual source set configuration, you have to select one of the following: + + * `jvm` + * `js` + * `native` + * `common` diff --git a/mkdocs/src/doc/docs/user_guide/output-formats/html.md b/mkdocs/src/doc/docs/user_guide/output-formats/html.md new file mode 100644 index 00000000..9a80a5d2 --- /dev/null +++ b/mkdocs/src/doc/docs/user_guide/output-formats/html.md @@ -0,0 +1,112 @@ +# Configuration specific to HTML format + +## Prerequisites + +Dokka's HTML format requires a web server to view documentation correctly. +This can be achieved by using the one that is build in IntelliJ or providing your own. +If this requisite is not fulfilled Dokka with fail to load navigation pane and search bars. + +!!! important + Concepts specified below apply only to configuration of the Base Plugin (that contains HTML format) + and needs to be applied via pluginsConfiguration and not on the root one. + +## Modifying assets + +It is possible to change static assets that are used to generate dokka's HTML. +Currently, user can modify: + + * customAssets + * customStyleSheets + +Every file provided in those values will be applied to **every** page. + +Dokka uses 4 stylesheets: + +* `style.css` - main css file responsible for styling the page +* `jetbrains-mono.css` - fonts used across dokka +* `logo-styles.css` - logo styling +* [`prism.css`](https://github.com/Kotlin/dokka/blob/master/plugins/base/src/main/resources/dokka/styles/prism.css) - code highlighting + +Also, it uses js scripts. The actual ones are [here](https://github.com/Kotlin/dokka/tree/master/plugins/base/src/main/resources/dokka/scripts). +User can choose to add or override those files - stylesheets and js scripts. +Resources will be overridden when in `pluginConfiguration` block there is a resource with the same name. + +## Modifying footer + +Dokka supports custom messages in the footer via `footerMessage` string property on base plugin configuration. +Keep in mind that this value will be passed exactly to the output HTML, so it has to be valid and escaped correctly. + +## Separating inherited members + +By setting a boolean property `separateInheritedMembers` dokka will split inherited members (like functions, properties etc.) +from ones declared in viewed class. Separated members will have it's own tabs on the page. + +## Merging declarations with name clashing + +By setting a boolean property `mergeImplicitExpectActualDeclarations` dokka will merge declarations that do not have `expect`/`actual` keywords but have the same fully qualified name. +The declarations will be displayed on one page. +By default, it is disabled. The page names of such declaration have a prefix that is the name of source set. + +### Examples +In order to override a logo and style it accordingly a css file named `logo-styles.css` is needed: +```css +.library-name a { + position: relative; + --logo-width: 100px; + margin-left: calc(var(--logo-width) + 5px); +} + +.library-name a::before { + content: ''; + background: url("https://upload.wikimedia.org/wikipedia/commons/9/9d/Ubuntu_logo.svg") center no-repeat; + background-size: contain; + position: absolute; + width: var(--logo-width); + height: 50px; + top: -18px; + left: calc(-1 * var(--logo-width) - 5px); + /* other styles required to make your page pretty */ +} +``` + + +For build system specific instructions please visit dedicated pages: [gradle](../applying/gradle.md#applying-plugins), [maven](../applying/maven.md#applying-plugins) and [cli](../applying/cli.md#configuration-options) + +## Custom HTML pages + +Templates are taken from the folder that is defined by the `templatesDir` property. +To customize HTML output, you can use the [default template](https://github.com/Kotlin/dokka/blob/master/plugins/base/src/main/resources/dokka/templates) as a starting point. + +!!! note + To change page assets, you can set properties `customAssets` and `customStyleSheets`. + Assets are handled by Dokka itself, not FreeMaker. + +There is a template file with predefined name `base.ftl`. It defines general design of all pages to render. +`base.ftl` can import another templates that can be set by user as well: + +* `includes/header.ftl` +* `includes/footer.ftl` +* `includes/page_metadata.ftl` +* `includes/source_set_selector.ftl`. + +If `templatesDir` is defined, Dokka will find a template file there. +If the file is not found, a default one will be used. + +Variables given below are available to the template: + +* `${pageName}` - the page name +* `${footerMessage}` - text that is set by the `footerMessage` property +* `${sourceSets}` - a nullable list of source sets, only for multi-platform pages. Each source set has `name`, `platfrom` and `filter` properties. + +Also, Dokka-defined [directives](https://freemarker.apache.org/docs/ref_directive_userDefined.html) can be used: + +* `<@content/>` - main content +* `<@resources/>` - scripts, stylesheets +* `<@version/>` - version ([versioning-plugin](../plugins/versioning-plugin.md) will replace this with a version navigator) +* `<@template_cmd name="...""> ...</@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/mkdocs/src/doc/docs/user_guide/plugins/android-plugin.md b/mkdocs/src/doc/docs/user_guide/plugins/android-plugin.md new file mode 100644 index 00000000..d52c2e5a --- /dev/null +++ b/mkdocs/src/doc/docs/user_guide/plugins/android-plugin.md @@ -0,0 +1,8 @@ +# Android documentation plugin + +Android documentation plugin aims to improve the documentation on android platform. + +### Features: + +* `@hide` support - `@hide` javadoc tag is an equivalent of `@suppress` tag in kdoc. It hides certain entry from being + displayed in the documentation. diff --git a/mkdocs/src/doc/docs/user_guide/plugins/versioning-plugin.md b/mkdocs/src/doc/docs/user_guide/plugins/versioning-plugin.md new file mode 100644 index 00000000..876ec436 --- /dev/null +++ b/mkdocs/src/doc/docs/user_guide/plugins/versioning-plugin.md @@ -0,0 +1,86 @@ +# Versioning plugin + +Versioning plugin aims to provide users with ability to create a versioned documentation. +Therefore, users of the documentation can view different versions of the documentation by going to the main page and change versions. + +Versioning can be configured using: + +* version - a string value representing a version that should be displayed in the dropdown. +* olderVersionsDir - an optional file that represents the parent directory containing folders with previous Dokka outputs. +* olderVersions - an optional list of directories, each containing a previous Dokka output. Used after the contents of + `olderVersionsDir` + (if it's specified). +* versionsOrdering - an optional list of strings representing the ordering of versions that should be visible. + By default, Dokka will try to use semantic versioning to create such ordering. +* renderVersionsNavigationOnAllPages - a bool value. + By default, Dokka renders a versions navigation on all pages. + +!!! note + You should enable the plugin in all submodules to render a versions navigation on all pages. + +Above configuration should be placed under the `pluginsConfiguration` block specific for your build tool. +Configuration object is named `org.jetbrains.dokka.versioning.VersioningConfiguration`. + + +### Directory structure required + +If you pass previous versions using `olderVersionsDir`, a particular directory structure is required: + +``` +. +└── older_versions_dir + └── 1.4.10 + ├── <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). |
