diff options
Diffstat (limited to 'mkdocs/src/doc')
17 files changed, 0 insertions, 1536 deletions
diff --git a/mkdocs/src/doc/docs/community/slack.md b/mkdocs/src/doc/docs/community/slack.md deleted file mode 100644 index 290d4a18..00000000 --- a/mkdocs/src/doc/docs/community/slack.md +++ /dev/null @@ -1,7 +0,0 @@ -# Slack channel - -`Dokka` has a dedicated `#dokka` channel in the `Kotlin Community Slack`, where you can ask questions and chat -about using, customizing or contributing to `Dokka`. - -[Follow the instructions](https://surveys.jetbrains.com/s3/kotlin-slack-sign-up) -to get an invite or [connect directly](https://kotlinlang.slack.com). diff --git a/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. diff --git a/mkdocs/src/doc/docs/developer_guide/introduction.md b/mkdocs/src/doc/docs/developer_guide/introduction.md deleted file mode 100644 index feb601fe..00000000 --- a/mkdocs/src/doc/docs/developer_guide/introduction.md +++ /dev/null @@ -1,19 +0,0 @@ -# Developer guides - -The purpose of `Developer guides` section is to get you acquainted with Dokka's internals so that you can start developing -your own plugins or contributing features and fixes to Dokka itself. - -If you want to start hacking on Dokka right away, the only thing you need to be aware of is the -[general workflow](workflow.md), it will teach you how to build, debug and test Dokka locally. - -If you want to get into plugin development quick, see -[Introduction to plugin development](plugin-development/introduction.md). - -If you have time to spare and want to know more about Dokka's internals, its architecture and capabilities, follow -[Architecture overview](architecture/architecture_overview.md) and subsequent sections inside `Internals`. - -Having read through all the developer guides, you'll have a pretty good unrestanding of Dokka and how to develop -for it. - -If you have any questions, feel free to get in touch with maintainers via [Slack](../community/slack.md) or -[GitHub](https://github.com/kotlin/dokka). diff --git a/mkdocs/src/doc/docs/developer_guide/plugin-development/introduction.md b/mkdocs/src/doc/docs/developer_guide/plugin-development/introduction.md deleted file mode 100644 index ad980e49..00000000 --- a/mkdocs/src/doc/docs/developer_guide/plugin-development/introduction.md +++ /dev/null @@ -1,72 +0,0 @@ -# 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/documentables.md) and -[extensions](../architecture/extension_points/introduction.md). - -## Setup - -### Template - -The easiest way to start is to use the convenient [Dokka plugin template](https://github.com/Kotlin/dokka-plugin-template). -It has pre-configured dependencies, publishing and signing of your artifacts. - -### Manual - -At a bare minimum, Dokka requires `Kotlin Gradle Plugin` and `dokka-core` dependencies: - -```kotlin -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 `DokkaPlugin` class. A fully qualified name of that class -must be placed in a file named `org.jetbrains.dokka.plugability.DokkaPlugin` under `resources/META-INF/services`. -All instances are automatically loaded during Dokka setup using `java.util.ServiceLoader`. - -## Extension points - -Dokka provides a set of entry points for which you can create your own implementations. If you are not sure which -extension point to use, have a look at [core extensions](../architecture/extension_points/core_extensions.md) and -[base extensions](../architecture/extension_points/base_extensions.md). - -You can learn how to declare extension points and use extensions in -[Introduction to Extension points](../architecture/extension_points/introduction.md). - -In case no suitable extension point exists for your use case, do share the details - it might be added in future -versions of Dokka. - -## Example - -You can follow the [sample plugin tutorial](sample-plugin-tutorial.md) which covers creation of a simple plugin: hide members -annotated with your own `@Internal` annotation, that is exclude these members from generated documentation. - -Fore more practical examples, have a look at sources of -[community plugins](https://kotlinlang.org/docs/dokka-plugins.html#notable-plugins). - -## Help - -If you have any further questions, feel free to get in touch with maintainers via [Slack](../../community/slack.md) or -[GitHub](https://github.com/kotlin/dokka). diff --git a/mkdocs/src/doc/docs/developer_guide/plugin-development/sample-plugin-tutorial.md b/mkdocs/src/doc/docs/developer_guide/plugin-development/sample-plugin-tutorial.md deleted file mode 100644 index 3869d79b..00000000 --- a/mkdocs/src/doc/docs/developer_guide/plugin-development/sample-plugin-tutorial.md +++ /dev/null @@ -1,297 +0,0 @@ -# Sample plugin tutorial - -We'll go over creating a simple plugin that covers a very common use case: generate documentation for everything except -for members annotated with a custom `@Internal` annotation - they should be hidden. - -The plugin will be tested with the following code: - -```kotlin -package org.jetbrains.dokka.internal.test - -annotation class Internal - -fun shouldBeVisible() {} - -@Internal -fun shouldBeExcludedFromDocumentation() {} -``` - -Expected behavior: function `shouldBeExcludedFromDocumentation` should not be visible in generated documentation. - -Full source code of this tutorial can be found in Dokka's examples under -[hide-internal-api](https://github.com/Kotlin/dokka/examples/plugin/hide-internal-api). - -## Preparing the project - -We'll begin by using [Dokka plugin template](https://github.com/Kotlin/dokka-plugin-template). Press the -`Use this template` button and -[open this project in IntelliJ IDEA](https://www.jetbrains.com/idea/guide/tutorials/working-with-gradle/opening-a-gradle-project/). - -First, let's rename the pre-made `template` package and `MyAwesomeDokkaPlugin` class to something of our own. - -For instance, package can be renamed to `org.example.dokka.plugin` and the class to `HideInternalApiPlugin`: - -```kotlin -package org.example.dokka.plugin - -import org.jetbrains.dokka.plugability.DokkaPlugin - -class HideInternalApiPlugin : DokkaPlugin() { - -} -``` - -After you do that, make sure to update the path to this class in -`resources/META-INF/services/org.jetbrains.dokka.plugability.DokkaPlugin`: -```kotlin -org.example.dokka.plugin.HideInternalApiPlugin -``` - -At this point you can also change project name in `settings.gradle.kts` (to `hide-internal-api` in our case) -and `groupId` in `build.gradle.kts`. - -## Extending Dokka - -After preparing the project we can begin extending Dokka with our own extension. - -Having read through [Core extensions](../architecture/extension_points/core_extensions.md), it's clear that we need -a `PreMergeDocumentableTransformer` extension in order to filter out undesired documentables. - -Moreover, the article mentioned a convenient abstract transformer `SuppressedByConditionDocumentableFilterTransformer` -which is perfect for our use case, so we can try to implement it. - -Create a new class, place it next to your plugin and implement the abstract method. You should end up with this: - -```kotlin -package org.example.dokka.plugin - -import org.jetbrains.dokka.base.transformers.documentables.SuppressedByConditionDocumentableFilterTransformer -import org.jetbrains.dokka.model.Documentable -import org.jetbrains.dokka.plugability.DokkaContext -import org.jetbrains.dokka.plugability.DokkaPlugin - -class HideInternalApiPlugin : DokkaPlugin() {} - -class HideInternalApiTransformer(context: DokkaContext) : SuppressedByConditionDocumentableFilterTransformer(context) { - - override fun shouldBeSuppressed(d: Documentable): Boolean { - return false - } -} -``` - -Now we somehow need to find all annotations applied to `d: Documentable` and see if our `@Internal` annotation is present. -However, it's not very clear how to do that. What usually helps is stopping in debugger and having a look at what fields -and values a given `Documentable` has. - -To do that, we'll need to register our extension point first, then we can publish our plugin and set the breakpoint. - -Having read through [Introduction to extensions](../architecture/extension_points/introduction.md), we now know -how to register our extensions: - -```kotlin -class HideInternalApiPlugin : DokkaPlugin() { - val myFilterExtension by extending { - plugin<DokkaBase>().preMergeDocumentableTransformer providing ::HideInternalApiTransformer - } -} -``` - -At this point we're ready to debug our plugin locally, it should already work, but do nothing. - -## Debugging - -Please read through [Debugging Dokka](../workflow.md#debugging-dokka), it goes over the same steps in more detail -and with examples. Below you will find rough instructions. - -First, let's begin by publishing our plugin to `mavenLocal()`. - -```bash -./gradlew publishToMavenLocal -``` - -This will publish your plugin under the `groupId`, `artifactId` and `version` that you've specified in your -`build.gradle.kts`. In our case it's `org.example:hide-internal-api:1.0-SNAPSHOT`. - -Open a debug project of your choosing that has Dokka configured, and add our plugin to dependencies: - -```kotlin -dependencies { - dokkaPlugin("org.example:hide-internal-api:1.0-SNAPSHOT") -} -``` - -Next, in that project let's run `dokkaHtml` with debug enabled: - -```bash -./gradlew clean dokkaHtml -Dorg.gradle.debug=true --no-daemon -``` - -Switch to the plugin project, set a breakpoint inside `shouldBeSuppressed` and run jvm remote debug. - -If you've done everything correctly, it should stop in debugger and you should be able to observe the values contained -inside `d: Documentable`. - -## Implementing plugin logic - -Now that we've stopped at our breakpoint, let's skip until we see `shouldBeExcludedFromDocumentation` function in the -place of `d: Documentable` (observe the changing `name` property). - -Looking at what's inside the object, you might notice it has 3 values in `extra`, one of which is `Annotations`. -Sounds like something we need! - -Having poked around, we come up with the following monstrosity of a code for determining if a given documentable has -`@Internal` annotation (it can of course be refactored.. later): - -```kotlin -override fun shouldBeSuppressed(d: Documentable): Boolean { - - val annotations: List<Annotations.Annotation> = - (d as? WithExtraProperties<*>) - ?.extra - ?.allOfType<Annotations>() - ?.flatMap { it.directAnnotations.values.flatten() } - ?: emptyList() - - return annotations.any { isInternalAnnotation(it) } -} - -private fun isInternalAnnotation(annotation: Annotations.Annotation): Boolean { - return annotation.dri.packageName == "org.jetbrains.dokka.internal.test" - && annotation.dri.classNames == "Internal" -} -``` - -Seems like we're done with writing our plugin and can begin testing it manually. - -## Manual testing - -At this point, the implementation of your plugin should look roughly like this: - -```kotlin -package org.example.dokka.plugin - -import org.jetbrains.dokka.base.DokkaBase -import org.jetbrains.dokka.base.transformers.documentables.SuppressedByConditionDocumentableFilterTransformer -import org.jetbrains.dokka.model.Annotations -import org.jetbrains.dokka.model.Documentable -import org.jetbrains.dokka.model.properties.WithExtraProperties -import org.jetbrains.dokka.plugability.DokkaContext -import org.jetbrains.dokka.plugability.DokkaPlugin - -class HideInternalApiPlugin : DokkaPlugin() { - val myFilterExtension by extending { - plugin<DokkaBase>().preMergeDocumentableTransformer providing ::HideInternalApiTransformer - } -} - -class HideInternalApiTransformer(context: DokkaContext) : SuppressedByConditionDocumentableFilterTransformer(context) { - - override fun shouldBeSuppressed(d: Documentable): Boolean { - val annotations: List<Annotations.Annotation> = - (d as? WithExtraProperties<*>) - ?.extra - ?.allOfType<Annotations>() - ?.flatMap { it.directAnnotations.values.flatten() } - ?: emptyList() - - return annotations.any { isInternalAnnotation(it) } - } - - private fun isInternalAnnotation(annotation: Annotations.Annotation): Boolean { - return annotation.dri.packageName == "org.jetbrains.dokka.internal.test" - && annotation.dri.classNames == "Internal" - } -} -``` - -Bump plugin version in `gradle.build.kts`, publish it to maven local, open the debug project and run `dokkaHtml` -(without debug this time). It should work, you should **not** be able to see `shouldBeExcludedFromDocumentation` -function in generated documentation. - -Manual testing is cool and all, but wouldn't it be better if we could somehow write unit tests for it? Indeed! - -## Unit testing - -You might've noticed that plugin template comes with a pre-made test class. Feel free to move it to another package -and rename it. - -We are mostly interested in a single test case - functions annotated with `@Internal` should be hidden, while all other -public functions should be visible. - -Plugin API comes with a set of convenient test utilities that are used to test Dokka itself, so it covers a wide range -of use cases. When in doubt, see Dokka's tests for reference. - -Below you will find a complete unit test that passes, and the main takeaways below that. - -```kotlin -package org.example.dokka.plugin - -import org.jetbrains.dokka.base.testApi.testRunner.BaseAbstractTest -import org.junit.Test -import kotlin.test.assertEquals - -class HideInternalApiPluginTest : BaseAbstractTest() { - - @Test - fun `should hide annotated functions`() { - val configuration = dokkaConfiguration { - sourceSets { - sourceSet { - sourceRoots = listOf("src/main/kotlin/basic/Test.kt") - } - } - } - val hideInternalPlugin = HideInternalApiPlugin() - - testInline( - """ - |/src/main/kotlin/basic/Test.kt - |package org.jetbrains.dokka.internal.test - | - |annotation class Internal - | - |fun shouldBeVisible() {} - | - |@Internal - |fun shouldBeExcludedFromDocumentation() {} - """.trimMargin(), - configuration = configuration, - pluginOverrides = listOf(hideInternalPlugin) - ) { - preMergeDocumentablesTransformationStage = { modules -> - val testModule = modules.single { it.name == "root" } - val testPackage = testModule.packages.single { it.name == "org.jetbrains.dokka.internal.test" } - - val packageFunctions = testPackage.functions - assertEquals(1, packageFunctions.size) - assertEquals("shouldBeVisible", packageFunctions[0].name) - } - } - } -} -``` - -Note that the package of the tested code (inside `testInline` function) is the same as the package that we have -hardcoded in our plugin. Make sure to change that to your own if you are following along, otherwise it will fail. - -Things to note and remember: - -1. Your test class should extend `BaseAbstractTest`, which contains base utility methods for testing. -2. You can configure Dokka to your liking, enable some specific settings, configure - [source sets](https://kotlinlang.org/docs/multiplatform-discover-project.html#source-sets), etc. All done via - `dokkaConfiguration` DSL. -3. `testInline` function is the main entry point for unit tests -4. You can pass plugins to be used in a test, notice `pluginOverrides` parameter -5. You can write asserts for different stages of generating documentation, the main ones being `Documentables` model - generation, `Pages` generation and `Output` generation. Since we implemented our plugin to work during - `PreMergeDocumentableTransformer` stage, we can test it on the same level (that is - `preMergeDocumentablesTransformationStage`). -6. You will need to write asserts using the model of whatever stage you choose. For `Documentable` transformation stage - it's `Documentable`, for `Page` generation stage you would have `Page` model, and for `Output` you can have `.html` - files that you will need to parse with `JSoup` (there are also utilities for that). - -___ - -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/mkdocs/src/doc/docs/developer_guide/workflow.md b/mkdocs/src/doc/docs/developer_guide/workflow.md deleted file mode 100644 index 388100b2..00000000 --- a/mkdocs/src/doc/docs/developer_guide/workflow.md +++ /dev/null @@ -1,100 +0,0 @@ -# Workflow - -Whether you're contributing a feature/fix to Dokka itself or developing a separate plugin, there's 3 things -you'll be doing: - -1. Building Dokka / Plugins -2. Using/Testing locally built Dokka in a (debug) project -3. Debugging Dokka / Plugin code - -We'll go over each step individually in this section. - -Examples below will be specific to Gradle and [Gradle’s Kotlin DSL](https://docs.gradle.org/current/userguide/kotlin_dsl.html), -but you can apply the same principles and run/test/debug with CLI/Maven runners and build configurations if you wish. - -## Building Dokka - -Building Dokka is pretty straightforward, with one small caveat: when you run `./gradlew build`, it will run -integration tests as well, which might take some time and will consume a lot of RAM, so you would usually want -to exclude integration tests when building locally. - -```shell -./gradlew build -x integrationTest -``` - -Unit tests which are run as part of `build` should not take much time, but you can also skip it with `-x test`. - -### Troubleshooting build - -#### API check failed for project .. - -If you see messages like `API check failed for project ..` during `build` phase, it indicates that -[binary compatibility check](https://github.com/Kotlin/binary-compatibility-validator) has failed, meaning you've -changed/added/removed some public API. - -If the change was intentional, run `./gradlew apiDump` - it will re-generate `.api` files with signatures, -and you should be able to `build` Dokka with no errors. These updated files need to be committed as well. Maintainers -will review API changes thoroughly, so please make sure it's intentional and rational. - -## Using/testing locally built Dokka - -Having built Dokka locally, you can publish it to `mavenLocal()`. This will allow you to test your changes in another -project as well as debug code remotely. - -1. Change `dokka_version` in `gradle.properties` to something that you will use later on as the dependency version. - For instance, you can set it to something like `1.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 plugin which resides in a separate project. - -1. Choose a project to debug on, it needs to have some code for which documentation will be generated. - Prefer using smaller projects that reproduce the exact problem or behaviour you want - since the less code you have, the easier it will be to understand what's going on. You can use example projects - found in [dokka/examples/gradle](https://github.com/Kotlin/dokka/tree/master/examples/gradle), there's both simple - single-module and more complex multimodule/multiplatform examples. -2. For the debug project, set `org.gradle.debug` to `true` in one of the following ways: - - * In your `gradle.properties` add `org.gradle.debug=true` - * When running Dokka tasks:<br/>`./gradlew dokkaHtml -Dorg.gradle.debug=true --no-daemon` - -3. Run desired Dokka task with `--no-daemon`. Gradle should wait until you attach with debugger before proceeding - with the task, so no need to hurry here. - <br/>Example: `./gradlew dokkaHtml -Dorg.gradle.debug=true --no-daemon`. - -4. Open Dokka in IntelliJ IDEA, set a breakpoint and, using remote debug in IntelliJ IDEA, - [Attach to process](https://www.jetbrains.com/help/idea/attaching-to-local-process.html#attach-to-remote) - running on the default port 5005. You can do that either by creating a `Remote JVM Debug` Run/Debug configuration - or by attaching to the process via `Run` -> `Attach to process` - -!!! note - The reason for `--no-daemon` is that - [Gradle daemons](https://docs.gradle.org/current/userguide/gradle_daemon.html) continue to exist even after the task - has completed execution, so you might hang in debug or experience issues with `port was already in use` if you try - to run it again. - - If you previously ran Dokka with daemons and you are already encountering problems with it, try killing - gradle daemons. For instance, via `pkill -f gradle.*daemon` - -In case you need to debug some other part of the build - consult the official Gradle -tutorials on [Troubleshooting Builds](https://docs.gradle.org/current/userguide/troubleshooting.html). diff --git a/mkdocs/src/doc/docs/dokka_colors.css b/mkdocs/src/doc/docs/dokka_colors.css deleted file mode 100644 index 69a24359..00000000 --- a/mkdocs/src/doc/docs/dokka_colors.css +++ /dev/null @@ -1,3 +0,0 @@ -.md-header, .md-tabs { - background-color: #27282c -} diff --git a/mkdocs/src/doc/docs/favicon.svg b/mkdocs/src/doc/docs/favicon.svg deleted file mode 100755 index 1fea0877..00000000 --- a/mkdocs/src/doc/docs/favicon.svg +++ /dev/null @@ -1,10 +0,0 @@ -<svg width="64" height="64" viewBox="0 0 64 64" fill="none" xmlns="http://www.w3.org/2000/svg"> - <path d="M64 64H0V0H64L31.3373 31.5369L64 64Z" fill="url(#paint0_radial)"/> - <defs> - <radialGradient id="paint0_radial" cx="0" cy="0" r="1" gradientUnits="userSpaceOnUse" gradientTransform="translate(61.8732 2.63097) scale(73.3111)"> - <stop offset="0.00343514" stop-color="#EF4857"/> - <stop offset="0.4689" stop-color="#D211EC"/> - <stop offset="1" stop-color="#7F52FF"/> - </radialGradient> - </defs> -</svg>
\ No newline at end of file diff --git a/mkdocs/src/doc/docs/index.md b/mkdocs/src/doc/docs/index.md deleted file mode 100644 index 2cedfe35..00000000 --- a/mkdocs/src/doc/docs/index.md +++ /dev/null @@ -1,9 +0,0 @@ -# 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/mkdocs/src/doc/docs/user_guide/output-formats/html.md b/mkdocs/src/doc/docs/user_guide/output-formats/html.md deleted file mode 100644 index e69de29b..00000000 --- a/mkdocs/src/doc/docs/user_guide/output-formats/html.md +++ /dev/null diff --git a/mkdocs/src/doc/mkdocs.yml b/mkdocs/src/doc/mkdocs.yml deleted file mode 100644 index 0b520944..00000000 --- a/mkdocs/src/doc/mkdocs.yml +++ /dev/null @@ -1,85 +0,0 @@ -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/mkdocs/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: 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/documentables.md - - Page & Content: developer_guide/architecture/data_model/page_content.md - - Extra properties: developer_guide/architecture/data_model/extra.md - - Extension points: - - Extension points: developer_guide/architecture/extension_points/introduction.md - - Core extension points: developer_guide/architecture/extension_points/core_extensions.md - - Base extensions: developer_guide/architecture/extension_points/base_extensions.md - - Plugin development: - - Plugin development: developer_guide/plugin-development/introduction.md - - Sample plugin tutorial: developer_guide/plugin-development/sample-plugin-tutorial.md - - Community: - - Slack: community/slack.md - -extra_css: - - dokka_colors.css |
