diff options
Diffstat (limited to 'mkdocs/src/doc/docs/developer_guide/architecture')
7 files changed, 0 insertions, 934 deletions
diff --git a/mkdocs/src/doc/docs/developer_guide/architecture/architecture_overview.md b/mkdocs/src/doc/docs/developer_guide/architecture/architecture_overview.md deleted file mode 100644 index fb11f32a..00000000 --- a/mkdocs/src/doc/docs/developer_guide/architecture/architecture_overview.md +++ /dev/null @@ -1,123 +0,0 @@ -# Architecture overview - -Normally, you would think that a tool like `Dokka` simply parses some programming language sources and generates -`HTML` pages for whatever it sees along the way, with little to no abstractions. That would be the simplest and -shortest way to implement an API documentation engine. - -However, it was clear that `Dokka` may need to generate documentation from various sources (not only `Kotlin`), that users -might request additional output formats (like `Markdown`), that users might need additional features like supporting -custom `KDoc` tags or rendering `mermaid.js` diagrams - all these things would require changing a lot of code inside -`Dokka` itself if all solutions were hardcoded. - -For this reason, `Dokka` was built from the ground up to be easily extensible and customizable by adding several layers -of abstractions to the data model, and by providing pluggable extension points, giving you the ability to introduce -selective changes on a single level. - -## Overview of data model - -Generating API documentation begins with `Input` source files (`.kts`, `.java`, etc) and ends with some `Output` files -(`.html`/`.md` pages, etc). However, to allow for extensibility and customization, several input and output independent -abstractions have been added to the data model. - -Below you can find the general pipeline of processing data gathered from sources and the explanation for each stage. - -```mermaid -flowchart TD - Input --> Documentables --> Pages --> Output -``` - -* `Input` - generalization of sources, by default `Kotlin`/`Java` sources, but could be virtually anything -* `Documentables` - unified data model that represents _any_ parsed sources as a tree, independent of the source - language. Examples of a `Documentable`: class, function, package, property, etc -* `Pages` - universal model that represents output pages (e.g a function/property page) and the content it's composed of - (lists, text, code blocks) that the users needs to see. Not to be confused with `.html` pages. Goes hand in hand - with so-called `Content` model. -* `Output` - specific output format like `HTML`/`Markdown`/`Javadoc`/etc. This is a mapping of pages/content model to - some human-readable and visual representation. For instance: - * `PageNode` is mapped as - * `.html` file for `HTML` format - * `.md` file for `Markdown` format - * `ContentList` is mapped as - * `<li>` / `<ul>` for `HTML` format - * `1.` / `*` for `Markdown` format - * `ContentCodeBlock` is mapped as - * `<code>` or `<pre>` with some CSS styles in `HTML` format - * Text wrapped in triple backticks for `Markdown` format - - -You, as a `Dokka` developer or a plugin writer, can use extension points to introduce selective changes to the -model on one particular level without touching everything else. - -For instance, if you wanted to make some annotation/function/class invisible in the final documentation, you would only -need to modify the `Documentables` model by filtering undesirable members out. If you wanted to display all overloaded -methods on the same page instead of on separate ones, you would only need to modify the `Page` model by merging multiple -pages into one, and so on. - -For a deeper dive into Dokka's model with more examples and details, -see sections about [Documentables](data_model/documentables.md) and [Page/Content](data_model/page_content.md) - -For an overview of existing extension points that let you transform Dokka's models, see -[Core extension points](extension_points/core_extensions.md) and [Base extensions](extension_points/base_extensions.md). - -## Overview of extension points - -An extension point usually represents some pluggable interface that performs an action during one of the stages of -generating documentation. An extension is therefore an implementation of that interface which is extending the -extension point. - -You can create extension points, provide your own implementations (extensions) and configure them. All of -this is possible with Dokka's plugin/extension point API. - -Here's a sneak peek of the DSL: - -```kotlin -class MyPlugin : DokkaPlugin() { - // create an extension point for other developers - val signatureProvider by extensionPoint<SignatureProvider>() - - // provide a default implementation - val defaultSignatureProvider by extending { - signatureProvider with KotlinSignatureProvider() - } - - // register our own extension in base plugin and override its default - val dokkaBasePlugin by lazy { plugin<DokkaBase>() } - val multimoduleLocationProvider by extending { - (dokkaBasePlugin.locationProviderFactory - providing MultimoduleLocationProvider::Factory - override dokkaBasePlugin.locationProvider) - } -} - -// use a registered extention, pretty much dependency injection -class MyExtension(val context: DokkaContext) { - - val signatureProvider: SignatureProvider = context.plugin<MyPlugin>().querySingle { signatureProvider } - - fun doSomething() { - signatureProvider.signature(..) - } -} - -interface SignatureProvider { - fun signature(documentable: Documentable): List<ContentNode> -} - -class KotlinSignatureProvider : SignatureProvider { - override fun signature(documentable: Documentable): List<ContentNode> = listOf() -} -``` - -For a deeper dive into extensions and extension points with more examples and details, see -[Introduction to Extensions](extension_points/introduction.md). - -For an overview of existing extension points, see [Core extension points](extension_points/core_extensions.md) and -[Base extensions](extension_points/base_extensions.md). - -## Historical context - -This is a second iteration of Dokka that was built from scratch. - -If you want to learn more about why Dokka has been designed this way, watch this great talk by Paweł Marks: -[New Dokka - Designed for Fearless Creativity](https://www.youtube.com/watch?v=OvFoTRhqaKg). The general principles -and general architecture are the same, although it may be outdated in some areas, so please double-check. diff --git a/mkdocs/src/doc/docs/developer_guide/architecture/data_model/documentables.md b/mkdocs/src/doc/docs/developer_guide/architecture/data_model/documentables.md deleted file mode 100644 index 5264553d..00000000 --- a/mkdocs/src/doc/docs/developer_guide/architecture/data_model/documentables.md +++ /dev/null @@ -1,245 +0,0 @@ -# Documentables Model - -Documentables represent data that is parsed from sources. Think of this data model as of something that could be -seen or produced by a compiler frontend, it's not far off from the truth. - -By default, documentables are parsed from `Descriptor` (for `Kotlin`) -and [Psi](https://plugins.jetbrains.com/docs/intellij/psi.html) -(for `Java`) models. Code-wise, you can have a look at following classes: - -* `DefaultDescriptorToDocumentableTranslator` - responsible for `Kotlin` -> `Documentable` mapping -* `DefaultPsiToDocumentableTranslator` - responsible for `Java` -> `Documentable` mapping - -Upon creation, it's a collection of trees, each with `DModule` as root. - -Take some arbitrary `Kotlin` source code that is located within the same module: - -```kotlin -// Package 1 -class Clazz(val property: String) { - fun function(parameter: String) {} -} - -fun topLevelFunction() {} - -// Package 2 -enum class Enum { } - -val topLevelProperty: String -``` - -This would be represented roughly as the following `Documentable` tree: - -```mermaid -flowchart TD - DModule --> firstPackage[DPackage] - firstPackage --> DClass - firstPackage --> toplevelfunction[DFunction] - DClass --> DProperty - DClass --> DFunction - DFunction --> DParameter - DModule --> secondPackage[DPackage] - secondPackage --> DEnum - secondPackage --> secondPackageProperty[DProperty] -``` - -At later stages of transformation, all trees are folded into one (by `DocumentableMerger`). - -## Documentable - -The main building block of documentables model is `Documentable` class. It's the base class for all more specific types -that represent elements of parsed sources with mostly self-explanatory names (`DFunction`, `DPackage`, `DProperty`, etc) -. -`DClasslike` is the base class for class-like documentables such as `DClass`, `DEnum`, `DAnnotation`, etc. - -The contents of each documentable normally represent what you would see in source code. For instance, if you open -`DClass`, you should find that it contains references to functions, properties, companion object, constructors and so -on. -`DEnum` should have references to enum entries, and `DPackage` can have references to both classlikes and top-level -functions and properties (`Kotlin`-specific). - -Here's an example of a documentable: - -```kotlin -data class DClass( - val dri: DRI, - val name: String, - val constructors: List<DFunction>, - val functions: List<DFunction>, - val properties: List<DProperty>, - val classlikes: List<DClasslike>, - val sources: SourceSetDependent<DocumentableSource>, - val visibility: SourceSetDependent<Visibility>, - val companion: DObject?, - val generics: List<DTypeParameter>, - val supertypes: SourceSetDependent<List<TypeConstructorWithKind>>, - val documentation: SourceSetDependent<DocumentationNode>, - val expectPresentInSet: DokkaSourceSet?, - val modifier: SourceSetDependent<Modifier>, - val sourceSets: Set<DokkaSourceSet>, - val isExpectActual: Boolean, - val extra: PropertyContainer<DClass> = PropertyContainer.empty() -) : DClasslike(), WithAbstraction, WithCompanion, WithConstructors, - WithGenerics, WithSupertypes, WithExtraProperties<DClass> -``` - -___ - -There are three non-documentable classes that important for this model: - -* `DRI` -* `SourceSetDependent` -* `ExtraProperty`. - -### DRI - -`DRI` stans for _Dokka Resource Identifier_ - a unique value that identifies a specific `Documentable`. -All references and relations between documentables (other than direct ownership) are described using `DRI`. - -For example, `DFunction` with a parameter of type `Foo` has only `Foo`'s `DRI`, not the actual reference -to `Foo`'s `Documentable` object. - -#### Example - -For an example of how a `DRI` can look like, let's take the `limitedParallelism` function from `kotlinx.coroutines`: - -```kotlin -package kotlinx.coroutines - -import ... - -public abstract class MainCoroutineDispatcher : CoroutineDispatcher() { - - override fun limitedParallelism(parallelism: Int): CoroutineDispatcher { - ... - } -} -``` - -If we were to re-create the DRI of this function in code, it would look something like this: - -```kotlin -DRI( - packageName = "kotlinx.coroutines", - classNames = "MainCoroutineDispatcher", - callable = Callable( - name = "limitedParallelism", - receiver = null, - params = listOf( - TypeConstructor( - fullyQualifiedName = "kotlin.Int", - params = emptyList() - ) - ) - ), - target = PointingToDeclaration, - extra = null -) -``` - -If you format it as `String`, it would look like this: - -``` -kotlinx.coroutines/MainCoroutineDispatcher/limitedParallelism/#kotlin.Int/PointingToDeclaration/ -``` - -### SourceSetDependent - -`SourceSetDependent` helps handling multiplatform data by associating platform-specific data (declared with either -`expect` or `actual` modifier) with particular -[source sets](https://kotlinlang.org/docs/multiplatform-discover-project.html#source-sets). - -This comes in handy if `expect`/`actual` declarations differ. For instance, the default value for `actual` might differ -from that declared in `expect`, or code comments written for `expect` might be different from what's written -for `actual`. - -Under the hood, it's a `typealias` to a `Map`: - -```kotlin -typealias SourceSetDependent<T> = Map<DokkaSourceSet, T> -``` - -### ExtraProperty - -`ExtraProperty` is used to store any additional information that falls outside of the regular model. It is highly -recommended to use extras to provide any additional information when creating custom Dokka plugins. - -This element is a bit more complex, so you can read more about how to use it -[in a separate section](extra.md). - -___ - -## Documentation model - -Documentation model is used alongside Documentables to store data obtained by parsing -code comments (such as `KDoc`/`Javadoc`). - -### DocTag - -`DocTag` describes a specific documentation syntax element. - -It's universal across source languages. For instance, DocTag `B` is the same for `**bold**` in `Kotlin` and -`<b>bold</b>` in `Java`. - -However, some `DocTag` elements are specific to a certain language, there are many such examples for `Java` -because it allows HTML tags inside `Javadoc` comments, some of which are simply not possible to reproduce with `Markdown`. - -`DocTag` elements can be deeply nested with other `DocTag` children elements. - -Examples: - -```kotlin -data class H1( - override val children: List<DocTag> = emptyList(), - override val params: Map<String, String> = emptyMap() -) : DocTag() - -data class H2( - override val children: List<DocTag> = emptyList(), - override val params: Map<String, String> = emptyMap() -) : DocTag() - -data class Strikethrough( - override val children: List<DocTag> = emptyList(), - override val params: Map<String, String> = emptyMap() -) : DocTag() - -data class Strong( - override val children: List<DocTag> = emptyList(), - override val params: Map<String, String> = emptyMap() -) : DocTag() - -data class CodeBlock( - override val children: List<DocTag> = emptyList(), - override val params: Map<String, String> = emptyMap() -) : Code() - -``` - -### TagWrapper - -`TagWrapper` describes the whole comment description or a specific comment tag. -For example: `@see` / `@author` / `@return`. - -Since each such section may contain formatted text inside of it, each `TagWrapper` has `DocTag` children. - -```kotlin -/** - * @author **Ben Affleck* - * @return nothing, except _sometimes_ it may throw an [Error] - */ -fun foo() {} -``` - -### DocumentationNode - -`DocumentationNode` acts as a container for multiple `TagWrapper` elements for a specific `Documentable`, usually -used like this: - -```kotlin -data class DFunction( - ... - val documentation: SourceSetDependent<DocumentationNode>, - ... -) -``` diff --git a/mkdocs/src/doc/docs/developer_guide/architecture/data_model/extra.md b/mkdocs/src/doc/docs/developer_guide/architecture/data_model/extra.md deleted file mode 100644 index 0abbc70e..00000000 --- a/mkdocs/src/doc/docs/developer_guide/architecture/data_model/extra.md +++ /dev/null @@ -1,99 +0,0 @@ -# Extra - -## Introduction - -`ExtraProperty` classes are used both by [Documentable](documentables.md) and [Content](page_content.md#content-model) -models. - -Source code for `ExtraProperty`: - -```kotlin -interface ExtraProperty<in C : Any> { - interface Key<in C : Any, T : Any> { - fun mergeStrategyFor(left: T, right: T): MergeStrategy<C> = MergeStrategy.Fail { - throw NotImplementedError("Property merging for $this is not implemented") - } - } - - val key: Key<C, *> -} -``` - -To declare a new extra, you need to implement `ExtraProperty` interface. It is advised to use following pattern -when declaring new extras: - -```kotlin -data class CustomExtra( - [any data relevant to your extra], - [any data relevant to your extra] -): ExtraProperty<Documentable> { - override val key: CustomExtra.Key<Documentable, *> = CustomExtra - companion object : CustomExtra.Key<Documentable, CustomExtra> -} -``` - -Merge strategy (`mergeStrategyFor` method) for extras is invoked during -[merging](../extension_points/core_extensions.md#documentablemerger) if documentables from different -[source sets](https://kotlinlang.org/docs/multiplatform-discover-project.html#source-sets) each -have their own `Extra` of the same type. - -## PropertyContainer - -All extras for `ContentNode` and `Documentable` classes are stored in `PropertyContainer<C : Any>` class instances. - -```kotlin -data class DFunction( - ... - override val extra: PropertyContainer<DFunction> = PropertyContainer.empty() - ... -) : WithExtraProperties<DFunction> -``` - -`PropertyContainer` has a number of convenient functions for handling extras in a collection-like manner. - -The `C` generic class parameter limits the type of properties that can be stored in the container - it must -match generic `C` class parameter from `ExtraProperty` interface. This allows creating extra properties -which can only be stored in a specific `Documentable`. - -## Usage example - -In following example we will create a `DFunction`-only property, store it and then retrieve its value: - -```kotlin -data class CustomExtra(val customExtraValue: String) : ExtraProperty<DFunction> { - override val key: ExtraProperty.Key<Documentable, *> = CustomExtra - companion object: ExtraProperty.Key<Documentable, CustomExtra> -} - -fun DFunction.withCustomExtraProperty(data: String): DFunction { - return this.copy( - extra = extra + CustomExtra(data) - ) -} - -fun DFunction.getCustomExtraPropertyValue(): String? { - return this.extra[CustomExtra]?.customExtraValue -} -``` - -___ - -You can also use extras as markers, without storing any data in them: - -```kotlin - -object MarkerExtra : ExtraProperty<Any>, ExtraProperty.Key<Any, MarkerExtra> { - override val key: ExtraProperty.Key<Any, *> = this -} - -fun Documentable.markIfFunction(): Documentable { - return when(this) { - is DFunction -> this.copy(extra = extra + MarkerExtra) - else -> this - } -} - -fun WithExtraProperties<Documentable>.isMarked(): Boolean { - return this.extra[MarkerExtra] != null -} -``` diff --git a/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 deleted file mode 100644 index 54ded235..00000000 --- a/mkdocs/src/doc/docs/developer_guide/architecture/data_model/page_content.md +++ /dev/null @@ -1,140 +0,0 @@ -# Page / Content Model - -Even though `Page` and `Content` models reside on the same level (under `Page`), it's easier to view it as two different -models altogether, even though `Content` is only used in conjunction with and inside `Page` model. - -## Page - -Page model represents the structure of documentation pages to be generated. During rendering, each page -is processed separately, so one page corresponds to exactly one output file. - -Page model is independent of the final output format, in other words it's universal. Which extension the pages -should be created as (`.html`, `.md`, etc) and how is up to the `Renderer`. - -Subclasses of `PageNode` represent different kinds of rendered pages, such as `ModulePage`, `PackagePage`, -`ClasslikePage`, `MemberPage` (properties, functions), etc. - -The Page Model is a tree structure, with `RootPageNode` at the root. - -Here's an example of how an arbitrary `Page` tree might look like for a module with 3 packages, one of which contains -a top level function, top level property and a class, inside which there's a function and a property: - -```mermaid -flowchart TD - RootPageNode --> firstPackage[PackagePageNode] - RootPageNode --> secondPackage[PackagePageNode] - RootPageNode --> thirdPackage[PackagePageNode] - firstPackage --> firstPackageFirstMember[MemberPageNode - Function] - firstPackage --> firstPackageSecondMember[MemberPageNode - Property] - firstPackage ---> firstPackageClasslike[ClasslikePageNode - Class] - firstPackageClasslike --> firstPackageClasslikeFirstMember[MemberPageNode - Function] - firstPackageClasslike --> firstPackageClasslikeSecondMember[MemberPageNode - Property] - secondPackage --> etcOne[...] - thirdPackage --> etcTwo[...] -``` - -Almost all pages are derivatives of `ContentPage` - it's the type of `Page` that has `Content` on it. - -## Content Model - -Content model describes how the actual `Page` content is presented. The important thing to understand is that it's -also output-format independent and is universal. - -Content model is essentially a set of building blocks that you can put together to represent some content. -Have a look at subclasses of `ContentNode`: `ContentText`, `ContentList`, `ContentTable`, `ContentCodeBlock`, -`ContentHeader` and so on. You can group content together with `ContentGroup` - for instance, -to wrap all children with some style. - -```kotlin -// real example of composing content using `DocumentableContentBuilder` DSL -orderedList { - item { - text("This list contains a nested table:") - table { - header { - text("Col1") - text("Col2") - } - row { - text("Text1") - text("Text2") - } - } - } - item { - group(styles = setOf(TextStyle.Bold)) { - text("This is bald") - text("This is also bald") - } - } -} -``` - -It is then responsibility of `Renderer` (i.e specific output format) to render it the way it wants. - -For instance, `HtmlRenderer` might render `ContentCodeBlock` as `<code>text</code>`, but `CommonmarkRenderer` might -render it using backticks. - -___ - -### DCI - -Each node is identified by unique `DCI`, which stands for _Dokka Content Identifier_. `DCI` aggregates `DRI`s of all -`Documentables` that make up a specific `ContentNode`. - -```kotlin -data class DCI(val dri: Set<DRI>, val kind: Kind) -``` - -All references to other nodes (other than direct ownership) are described using `DCI`. - -### ContentKind - -`ContentKind` represents a grouping of content of one kind that can can be rendered as part of a composite -page (one tab/block within a class's page, for instance). - -For instance, on the same page that describes a class you can have multiple sections (== `ContentKind`). -One to describe functions, one to describe properties, another one to describe constructors and so on. - -### Styles - -Each `ContentNode` has `styles` property in case you want to incidate to `Renderer` that this content needs to be -displayed in a certain way. - -```kotlin -group(styles = setOf(TextStyle.Paragraph)) { - text("Text1", styles = setOf(TextStyle.Bold)) - text("Text2", styles = setOf(TextStyle.Italic)) -} -``` - -It is then responsibility of `Renderer` (i.e specific output format) to render it the way it wants. For instance, -`HtmlRenderer` might render `TextStyle.Bold` as `<b>text</b>`, but `CommonmarkRenderer` might render it as `**text**`. - -There's a number of existing styles that you can use, most of them are supported by `HtmlRenderer` out of the box: - -```kotlin -// for code highlighting -enum class TokenStyle : Style { - Keyword, Punctuation, Function, Operator, Annotation, - Number, String, Boolean, Constant, Builtin, ... -} - -enum class TextStyle : Style { - Bold, Italic, Strong, Strikethrough, Paragraph, ... -} - -enum class ContentStyle : Style { - TabbedContent, RunnableSample, Wrapped, Indented, ... -} -``` - -### Extra - -`ExtraProperty` is used to store any additional information that falls outside of the regular model. It is highly -recommended to use extras to provide any additional information when creating custom Dokka plugins. - -All `ExtraProperty` elements from `Documentable` model are propagated into `Content` model and are available -for `Renderer`. - -This element is a bit complex, so you can read more about how to use it [in a separate section](extra.md). diff --git a/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 deleted file mode 100644 index 16a52fab..00000000 --- a/mkdocs/src/doc/docs/developer_guide/architecture/extension_points/base_extensions.md +++ /dev/null @@ -1,13 +0,0 @@ -# Base extensions - -`DokkaBase` class is a base plugin which defines a number of default implementations for `CoreExtensions` as well as -declares its own, more high-level extension points to be used from other plugins and output formats. - -It's very convenient to use extension points and defaults defined in `DokkaBase` if you have an idea for a simple -plugin that only needs to provide a few extensions or change a single extension point and have everything else be the -default. - -`DokkaBase` is used extensively for Dokka's own output formats such as `HTML`, `Markdown`, `Mathjax` and others. - -You can learn how to add/use/override/configure extensions and extension points in -[Introduction to Extensions](introduction.md), all the information is applicable to `DokkaBase` plugin as well. diff --git a/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 deleted file mode 100644 index 77ebc15e..00000000 --- a/mkdocs/src/doc/docs/developer_guide/architecture/extension_points/core_extensions.md +++ /dev/null @@ -1,151 +0,0 @@ -# Core extension points - -Core extension points represent the main stages of generating documentation. - -These extension points are plugin and output format independent, meaning it's the very core functionality and as -low-level as can get. For higher-level extension functions that can be used in different output formats, have a look at -[Base extensions](base_extensions.md) defined in `DokkaBase`. - -You can find all core extensions in `CoreExtensions` class: -```kotlin -object CoreExtensions { - val preGenerationCheck by coreExtensionPoint<PreGenerationChecker>() - val generation by coreExtensionPoint<Generation>() - val sourceToDocumentableTranslator by coreExtensionPoint<SourceToDocumentableTranslator>() - val documentableMerger by coreExtensionPoint<DocumentableMerger>() - val documentableTransformer by coreExtensionPoint<DocumentableTransformer>() - val documentableToPageTranslator by coreExtensionPoint<DocumentableToPageTranslator>() - val pageTransformer by coreExtensionPoint<PageTransformer>() - val renderer by coreExtensionPoint<Renderer>() - val postActions by coreExtensionPoint<PostAction>() -} -``` - -On this page we'll go over each extension point individually. - -## PreGenerationChecker - -`PreGenerationChecker` can be used to run some checks and constraints. - -For instance, `Javadoc` plugin does not support generating documentation for multi-platform projects, so it uses -`PreGenerationChecker` to check for multi-platform -[source sets](https://kotlinlang.org/docs/multiplatform-discover-project.html#source-sets) and fails if it finds any. - -## Generation - -`Generation` is responsible for generating documentation as a whole, utilizing other extension points where applicable. - -There are two implementations at the moment: - -* `AllModulesPageGeneration` - generates multimodule documentation, for instance when `dokkaHtmlMultiModule` task is - invoked. -* `SingleModuleGeneration` - generates documentation for a single module, for instance when `dokkaHtml` task is invoked - -### AllModulesPageGeneration - -`AllModulesPageGeneration` utilizes output generated by `SingleModuleGeneration`. Under the hood it just collects all -pages generated for individual modules and assembles everything together, creating navigation pages between the -modules and so on. - -### SingleModuleGeneration stages - -When developing a feature or a plugin, it's more convenient to think that you are generating documentation for single -module projects, believing that Dokka will somehow take care of the rest in multimodule environment. - -`SingleModuleGeneration` is at heart of generating documentation and utilizes other core extension points, so -it's worth going over its stages. - -Below you can see the transformations of [Dokka's models](../architecture_overview.md#overview-of-data-model) and -extension interfaces responsible for each one. Notice how `Documentables` and `Pages` are transformed multiple times. - -```mermaid -flowchart TD - Input -- SourceToDocumentableTranslator --> doc1[Documentables] - subgraph documentables [ ] - doc1 -- PreMergeDocumentableTransformer --> doc2[Documentables] - doc2 -- DocumentableMerger --> doc3[Documentables] - doc3 -- DocumentableTransformer --> doc4[Documentables] - end - doc4 -- DocumentableToPageTranslator --> page1[Pages] - subgraph ide2 [ ] - page1 -- PageTransformer --> page2[Pages] - end - page2 -- Renderer --> Output -``` - -#### SourceToDocumentableTranslator - -`SourceToDocumentableTranslator` translates sources into documentable model. - -`Kotlin` and `Java` sources are supported by default, but you can analyze any language as long as you can map -it to the [Documentable](../data_model/documentables.md) model. - -For reference, see - -* `DefaultDescriptorToDocumentableTranslator` for `Kotlin` sources translation -* `DefaultPsiToDocumentableTranslator` for `Java` sources translation - -#### PreMergeDocumentableTransformer - -This extension point actually comes from `DokkaBase` and is not a core extension point, but it's used in -`SingleModuleGeneration` nonetheless. If you are implementing your own plugin without relying on `DokkaBase`, -you can either introduce a similar extension point or rely on [DocumentableTransformer](#documentabletransformer) which -will be discussed below. - -`PreMergeDocumentableTransformer` allows applying any transformation to -[Documentables model](../data_model/documentables.md) before different -[source sets](https://kotlinlang.org/docs/multiplatform-discover-project.html#source-sets) are merged. - -Useful if you want to filter/map existing documentables. For instance, if you want to exclude members annotated with -`@Internal`, you most likely need an implementation of `PreMergeDocumentableTransformer`. - -For simple condition-based filtering of documentables consider extending -`SuppressedByConditionDocumentableFilterTransformer` - it implements `PreMergeDocumentableTransformer` and only -requires one function to be overridden. The rest is taken care of. - -#### DocumentableMerger - -`DocumentableMerger` merges all `DModule` instances into one. Only one extension is expected of this type. - -#### DocumentableTransformer - -`DocumentableTransformer` performs the same function as `PreMergeDocumentableTransformer`, but after merging source -sets. - -Notable example is `InheritorsExtractorTransformer`, it extracts inherited classes data across -[source sets](https://kotlinlang.org/docs/multiplatform-discover-project.html#source-sets) and creates an inheritance -map. - -#### DocumentableToPageTranslator - -`DocumentableToPageTranslator` is responsible for creating pages and their content. See -[Page/Content model](../data_model/page_content.md) section for more information and examples. - -Different output formats can either use the same page structure or define their own in case it needs to be different. - -Only a single extension of this type is expected to be registered. - -#### PageTransformer - -`PageTransformer` is useful if you need to add/remove/modify generated pages or their content. - -Plugins like `mathjax` can add `.js` scripts to pages using this extension point. - -If you want all overloaded functions to be rendered on the same page (instead of separate ones), -you can also use `PageTransformer` to delete excessive pages and combine them into a new single one. - -#### Renderer - -`Renderer` - defines rules on what to do with pages and their content, which files to create and how to display -it properly. - -Output format implementations should use `Renderer` extension point. Notable examples are `HtmlRenderer` -and `CommonmarkRenderer`. - -## PostAction - -`PostAction` is useful for when you want to run some actions after the documentation has been generated - for instance -if you want to move some files around. - -[Versioning plugin](https://github.com/Kotlin/dokka/tree/master/plugins/versioning) 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 deleted file mode 100644 index 877d14e9..00000000 --- a/mkdocs/src/doc/docs/developer_guide/architecture/extension_points/introduction.md +++ /dev/null @@ -1,163 +0,0 @@ -# Introduction to extension points - -In this section you can learn how to create new extension points, how to use and configure existing ones and -how to query for extensions when generating documentation. - -## Declaring extension points - -If you are writing a plugin, you can create your own extension point that other developers (or you) can use later on -in some other part of code. - -```kotlin -class MyPlugin : DokkaPlugin() { - val sampleExtensionPoint by extensionPoint<SampleExtensionPointInterface>() -} - -interface SampleExtensionPointInterface { - fun doSomething(input: Input): List<Output> -} - -class Input -class Output -``` - -Usually you would want to provide some default implementation(s) for your extension point, you can do that -within the same plugin class by extending an extension point you've just created. -See [Extending from extension points](#extending-from-extension-points) for examples. - -## Extending from extension points - -You can use extension points to provide your own implementation(s) in order to customize plugin's behaviour. - -You can do that within the same class as the extension point itself: - -```kotlin -open class MyPlugin : DokkaPlugin() { - val sampleExtensionPoint by extensionPoint<SampleExtensionPointInterface>() - - val defaultSampleExtension by extending { - sampleExtensionPoint with DefaultSampleExtension() - } -} - -... - -class DefaultSampleExtension : SampleExtensionPointInterface { - override fun doSomething(input: Input): List<Output> = listOf() -} -``` - -___ - -If you want to extend someone else's plugin (including `DokkaBase`), you can use plugin querying API to do that. -In the example below we will extend `MyPlugin` that was created above with our own implementation of -`SampleExtensionPointInterface`. - -```kotlin -class MyExtendedPlugin : DokkaPlugin() { - val mySampleExtensionImplementation by extending { - plugin<MyPlugin>().sampleExtensionPoint with SampleExtensionImpl() - } -} - -class SampleExtensionImpl : SampleExtensionPointInterface { - override fun doSomething(input: Input): List<Output> = listOf() -} - -``` - -### Providing - -If you need to have access to `DokkaContext` in order to create an extension, you can use `providing` instead. - -```kotlin -val defaultSampleExtension by extending { - sampleExtensionPoint providing { context -> - // can use context to query other extensions or get configuration - DefaultSampleExtension() - } -} -``` - -You can read more on what you can do with `context` in [Obtaining extension instance](#obtaining-extension-instance). - -### Override - -By extending an extension point, you are registering an _additional_ extension. This behaviour is expected for some -extension points, for instance `Documentable` transformers, since all transformers do their own transformations and all -of them will be invoked before proceeding. - -However, a plugin can expect only a single registered extension for an extension point. In this case, you can `override` -existing registered extensions: - -```kotlin -class MyExtendedPlugin : DokkaPlugin() { - private val myPlugin by lazy { plugin<MyPlugin>() } - - val mySampleExtensionImplementation by extending { - (myPlugin.sampleExtensionPoint - with SampleExtensionImpl() - override myPlugin.defaultSampleExtension) - } -} -``` - -This is also useful if you wish to override some extension from `DokkaBase` to disable or alter it. - -### Order - -Sometimes the order in which extensions are invoked matters. This is something you can control as well using `order`: - -```kotlin -class MyExtendedPlugin : DokkaPlugin() { - private val myPlugin by lazy { plugin<MyPlugin>() } - - val mySampleExtensionImplementation by extending { - myPlugin.sampleExtensionPoint with SampleExtensionImpl() order { - before(myPlugin.firstExtension) - after(myPlugin.thirdExtension) - } - } -} -``` - -### Conditional apply - -If you want your extension to be registered only if some condition is `true`, you can use `applyIf`: - -```kotlin -class MyExtendedPlugin : DokkaPlugin() { - private val myPlugin by lazy { plugin<MyPlugin>() } - - val mySampleExtensionImplementation by extending { - myPlugin.sampleExtensionPoint with SampleExtensionImpl() applyIf { - Random.Default.nextBoolean() - } - } -} -``` - -## Obtaining extension instance - -After an extension point has been [created](#declaring-extension-points) and some extension has been -[registered](#extending-from-extension-points), you can use `query` and `querySingle` to find all or just a single -implementation for it. - -```kotlin -class MyExtension(context: DokkaContext) { - // returns all registered extensions for this extension point - val allSampleExtensions = context.plugin<MyPlugin>().query { sampleExtensionPoint } - - // will throw an exception if more than one extension is found - // use if you expect only a single extension to be registered for this extension point - val singleSampleExtensions = context.plugin<MyPlugin>().querySingle { sampleExtensionPoint } - - fun invoke() { - allSampleExtensions.forEach { it.doSomething(Input()) } - - singleSampleExtensions.doSomething(Input()) - } -} -``` - -In order to have access to context you can use [providing](#providing) when registering this as an extension. |