Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Revise developer guides documentation (#2523)
- Loading branch information
1 parent
3ee4fd8
commit 3934919
Showing
50 changed files
with
2,387 additions
and
559 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,4 @@ | ||
## Code of Conduct | ||
|
||
This project and the corresponding community is governed by the [JetBrains Open Source and Community Code of Conduct](https://confluence.jetbrains.com/display/ALL/JetBrains+Open+Source+and+Community+Code+of+Conduct). | ||
Please make sure you read it. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file was deleted.
Oops, something went wrong.
This file was deleted.
Oops, something went wrong.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,18 +1,160 @@ | ||
# Dokka community plugins | ||
|
||
Here is a list of plugins created by dokka team or community. | ||
On this page you can find `Dokka` plugins which are supported by both `Dokka` maintainers and community members. | ||
|
||
In order to add your plugin to this list it needs to be: | ||
If you want to add your plugin to this list, get in touch with maintainers via [Slack](../community/slack.md) | ||
or `GitHub`. | ||
|
||
* an open source project - sharing is caring so let others learn and improve your plugin | ||
* present in any public artefacts repository like bintray | ||
If you want to learn how to develop plugins for `Dokka`, see | ||
[Plugin development](../developer_guide/plugin-development/introduction.md) section. | ||
|
||
| Plugin name | Description | Source | | ||
| :--------- | :--------- | :------------ | | ||
| [Kotlin as Java](https://kotlin.github.io/dokka/1.7.0/user_guide/introduction/#plugins) | Display Kotlin code as seen from Java | [Github](https://github.com/Kotlin/dokka/tree/master/plugins/kotlin-as-java) | ||
| [GFM](https://kotlin.github.io/dokka/1.7.0/user_guide/introduction/#plugins) | Renders documentation in a GFM format | [Github](https://github.com/Kotlin/dokka/tree/master/plugins/gfm) | ||
| [Javadoc](https://kotlin.github.io/dokka/1.7.0/user_guide/introduction/#plugins) | Renders documentation in a Javadoc format | [Github](https://github.com/Kotlin/dokka/tree/master/plugins/javadoc) | ||
| [Jekyll](https://kotlin.github.io/dokka/1.7.0/user_guide/introduction/#plugins) | Renders documentation in a Jekyll format | [Github](https://github.com/Kotlin/dokka/tree/master/plugins/jekyll) | ||
| [Mermaid-HTML](https://mermaid-js.github.io/mermaid/#/) | Renders Mermaid graphs for HTML renderer. | [Github](https://github.com/glureau/dokka-mermaid) | ||
## Output Formats | ||
|
||
### Javadoc (Alpha) | ||
|
||
Javadoc plugin adds a `Javadoc` output format that looks like Java's `Javadoc`, but it's for the most part | ||
a lookalike, so you may experience problems if you try to use it with a tool that expects native | ||
`Javadoc` documentation generated by `Java`. | ||
|
||
`Javadoc` plugin does not support multiplatform projects and does not have a multi-module task. | ||
|
||
`Javadoc` plugin is shipped with `Dokka`, so you can start using it right away with one of the following tasks: | ||
|
||
* `dokkaJavadoc` - builds `Javadoc` documentation for single-module projects or for a specific module. | ||
* `dokkaJavadocCollector` - collects generated `Javadoc` documentation from submodules and assembles it together. | ||
|
||
`Javadoc` plugin has its own signature provider that essentially translates `Kotlin` signatures to `Java` ones. | ||
|
||
**This plugin is at its early stages**, so you may experience issues and encounter bugs. Feel free to | ||
[report](https://github.com/Kotlin/dokka/issues/new/choose) any errors you see. | ||
|
||
[Plugin source code on GitHub](https://github.com/Kotlin/dokka/tree/master/plugins/javadoc) | ||
|
||
### GFM (Alpha) | ||
|
||
`GFM` plugins adds the ability to generate documentation in `GitHub flavoured Markdown` format. Supports both | ||
multimodule and multiplatform projects, and is shipped together with `Dokka`, so you can start using it | ||
right away with one of the following tasks: | ||
|
||
* `dokkaGfm` - generate documentation for a non multi-module project or one specific module. | ||
* `dokkaGfmMultiModule` - generate documentation for a multi-module project, assemble it together and | ||
generate navigation page/menu for all the modules. | ||
|
||
Example: | ||
|
||
___ | ||
|
||
//[dokka-debug-kts](#gfm)/[org.jetbrains.dokka.test](#gfm)/[MyClass](#gfm) | ||
|
||
#### MyClass | ||
|
||
[jvm] | ||
class [MyClass](#gfm) | ||
|
||
KDoc that describes this class | ||
|
||
##### Constructors | ||
|
||
| | | | ||
|---|---| | ||
| [MyClass](#gfm) | [jvm]<br>fun [MyClass](#gfm)() | | ||
|
||
##### Functions | ||
|
||
| Name | Summary | | ||
|------------------|---| | ||
| [function](#gfm) | [jvm]<br>fun [function](#gfm)(): [String](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-string/index.html)<br>KDoc comment on top of this function | | ||
|
||
##### Properties | ||
|
||
| Name | Summary | | ||
|---|------------------------------------------------------------------------------------------------------------------------------------------------| | ||
| [property](#gfm) | [jvm]<br>val [property](#gfm): [String](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-string/index.html)<br>KDoc comment for a property | | ||
|
||
___ | ||
|
||
**This plugin is at its early stages**, so you may experience issues and encounter bugs. Feel free to | ||
[report](https://github.com/Kotlin/dokka/issues/new/choose) any errors you see. | ||
|
||
[Plugin source code on GitHub](https://github.com/Kotlin/dokka/tree/master/plugins/gfm) | ||
|
||
### Jekyll (Alpha) | ||
|
||
`Jekyll` plugins adds the ability to generate documentation in `Jekyll flavoured Markdown` format. Supports both | ||
multi-module and multiplatform projects, and is shipped together with `Dokka`, so you can start using it | ||
right away with one of the following tasks: | ||
|
||
* `dokkaJekyll` - generate documentation for a non multi-module project or one specific module. | ||
* `dokkaJekyllMultiModule` - generate documentation for a multi-module project, assemble it together and | ||
generate navigation page/menu for all the modules. | ||
|
||
**This plugin is at its early stages**, so you may experience issues and encounter bugs. Feel free to | ||
[report](https://github.com/Kotlin/dokka/issues/new/choose) any errors you see. | ||
|
||
[Plugin source code on GitHub](https://github.com/Kotlin/dokka/tree/master/plugins/jekyll) | ||
|
||
## Extensions | ||
|
||
### Mathjax | ||
|
||
[MathJax](https://docs.mathjax.org/) allows you to include mathematics in your web pages. `MathJax` plugin | ||
adds the ability to render mathematics from source code comments. | ||
|
||
If `MathJax` plugin encounters `@usesMathJax` `KDoc` tag, it adds `MathJax.js` (ver. 2) with `config=TeX-AMS_SVG` | ||
to generated `HTML` pages. | ||
|
||
Usage example: | ||
```kotlin | ||
/** | ||
* Some math \(\sqrt{3x-1}+(1+x)^2\) | ||
* | ||
* @usesMathJax | ||
*/ | ||
class Foo {} | ||
``` | ||
|
||
Which results in: | ||
|
||
![Mathjax demo](../images/mathjax_demo.png){ width="400" } | ||
|
||
[Plugin source code on GitHub](https://github.com/Kotlin/dokka/tree/master/plugins/mathjax) | ||
|
||
### Mermaid | ||
|
||
[Mermaid JS](https://mermaid-js.github.io/mermaid/#/) lets you create diagrams and visualizations using text and code. | ||
`Mermaid` plugin allows rendering such diagrams and visualizations found in source code documentation. | ||
|
||
Usage example: | ||
```kotlin | ||
/** | ||
* See the graph for more details: | ||
* \```mermaid | ||
* graph LR | ||
* A[Christmas] -->|Get money| B(Go shopping) | ||
* B --> C{Let me think} | ||
* C -->|One| D[Laptop] | ||
* C -->|Two| E[iPhone] | ||
* C -->|Three| F[fa:fa-car Car] | ||
* \``` | ||
*/ | ||
class CompositeSubscription | ||
``` | ||
|
||
Which results in: | ||
|
||
![Mermaid demo](../images/mermaid_demo.png){ width="700" } | ||
|
||
For more information and examples, see | ||
[Html Mermaid Dokka plugin](https://github.com/glureau/dokka-mermaid) repository on GitHub. | ||
|
||
### Kotlin as Java | ||
|
||
With `Kotlin as Java` plugin applied, all `Kotlin` signatures will be rendered as `Java` signatures. | ||
|
||
For instance, `fun foo(bar: Bar): Baz` will be rendered as `public final Baz foo(Bar bar)`. | ||
|
||
`Kotlin as Java` plugin is published to maven central as a | ||
[separate artifact](https://mvnrepository.com/artifact/org.jetbrains.dokka/kotlin-as-java-plugin): | ||
`org.jetbrains.dokka:kotlin-as-java-plugin:1.7.0`. | ||
|
||
[Plugin source code on GitHub](https://github.com/Kotlin/dokka/tree/master/plugins/kotlin-as-java) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,7 @@ | ||
# Slack channel | ||
|
||
`Dokka` has a dedicated `#dokka` channel in the `Kotlin Community Slack`, where you can ask questions and chat | ||
about using, customizing or contributing to `Dokka`. | ||
|
||
[Follow the instructions](https://surveys.jetbrains.com/s3/kotlin-slack-sign-up) | ||
to get an invite or [connect directly](https://kotlinlang.slack.com). |
123 changes: 123 additions & 0 deletions
123
docs/src/doc/docs/developer_guide/architecture/architecture_overview.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,123 @@ | ||
# Architecture overview | ||
|
||
Normally, you would think that a tool like `Dokka` simply parses some programming language sources and generates | ||
`HTML` pages for whatever it sees along the way, with little to no abstractions. That would be the simplest and | ||
shortest way to implement an API documentation engine. | ||
|
||
However, it was clear that `Dokka` may need to generate documentation from various sources (not only `Kotlin`), that users | ||
might request additional output formats (like `Markdown`), that users might need additional features like supporting | ||
custom `KDoc` tags or rendering `mermaid.js` diagrams - all these things would require changing a lot of code inside | ||
`Dokka` itself if all solutions were hardcoded. | ||
|
||
For this reason, `Dokka` was built from the ground up to be easily extensible and customizable by adding several layers | ||
of abstractions to the data model, and by providing pluggable extension points, giving you the ability to introduce | ||
selective changes on a single level. | ||
|
||
## Overview of data model | ||
|
||
Generating API documentation begins with `Input` source files (`.kts`, `.java`, etc) and ends with some `Output` files | ||
(`.html`/`.md` pages, etc). However, to allow for extensibility and customization, several input and output independent | ||
abstractions have been added to the data model. | ||
|
||
Below you can find the general pipeline of processing data gathered from sources and the explanation for each stage. | ||
|
||
```mermaid | ||
flowchart TD | ||
Input --> Documentables --> Pages --> Output | ||
``` | ||
|
||
* `Input` - generalization of sources, by default `Kotlin`/`Java` sources, but could be virtually anything | ||
* `Documentables` - unified data model that represents _any_ parsed sources as a tree, independent of the source | ||
language. Examples of a `Documentable`: class, function, package, property, etc | ||
* `Pages` - universal model that represents output pages (e.g a function/property page) and the content it's composed of | ||
(lists, text, code blocks) that the users needs to see. Not to be confused with `.html` pages. Goes hand in hand | ||
with so-called `Content` model. | ||
* `Output` - specific output format like `HTML`/`Markdown`/`Javadoc`/etc. This is a mapping of pages/content model to | ||
some human-readable and visual representation. For instance: | ||
* `PageNode` is mapped as | ||
* `.html` file for `HTML` format | ||
* `.md` file for `Markdown` format | ||
* `ContentList` is mapped as | ||
* `<li>` / `<ul>` for `HTML` format | ||
* `1.` / `*` for `Markdown` format | ||
* `ContentCodeBlock` is mapped as | ||
* `<code>` or `<pre>` with some CSS styles in `HTML` format | ||
* Text wrapped in triple backticks for `Markdown` format | ||
|
||
|
||
You, as a `Dokka` developer or a plugin writer, can use extension points to introduce selective changes to the | ||
model on one particular level without touching everything else. | ||
|
||
For instance, if you wanted to make some annotation/function/class invisible in the final documentation, you would only | ||
need to modify the `Documentables` model by filtering undesirable members out. If you wanted to display all overloaded | ||
methods on the same page instead of on separate ones, you would only need to modify the `Page` model by merging multiple | ||
pages into one, and so on. | ||
|
||
For a deeper dive into Dokka's model with more examples and details, | ||
see sections about [Documentables](data_model/documentables.md) and [Page/Content](data_model/page_content.md) | ||
|
||
For an overview of existing extension points that let you transform Dokka's models, see | ||
[Core extension points](extension_points/core_extensions.md) and [Base extensions](extension_points/base_extensions.md). | ||
|
||
## Overview of extension points | ||
|
||
An extension point usually represents some pluggable interface that performs an action during one of the stages of | ||
generating documentation. An extension is therefore an implementation of that interface which is extending the | ||
extension point. | ||
|
||
You can create extension points, provide your own implementations (extensions) and configure them. All of | ||
this is possible with Dokka's plugin/extension point API. | ||
|
||
Here's a sneak peek of the DSL: | ||
|
||
```kotlin | ||
class MyPlugin : DokkaPlugin() { | ||
// create an extension point for other developers | ||
val signatureProvider by extensionPoint<SignatureProvider>() | ||
|
||
// provide a default implementation | ||
val defaultSignatureProvider by extending { | ||
signatureProvider with KotlinSignatureProvider() | ||
} | ||
|
||
// register our own extension in base plugin and override its default | ||
val dokkaBasePlugin by lazy { plugin<DokkaBase>() } | ||
val multimoduleLocationProvider by extending { | ||
(dokkaBasePlugin.locationProviderFactory | ||
providing MultimoduleLocationProvider::Factory | ||
override dokkaBasePlugin.locationProvider) | ||
} | ||
} | ||
|
||
// use a registered extention, pretty much dependency injection | ||
class MyExtension(val context: DokkaContext) { | ||
|
||
val signatureProvider: SignatureProvider = context.plugin<MyPlugin>().querySingle { signatureProvider } | ||
|
||
fun doSomething() { | ||
signatureProvider.signature(..) | ||
} | ||
} | ||
|
||
interface SignatureProvider { | ||
fun signature(documentable: Documentable): List<ContentNode> | ||
} | ||
|
||
class KotlinSignatureProvider : SignatureProvider { | ||
override fun signature(documentable: Documentable): List<ContentNode> = listOf() | ||
} | ||
``` | ||
|
||
For a deeper dive into extensions and extension points with more examples and details, see | ||
[Introduction to Extensions](extension_points/introduction.md). | ||
|
||
For an overview of existing extension points, see [Core extension points](extension_points/core_extensions.md) and | ||
[Base extensions](extension_points/base_extensions.md). | ||
|
||
## Historical context | ||
|
||
This is a second iteration of Dokka that was built from scratch. | ||
|
||
If you want to learn more about why Dokka has been designed this way, watch this great talk by Paweł Marks: | ||
[New Dokka - Designed for Fearless Creativity](https://www.youtube.com/watch?v=OvFoTRhqaKg). The general principles | ||
and general architecture are the same, although it may be outdated in some areas, so please double-check. |
Oops, something went wrong.