diff options
Diffstat (limited to 'docs-developer')
19 files changed, 1612 insertions, 0 deletions
diff --git a/docs-developer/README.md b/docs-developer/README.md new file mode 100644 index 00000000..d415dbf7 --- /dev/null +++ b/docs-developer/README.md @@ -0,0 +1,43 @@ +# Developer documentation + +This module contains developer documentation which is published to GitHub pages: +[kotlin.github.io/dokka](https://kotlin.github.io/dokka/). + +It is built using the [gradle-mkdocs-plugin](https://github.com/xvik/gradle-mkdocs-plugin). + +## Building + +You can build the documentation locally: + +```Bash +./gradlew :docs-developer:mkdocsBuild +``` + +The output directory is `build/mkdocs`. + +### Docker + +Alternatively, you can use Docker: + +```bash +docker run --rm -it -p 8000:8000 -v ./docs-developer/src/doc:/docs squidfunk/mkdocs-material +``` + +This will build the docs and start a web server under [localhost:8000/Kotlin/dokka](http://localhost:8000/Kotlin/dokka/). + +### Livereload server + +Alternatively, you can run a livereload server that automatically rebuilds documentation on every change: + +```Bash +./gradlew :docs-developer:mkdocsServe +``` + +By default, it is run under [localhost:3001](http://localhost:3001/), but you can change it in +[mkdocs.yml](src/doc/mkdocs.yml) by setting the `dev_addr` option. + +## Publishing + +The documentation is published automatically for all changes in master and for every GitHub release. + +See [gh-pages.yml](../.github/workflows/gh-pages-deploy-dev-docs.yml) workflow configuration for more details. diff --git a/docs-developer/build.gradle.kts b/docs-developer/build.gradle.kts new file mode 100644 index 00000000..e920c6f8 --- /dev/null +++ b/docs-developer/build.gradle.kts @@ -0,0 +1,15 @@ +import org.jetbrains.dokkaVersionType +import org.jetbrains.DokkaVersionType + +plugins { + id("ru.vyarus.mkdocs") version "2.4.0" +} + +if (dokkaVersionType != DokkaVersionType.RELEASE) { + // Do not generate the root index.html file with the redirect + // to a non-release version, otherwise GitHub pages based documentation + // will always lead to the non-stable documentation. + // For more details, see https://github.com/Kotlin/dokka/issues/2869. + // For configuration details, see https://xvik.github.io/gradle-mkdocs-plugin/3.0.0/examples/#simple-multi-version. + mkdocs.publish.rootRedirect = false +} diff --git a/docs-developer/src/doc/docs/developer_guide/architecture/architecture_overview.md b/docs-developer/src/doc/docs/developer_guide/architecture/architecture_overview.md new file mode 100644 index 00000000..d72dda91 --- /dev/null +++ b/docs-developer/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 +the most straightforward 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](https://mermaid.js.org/) 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 given level. + +## Overview of data model + +Generating API documentation begins with input source files (`.kt`, `.java`, etc) and ends with some output files +(`.html`/`.md`, 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`](data_model/documentable_model.md) - 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`](data_model/page_content.md) - 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 the so-called [Content model](data_model/page_content.md#content-model). +* `Output` - specific output formats like HTML / Markdown / Javadoc and so on. This is a mapping of the pages/content + model to a human-readable and visual representation. For instance: + * `PageNode` is mapped as + * `.html` file for the HTML format + * `.md` file for the Markdown format + * `ContentList` is mapped as + * `<li>` / `<ul>` for the HTML format + * `1.` / `*` for the Markdown format + * `ContentCodeBlock` is mapped as + * `<code>` or `<pre>` with some CSS styles in the HTML format + * Text wrapped in triple backticks for the 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 altering everything else. + +For instance, if you wanted to make an annotation / function / class invisible in the final documentation, you would only +need to modify the `Documentables` level by filtering undesirable declarations 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 `Pages` layer 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/documentable_model.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_extension_points.md) and [Base extensions](extension_points/base_plugin.md). + +## Overview of extension points + +An _extension point_ usually represents a pluggable interface that performs an action during one of the stages of +generating documentation. An _extension_ is, therefore, an implementation of the 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 +// declare your own plugin +class MyPlugin : DokkaPlugin() { + // create an extension point for developers to use + val signatureProvider by extensionPoint<SignatureProvider>() + + // provide a default implementation + val defaultSignatureProvider by extending { + signatureProvider with KotlinSignatureProvider() + } + + // register our own extension in Dokka's Base plugin by overriding its default implementation + val dokkaBasePlugin by lazy { plugin<DokkaBase>() } + val multimoduleLocationProvider by extending { + (dokkaBasePlugin.locationProviderFactory + providing MultimoduleLocationProvider::Factory + override dokkaBasePlugin.locationProvider) + } +} + +class MyExtension(val context: DokkaContext) { + + // use an existing extension + 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, see [Introduction to Extensions](extension_points/extension_points.md). + +For an overview of existing extension points, see [Core extension points](extension_points/core_extension_points.md) and +[Base extensions](extension_points/base_plugin.md). + +## Historical context + +This is a second iteration of Dokka that was built from scratch. + +If you want to learn more about why Dokka was redesigned this way, watch this great talk by Paweł Marks: +[New Dokka - Designed for Fearless Creativity](https://www.youtube.com/watch?v=OvFoTRhqaKg). The general principles +and general architecture are the same, although it may be outdated in some areas, so please double-check. diff --git a/docs-developer/src/doc/docs/developer_guide/architecture/data_model/documentable_model.md b/docs-developer/src/doc/docs/developer_guide/architecture/data_model/documentable_model.md new file mode 100644 index 00000000..b30780fc --- /dev/null +++ b/docs-developer/src/doc/docs/developer_guide/architecture/data_model/documentable_model.md @@ -0,0 +1,251 @@ +# Documentable Model + +The Documentable model represents the data that is parsed from some programming language sources. Think of this data as +of something that could be seen or produced by a compiler frontend, it's not far off from the truth. + +By default, the documentables are created from: + +* Descriptors (Kotlin's K1 compiler) +* Symbols (Kotlin's K2 compiler) +* [PSI](https://plugins.jetbrains.com/docs/intellij/psi.html) (Java's model). + +Code-wise, you can have a look at following classes: + +* `DefaultDescriptorToDocumentableTranslator` - responsible for Kotlin -> `Documentable` mapping +* `DefaultPsiToDocumentableTranslator` - responsible for Java -> `Documentable` mapping + +Upon creation, the documentable model represents 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](../extension_points/core_extension_points.md#documentablemerger). + +## Documentable + +The main building block of the documentable model is the `Documentable` class. It is the base class for all more specific +types. All implementations represent elements of source code with mostly self-explanatory names: `DFunction`, +`DPackage`, `DProperty`, and so on. + +`DClasslike` is the base class for all class-like documentables, such as `DClass`, `DEnum`, `DAnnotation` and others. + +The contents of each documentable normally represent what you would see in the source code. + +For example, if you open +`DClass`, you should find that it contains references to functions, properties, companion objects, constructors and so +on. `DEnum` should have references to its 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 are 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 the documentables (other than direct ownership) are described using `DRI`. + +For example, `DFunction` with a parameter of type `Foo` only has `Foo`'s `DRI`, but 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` modifiers) with particular +[source sets](https://kotlinlang.org/docs/multiplatform-discover-project.html#source-sets). + +This comes in handy if the `expect` / `actual` declarations differ. For example, 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 + +The Documentation model is used alongside documentables to store data obtained by parsing +code comments (such as KDocs / Javadocs). + +### DocTag + +`DocTag` describes a specific documentation syntax element. + +It's universal across language sources. For example, the DocTag `B` is the same for `**bold**` in Kotlin and +`<b>bold</b>` in Java. + +However, some DocTag elements are specific to one language. There are many such examples for Java, because it allows +HTML tags inside the Javadoc comments, some of which are simply not possible to reproduce with Markdown that KDocs use. + +`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 it, each `TagWrapper` has `DocTag` children. + +```kotlin +/** + * @author **Ben Affleck* + * @return nothing, except _sometimes_ it may throw an [Error] + */ +fun foo() {} +``` + +### DocumentationNode + +`DocumentationNode` acts as a container for multiple `TagWrapper` elements for a specific `Documentable`, usually +used like this: + +```kotlin +data class DFunction( + ... + val documentation: SourceSetDependent<DocumentationNode>, + ... +) +``` diff --git a/docs-developer/src/doc/docs/developer_guide/architecture/data_model/extra.md b/docs-developer/src/doc/docs/developer_guide/architecture/data_model/extra.md new file mode 100644 index 00000000..d7412e36 --- /dev/null +++ b/docs-developer/src/doc/docs/developer_guide/architecture/data_model/extra.md @@ -0,0 +1,91 @@ +# Extra + +## Introduction + +`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. + +`ExtraProperty` classes are available both in the [Documentable](documentable_model.md) and the [Content](page_content.md#content-model) +models. + +To create a new extra, you need to implement the `ExtraProperty` interface. It is advised to use the 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 (the `mergeStrategyFor` method) for extras is invoked during the +[merging](../extension_points/core_extension_points.md#documentablemerger) of the documentables from different +[source sets](https://kotlinlang.org/docs/multiplatform-discover-project.html#source-sets), when the documentables being +merged have their own `Extra` of the same type. + +## PropertyContainer + +All extras for `ContentNode` and `Documentable` classes are stored in the `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 generic class parameter `C` limits the types of properties that can be stored in the container - it must +match the generic `C` class parameter from the `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 extra property, store it and then retrieve its value: + +```kotlin +// Extra that is applicable only to DFunction +data class CustomExtra(val customExtraValue: String) : ExtraProperty<DFunction> { + override val key: ExtraProperty.Key<Documentable, *> = CustomExtra + companion object: ExtraProperty.Key<Documentable, CustomExtra> +} + +// Storing it inside the documentable +fun DFunction.withCustomExtraProperty(data: String): DFunction { + return this.copy( + extra = extra + CustomExtra(data) + ) +} + +// Retrieveing it from the documentable +fun DFunction.getCustomExtraPropertyValue(): String? { + return this.extra[CustomExtra]?.customExtraValue +} +``` + +___ + +You can also use extras as markers, without storing any data in them: + +```kotlin + +object MarkerExtra : ExtraProperty<Any>, ExtraProperty.Key<Any, MarkerExtra> { + override val key: ExtraProperty.Key<Any, *> = this +} + +fun Documentable.markIfFunction(): Documentable { + return when(this) { + is DFunction -> this.copy(extra = extra + MarkerExtra) + else -> this + } +} + +fun WithExtraProperties<Documentable>.isMarked(): Boolean { + return this.extra[MarkerExtra] != null +} +``` diff --git a/docs-developer/src/doc/docs/developer_guide/architecture/data_model/page_content.md b/docs-developer/src/doc/docs/developer_guide/architecture/data_model/page_content.md new file mode 100644 index 00000000..eb85200f --- /dev/null +++ b/docs-developer/src/doc/docs/developer_guide/architecture/data_model/page_content.md @@ -0,0 +1,144 @@ +# Page / Content Model + +Even though the `Page` and `Content` models reside on the same level (under `Page`), it is easier to view them as two +different models altogether, even though `Content` is only used in conjunction with and inside the `Page` model only. + +## Page + +The 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. + +The Page model is independent of the final output format. In other words, it's universal. Which file extension the pages +should be created as (`.html`, `.md`, etc), and how, is up to the +[Renderer](../extension_points/core_extension_points.md#renderer) extension. + +Subclasses of the `PageNode` class represent the different kinds of pages, such as `ModulePage`, `PackagePage`, +`ClasslikePage`, `MemberPage` and so on. + +The Page model can be represented as a tree, with `RootPageNode` at the root. + +Here's an example of how an arbitrary project's `Page` tree might look like, if the project consists of a module with +3 packages, one of which contains a top level function, a 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 a page that has user-visible content on it. + +## Content Model + +The Content model describes what the pages consist of. It is essentially a set of building blocks that you can put +together to represent some content. It is also output-format independent and universal. + +For an example, have a look at the subclasses of `ContentNode`: `ContentText`, `ContentList`, `ContentTable`, +`ContentCodeBlock`, `ContentHeader` and so on -- all self-explanatory. You can group chunks of content together with +`ContentGroup` - for example, to wrap all children with a style. + +```kotlin +// real example of composing content using the `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 the responsibility of the `Renderer` (i.e a specific output format) to render it in a way the user can process it, +be it visually (html pages) or otherwise (json). + +For instance, `HtmlRenderer` might render `ContentCodeBlock` as `<code>text</code>`, but `CommonmarkRenderer` might +render it using backticks. + +### DCI + +Each node is identified by a unique `DCI`, which stands for _Dokka Content Identifier_. + +`DCI` aggregates `DRI`s of all documentables that are used by the given `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 be rendered as part of a composite +page, like a single one tab or a block within a class's page. + +For example, on the same page that describes a class you can have multiple sections (== `ContentKind`s). +One to describe functions, one to describe properties, another one to describe the constructors, and so on. + +### Styles + +Each `ContentNode` has a `styles` property in case you want to indicate to the `Renderer` that this content needs to be +rendered in a certain way. + +```kotlin +group(styles = setOf(TextStyle.Paragraph)) { + text("Text1", styles = setOf(TextStyle.Bold)) + text("Text2", styles = setOf(TextStyle.Italic)) +} +``` + +It is responsibility of the `Renderer` (i.e a specific output format) to render it in a way the user can process it. +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 the `HtmlRenderer` extension 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 the `Documentable` model are propagated into the `Content` model, and are available +in the `Renderer` extensions. + +This element is a bit complex, so you can read more about how to use it [in a separate section](extra.md). diff --git a/docs-developer/src/doc/docs/developer_guide/architecture/extension_points/base_plugin.md b/docs-developer/src/doc/docs/developer_guide/architecture/extension_points/base_plugin.md new file mode 100644 index 00000000..88579be7 --- /dev/null +++ b/docs-developer/src/doc/docs/developer_guide/architecture/extension_points/base_plugin.md @@ -0,0 +1,33 @@ +# Base plugin + +`DokkaBase` represents Dokka's _Base_ plugin, which provides a number of sensible default implementations for +`CoreExtensions`, as well as declares its own, more high-level abstractions and extension points to be used from other +plugins and output formats. + +If you want to develop a simple plugin that only changes a few details, it is very convenient to rely on +default implementations and use extension points defined in `DokkaBase`, as it reduces the scope of changes you need to make. + +`DokkaBase` is used extensively in Dokka's own output formats. + +You can learn how to add, use, override and configure extensions and extension points in +[Introduction to Extensions](extension_points.md) - all of that information is applicable to the `DokkaBase` plugin as well. + +## Extension points + +Some notable extension points defined in Dokka's Base plugin. + +### PreMergeDocumentableTransformer + +`PreMergeDocumentableTransformer` is very similar to the +[DocumentableTransformer](core_extension_points.md#documentabletransformer) core extension point, but it is used during +an earlier stage by the [Single module generation](generation_implementations.md#singlemodulegeneration). + +This extension point allows you to apply any transformations to the [Documentables model](../data_model/documentable_model.md) +before the project's [source sets](https://kotlinlang.org/docs/multiplatform-discover-project.html#source-sets) are merged. + +It is useful if you want to filter/map existing documentables. For example, 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, whereas the rest is taken care of. diff --git a/docs-developer/src/doc/docs/developer_guide/architecture/extension_points/core_extension_points.md b/docs-developer/src/doc/docs/developer_guide/architecture/extension_points/core_extension_points.md new file mode 100644 index 00000000..fc0088c9 --- /dev/null +++ b/docs-developer/src/doc/docs/developer_guide/architecture/extension_points/core_extension_points.md @@ -0,0 +1,103 @@ +# 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 in Dokka. + +For higher-level extension functions that can be used in different output formats, have a look at the +[Base plugin](base_plugin.md). + +You can find all core extensions in the `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 example, Dokka's 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 higher-level extensions and extension +points where applicable. + +See [Generation implementations](generation_implementations.md) to learn about the default implementations. + +## SourceToDocumentableTranslator + +`SourceToDocumentableTranslator` translates any given sources into the Documentable model. + +Kotlin and Java sources are supported by default by the [Base plugin](base_plugin.md), but you can analyze any language +as long as you can map it to the [Documentable](../data_model/documentable_model.md) model. + +For reference, see + +* `DefaultDescriptorToDocumentableTranslator` for Kotlin sources translation +* `DefaultPsiToDocumentableTranslator` for Java sources translation + +## DocumentableMerger + +`DocumentableMerger` merges all `DModule` instances into one. Only one extension of this type is expected to be +registered. + +## DocumentableTransformer + +`DocumentableTransformer` performs the same function as `PreMergeDocumentableTransformer`, but after merging source +sets. + +Notable example is `InheritorsExtractorTransformer`, it extracts inheritance information from +[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) page for more information and examples. + +Output formats can either use the same page structure or define their own. + +Only a single extension of this type is expected to be registered. + +## PageTransformer + +`PageTransformer` is useful if you need to add, remove or modify generated pages or their content. + +Using this extension point, plugins like `org.jetbrains.dokka:mathjax-pligin` can add `.js` scripts to the HTML pages. + +If you want all overloaded functions to be rendered on the same page instead of separate ones, +you can use `PageTransformer` to combine the pages into a single one. + +## Renderer + +`Renderer` - defines the rules on how to render pages and their content: which files to create and how to display +the content properly. + +Custom output format plugins should use the `Renderer` extension point. Notable examples are `HtmlRenderer` +and `CommonmarkRenderer`. + +## PostAction + +`PostAction` can be used for when you want to run some actions after the documentation has been generated - for example, +if you want to move some files around or log some informational messages. + +Dokka's [Versioning plugin](https://github.com/Kotlin/dokka/tree/master/plugins/versioning) utilizes `PostAction` +to move generated documentation to the versioned directories. + diff --git a/docs-developer/src/doc/docs/developer_guide/architecture/extension_points/extension_points.md b/docs-developer/src/doc/docs/developer_guide/architecture/extension_points/extension_points.md new file mode 100644 index 00000000..97b02a7d --- /dev/null +++ b/docs-developer/src/doc/docs/developer_guide/architecture/extension_points/extension_points.md @@ -0,0 +1,162 @@ +# Extension points + +In this section you can learn how to create new extension points, how to configure existing ones, and how to query for +registered extensions when generating documentation. + +## Declaring extension points + +If you are writing a plugin, you can create your own extension points that other developers (or you) can use in other +plugins / parts 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 implementations for your extension points. 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 implementations in order to customize a plugin's behaviour. + +If you want to provide an implementation for an extension point declared in an external plugin (including `DokkaBase`), +you can use plugin querying API to do that. + +The example below shows how to extend `MyPlugin` (that was created above) with an 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() +} +``` + +Alternatively, if it is your own plugin, 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() +} +``` + +### Providing + +If you need to have access to `DokkaContext` when creating an extension, you can use the `providing` keyword 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 by some +extension points, for example the `Documentable` transformers, because all registered transformer extensions do their own +transformations independently and one after the other. + +However, a plugin can expect only a single extension to be registered for an extension point. In this case, you can use +the `override` keyword to override the existing registered extension: + +```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 the +`order` construct: + +```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 the `applyIf` construct: + +```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 extensions have been +[registered](#extending-from-extension-points), you can use `query` and `querySingle` functions to find all or just a +single implementation. + +```kotlin +class MyExtension(context: DokkaContext) { + // returns all registered extensions for the 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 the 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 `DokkaContext`, you can use the [providing](#providing) keyword when registering an extension. diff --git a/docs-developer/src/doc/docs/developer_guide/architecture/extension_points/generation_implementations.md b/docs-developer/src/doc/docs/developer_guide/architecture/extension_points/generation_implementations.md new file mode 100644 index 00000000..3d857fec --- /dev/null +++ b/docs-developer/src/doc/docs/developer_guide/architecture/extension_points/generation_implementations.md @@ -0,0 +1,40 @@ +# Generation implementations + +There are two main implementations of the [Generation](core_extension_points.md#generation) core extension point: + +* `SingleModuleGeneration` - generates documentation for a single module, for instance when `dokkaHtml` task is invoked +* `AllModulesPageGeneration` - generates multi-module documentation, for instance when `dokkaHtmlMultiModule` task is + invoked. + +## SingleModuleGeneration + +`SingleModuleGeneration` is at the heart of generating documentation. It utilizes [core](core_extension_points.md) and +[base](base_plugin.md) extensions to build the documentation from start to finish. + +Below you can see the flow of how Dokka's [data model](../architecture_overview.md#overview-of-data-model) is transformed +by various core and base extensions. + +```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 +``` + +You can read about what each stage does in [Core extension points](core_extension_points.md) and +[Base plugin](base_plugin.md). + +## AllModulesPageGeneration + +`AllModulesPageGeneration` utilizes the output generated by `SingleModuleGeneration`. + +Under the hood, it just collects all of the pages generated for individual modules, and assembles it all together, +creating navigation links between the modules and so on. diff --git a/docs-developer/src/doc/docs/developer_guide/community/slack.md b/docs-developer/src/doc/docs/developer_guide/community/slack.md new file mode 100644 index 00000000..5e57f2ac --- /dev/null +++ b/docs-developer/src/doc/docs/developer_guide/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/docs-developer/src/doc/docs/developer_guide/introduction.md b/docs-developer/src/doc/docs/developer_guide/introduction.md new file mode 100644 index 00000000..627afa3a --- /dev/null +++ b/docs-developer/src/doc/docs/developer_guide/introduction.md @@ -0,0 +1,22 @@ +# Developer guides + +The purpose of the Developer guides documentation 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. + +[CONTRIBUTING.md](https://github.com/Kotlin/dokka/blob/master/CONTRIBUTING.md) contains information that can be useful +if you want to contribute to Dokka. + +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 understanding of Dokka and how to develop +for it. + +If you have any questions, feel free to get in touch with maintainers via [Slack](community/slack.md) or +[GitHub](https://github.com/kotlin/dokka). diff --git a/docs-developer/src/doc/docs/developer_guide/plugin-development/introduction.md b/docs-developer/src/doc/docs/developer_guide/plugin-development/introduction.md new file mode 100644 index 00000000..1008e336 --- /dev/null +++ b/docs-developer/src/doc/docs/developer_guide/plugin-development/introduction.md @@ -0,0 +1,73 @@ +# Introduction to plugin development + +Dokka was built from the ground up to be easily extensible and highly customizable, which allows the community to +implement plugins for missing or very specific features that are not provided out of the box. + +Dokka plugins range anywhere from supporting other programming language sources to exotic output formats. You can add +support for your own KDoc tags or annotations, teach Dokka how to render different DSLs that are found in KDoc +descriptions, visually redesign Dokka's pages to be seamlessly integrated into your company's website, integrate +it with other tools and so much more. + +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/documentable_model.md) and +[extensions](../architecture/extension_points/extension_points.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, a Dokka plugin requires `dokka-core` as a dependency: + +```kotlin +import org.jetbrains.kotlin.gradle.dsl.JvmTarget +import org.jetbrains.kotlin.gradle.tasks.KotlinCompile + + +plugins { + kotlin("jvm") version "<kotlin_version>" +} + +dependencies { + compileOnly("org.jetbrains.dokka:dokka-core:<dokka_version>") +} + +tasks.withType<KotlinCompile>().configureEach { + compilerOptions.jvmTarget.set(JvmTarget.JVM_1_8) +} +``` + +In order to load a plugin into Dokka, your class must extend the `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's configuration step 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 points to use, have a look at [core extensions](../architecture/extension_points/core_extension_points.md) and +[base extensions](../architecture/extension_points/base_plugin.md). + +You can learn how to declare extension points and extensions in +[Introduction to Extension points](../architecture/extension_points/extension_points.md). + +In case no suitable extension point exists for your use case, do share the use case with the +[maintainers](../community/slack.md) — it might be added in a future version of Dokka. + +## Example + +You can follow the [sample plugin tutorial](sample-plugin-tutorial.md), which covers the creation of a simple plugin +that hides members annotated with your own `@Internal` annotation: that is, it excludes these members from the generated +documentation. + +For more practical examples, have a look at sources of +[community plugins](https://kotlinlang.org/docs/dokka-plugins.html#notable-plugins). + +## Help + +If you have any further questions, feel free to get in touch with Dokka's maintainers via [Slack](../community/slack.md) +or [GitHub](https://github.com/kotlin/dokka). diff --git a/docs-developer/src/doc/docs/developer_guide/plugin-development/sample-plugin-tutorial.md b/docs-developer/src/doc/docs/developer_guide/plugin-development/sample-plugin-tutorial.md new file mode 100644 index 00000000..55d7001f --- /dev/null +++ b/docs-developer/src/doc/docs/developer_guide/plugin-development/sample-plugin-tutorial.md @@ -0,0 +1,297 @@ +# 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_extension_points.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/extension_points.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). + +___ + +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). diff --git a/docs-developer/src/doc/docs/developer_guide/workflow.md b/docs-developer/src/doc/docs/developer_guide/workflow.md new file mode 100644 index 00000000..7db5382d --- /dev/null +++ b/docs-developer/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 Dokka plugin, there are 3 essential things +you need to know how to do: + +1. How to build Dokka or a plugin +2. How to use/test locally built Dokka in a project +3. How to debug Dokka or a plugin in IntelliJ IDEA + +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. + +## Build 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 a message like `API check failed for project ..` during the `build` phase, it indicates that the +[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. + +## Use / test 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.8.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.8.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 Dokka plugin. + +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 multi-module / 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 the desired Dokka task with `--no-daemon`. Gradle should wait until you attach with debugger before proceeding + with the task, so no need to hurry here. + <br/>Example: `./gradlew dokkaHtml -Dorg.gradle.debug=true --no-daemon`. + +4. Open Dokka in IntelliJ IDEA, set a breakpoint and, using remote debug in IntelliJ IDEA, + [Attach to process](https://www.jetbrains.com/help/idea/attaching-to-local-process.html#attach-to-remote) + running on the default port 5005. You can do that either by creating a `Remote JVM Debug` Run/Debug configuration + or by attaching to the process via `Run` -> `Attach to process` + +!!! note + The reason for `--no-daemon` is that + [Gradle daemons](https://docs.gradle.org/current/userguide/gradle_daemon.html) continue to exist even after the task + has completed execution, so you might hang in debug or experience issues with `port was already in use` if you try + to run it again. + + If you previously ran Dokka with daemons and you are already encountering problems with it, try killing + gradle daemons. For instance, via `pkill -f gradle.*daemon` + +In case you need to debug some other part of the build - consult the official Gradle +tutorials on [Troubleshooting Builds](https://docs.gradle.org/current/userguide/troubleshooting.html). diff --git a/docs-developer/src/doc/docs/dokka_colors.css b/docs-developer/src/doc/docs/dokka_colors.css new file mode 100644 index 00000000..69a24359 --- /dev/null +++ b/docs-developer/src/doc/docs/dokka_colors.css @@ -0,0 +1,3 @@ +.md-header, .md-tabs { + background-color: #27282c +} diff --git a/docs-developer/src/doc/docs/favicon.svg b/docs-developer/src/doc/docs/favicon.svg new file mode 100755 index 00000000..1fea0877 --- /dev/null +++ b/docs-developer/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/docs-developer/src/doc/docs/index.md b/docs-developer/src/doc/docs/index.md new file mode 100644 index 00000000..2cedfe35 --- /dev/null +++ b/docs-developer/src/doc/docs/index.md @@ -0,0 +1,9 @@ +# Dokka + +Dokka is an API documentation engine for Kotlin. + +If you want to learn how to use Dokka, see +[documentation on kotlinlang.org](https://kotlinlang.org/docs/dokka-introduction.html). + +If you want to learn more about Dokka's internals and/or how to write Dokka plugins, +see [Developer guides](developer_guide/introduction.md). diff --git a/docs-developer/src/doc/mkdocs.yml b/docs-developer/src/doc/mkdocs.yml new file mode 100644 index 00000000..533d32b1 --- /dev/null +++ b/docs-developer/src/doc/mkdocs.yml @@ -0,0 +1,86 @@ +site_name: Dokka + +# Meta tags (placed in header) +site_description: Dokka is an API documentation engine for Kotlin, performing the same function as the Javadoc tool for Java +site_author: JetBrains +site_url: https://github.com/Kotlin/dokka + +# Repository (add link to repository on each page) +repo_name: dokka +repo_url: https://github.com/Kotlin/dokka +edit_uri: edit/master/docs-developer/src/doc/docs/ + +# Copyright (shown at the footer) +copyright: 'Copyright © 2023 JetBrains' + +# Material theme +theme: + name: 'material' + favicon: favicon.svg + social: + - type: 'github' + link: 'https://github.com/Kotlin/dokka' + features: + - navigation.expand + - navigation.tabs + - navigation.instant + - navigation.indexes + - navigation.top + +# Extensions +markdown_extensions: + - admonition + - codehilite: + guess_lang: false + - footnotes + - meta + - def_list + - toc: + permalink: true + - pymdownx.betterem: + smart_enable: all + - pymdownx.caret + - pymdownx.inlinehilite + - pymdownx.magiclink + - pymdownx.smartsymbols + - attr_list + - md_in_html + - pymdownx.superfences: + custom_fences: + - name: mermaid + class: mermaid + format: !!python/name:pymdownx.superfences.fence_code_format + +# Dev server binding for livereload +dev_addr: 127.0.0.1:3001 + +nav: + - Home: + - index.md + - User guides: https://kotlinlang.org/docs/dokka-introduction.html + - Developer guides: developer_guide/introduction.md + - Community: developer_guide/community/slack.md + - User guides: + - https://kotlinlang.org/docs/dokka-introduction.html + - Developer guides: + - Developer guides: developer_guide/introduction.md + - Workflow: developer_guide/workflow.md + - Internals: + - Architecture: developer_guide/architecture/architecture_overview.md + - Data model: + - Documentables: developer_guide/architecture/data_model/documentable_model.md + - Page & Content: developer_guide/architecture/data_model/page_content.md + - Extra properties: developer_guide/architecture/data_model/extra.md + - Extensions: + - Extension points: developer_guide/architecture/extension_points/extension_points.md + - Core extension points: developer_guide/architecture/extension_points/core_extension_points.md + - Base extensions: developer_guide/architecture/extension_points/base_plugin.md + - Generation implementations: developer_guide/architecture/extension_points/generation_implementations.md + - Plugin development: + - Plugin development: developer_guide/plugin-development/introduction.md + - Sample plugin tutorial: developer_guide/plugin-development/sample-plugin-tutorial.md + - Community: + - Slack: developer_guide/community/slack.md + +extra_css: + - dokka_colors.css |
