diff options
Diffstat (limited to 'plugins')
| -rw-r--r-- | plugins/README.md | 14 | ||||
| -rw-r--r-- | plugins/all-modules-page/README.md | 7 | ||||
| -rw-r--r-- | plugins/android-documentation/README.md | 10 | ||||
| -rw-r--r-- | plugins/base/README.md | 21 | ||||
| -rw-r--r-- | plugins/gfm/README.md | 17 | ||||
| -rw-r--r-- | plugins/javadoc/README.md | 19 | ||||
| -rw-r--r-- | plugins/jekyll/README.md | 17 | ||||
| -rw-r--r-- | plugins/kotlin-as-java/README.md | 15 | ||||
| -rw-r--r-- | plugins/mathjax/README.md | 27 | ||||
| -rw-r--r-- | plugins/templating/README.md | 4 | ||||
| -rw-r--r-- | plugins/versioning/README.md | 332 | ||||
| -rw-r--r-- | plugins/versioning/versioning-plugin-example.png | bin | 0 -> 43684 bytes |
12 files changed, 483 insertions, 0 deletions
diff --git a/plugins/README.md b/plugins/README.md new file mode 100644 index 00000000..00e0396f --- /dev/null +++ b/plugins/README.md @@ -0,0 +1,14 @@ +# Dokka plugins + +| Plugin project | Description | +|------------------------------------------------|-----------------------------------------------------------------------------------------------| +| [all-modules-page](all-modules-page) | Provides the ability to generate multi-module documentation. | +| [android-documentation](android-documentation) | Improves documentation experience on the Android platform. | +| [base](base) | Includes base Dokka features and extensions, along with the built-in HTML format | +| [gfm](gfm) | Provides the ability to generate documentation in `GitHub Flavoured Markdown` format. | +| [javadoc](javadoc) | Provides the ability to generate documentation in Javadoc format. | +| [jekyll](jekyll) | Provides the ability to generate documentation in `Jekyll Flavoured Markdown` format. | +| [kotlin-as-java](kotlin-as-java) | Renders all Kotlin signatures as Java signatures. | +| [mathjax](mathjax) | Allows rendering mathematics in the web pages. | +| [templating](templating) | An internal Dokka plugin that handles HTML template processing. | +| [versioning](versioning) | Provides the ability to host documentation for multiple versions of your library/application. | diff --git a/plugins/all-modules-page/README.md b/plugins/all-modules-page/README.md new file mode 100644 index 00000000..2524b5eb --- /dev/null +++ b/plugins/all-modules-page/README.md @@ -0,0 +1,7 @@ +# All Modules plugin + +Thge All Modules plugin is used for documenting multi-module projects. It creates a common table of contents +for all submodules and helps resolve cross-module links and resource locations. + +You can find the All Modules plugin on +[Maven Central](https://mvnrepository.com/artifact/org.jetbrains.dokka/all-modules-page-plugin). diff --git a/plugins/android-documentation/README.md b/plugins/android-documentation/README.md new file mode 100644 index 00000000..2928f180 --- /dev/null +++ b/plugins/android-documentation/README.md @@ -0,0 +1,10 @@ +# Android documentation plugin + +The Android documentation plugin aim to improve documentation experience on the Android platform. + +Features: + +* Support for the `@hide` KDoc tag. It hides marked declaration from being displayed in documentation. + +You can find the Android documentation plugin on +[Maven Central](https://mvnrepository.com/artifact/org.jetbrains.dokka/android-documentation-plugin). diff --git a/plugins/base/README.md b/plugins/base/README.md new file mode 100644 index 00000000..e4cba717 --- /dev/null +++ b/plugins/base/README.md @@ -0,0 +1,21 @@ +# Base plugin + +The Base plugin comes with a number of basic extensions and features that are likely to be needed by any output format and +some plugins in general. + +Including, but not limited to: + +* Markdown and KDoc parsing. +* Kotlin signature generation. +* Transformers that suppress empty modules/packages, unwanted visibility modifiers, obvious functions + (hashCode/equals/etc), and so on. +* Declaration link resolution (i.e linking to a class in a KDoc). +* Support for external documentation links (i.e links to Java's Javadocs website or Kotlin's stdlib). +* Declaration source link generation for navigation to source code (a.k.a `source` button). +* Multiplatform support. +* Output file writers. + +The Base plugin is not intended to be used directly by those who want to generate documentation - it is a building block +for other plugins and formats. + +It is in the heart of all documentation formats that come with Dokka. diff --git a/plugins/gfm/README.md b/plugins/gfm/README.md new file mode 100644 index 00000000..1d65c0f0 --- /dev/null +++ b/plugins/gfm/README.md @@ -0,0 +1,17 @@ +# GFM plugin + +The GFM plugin adds the ability to generate documentation in `GitHub Flavoured Markdown` format. It supports both +multi-module and multiplatform projects. + +The GFM plugin is shipped together with the Dokka Gradle Plugin, so you can start using it +right away with one of the following tasks: + +* `dokkaGfm` - generate documentation for a single-project build or one specific module. +* `dokkaGfmMultiModule` - generate documentation for a multi-module project, assemble it together and + generate navigation page/menu for all the modules. + +To use it with Maven or the CLI runner, you have to add it as a dependency. You can find it on +[Maven Central](https://mvnrepository.com/artifact/org.jetbrains.dokka/gfm-plugin) + +GFM plugin comes built in with the Dokka Gradle plugin. You can also find it on +[Maven Central](https://mvnrepository.com/artifact/org.jetbrains.dokka/gfm-plugin). diff --git a/plugins/javadoc/README.md b/plugins/javadoc/README.md new file mode 100644 index 00000000..aaa1f272 --- /dev/null +++ b/plugins/javadoc/README.md @@ -0,0 +1,19 @@ +# Javadoc plugin + +The Javadoc plugin adds a Javadoc output format that looks like Java's Javadoc HTML, 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. + +The Javadoc plugin is shipped with the Dokka Gradle Plugin, so you can start using it right away with one of the following +tasks: + +* `dokkaJavadoc` - builds Javadoc documentation for single-project builds or for a specific module. +* `dokkaJavadocCollector` - collects generated Javadoc documentation from submodules and assembles it together. + +The Javadoc plugin has its own signature provider that essentially translates Kotlin signatures to Java ones. + +To use it with Maven or the CLI runner, you have to add it as a dependency. You can find it on +[Maven Central](https://mvnrepository.com/artifact/org.jetbrains.dokka/javadoc-plugin). + +**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. diff --git a/plugins/jekyll/README.md b/plugins/jekyll/README.md new file mode 100644 index 00000000..15ad9071 --- /dev/null +++ b/plugins/jekyll/README.md @@ -0,0 +1,17 @@ +# Jekyll plugin + +The Jekyll plugin adds the ability to generate documentation in `Jekyll Flavoured Markdown` format. It supports both +multi-module and multiplatform projects. + +The Jekyll plugin is shipped together with the Dokka Gradle Plugin, so you can start using it +right away with one of the following tasks: + +* `dokkaJekyll` - generate documentation for a single-project build or one specific module. +* `dokkaJekyllMultiModule` - generate documentation for a multi-module project, assemble it together and + generate navigation page/menu for all the modules. + +To use it with Maven or CLI runners, you have to add it as a dependency. You can find it on +[Maven Central](https://mvnrepository.com/artifact/org.jetbrains.dokka/jekyll-plugin) + +**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. diff --git a/plugins/kotlin-as-java/README.md b/plugins/kotlin-as-java/README.md new file mode 100644 index 00000000..0098e1c7 --- /dev/null +++ b/plugins/kotlin-as-java/README.md @@ -0,0 +1,15 @@ +# Kotlin as Java plugin + +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)`. + +The Kotlin as Java plugin is published to maven central as a +[separate artifact](https://mvnrepository.com/artifact/org.jetbrains.dokka/kotlin-as-java-plugin): + +```text +org.jetbrains.dokka:kotlin-as-java-plugin:1.7.20 +``` + +**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. diff --git a/plugins/mathjax/README.md b/plugins/mathjax/README.md new file mode 100644 index 00000000..43d07c93 --- /dev/null +++ b/plugins/mathjax/README.md @@ -0,0 +1,27 @@ +# MathJax plugin + +[MathJax](https://docs.mathjax.org/) allows you to include mathematics in your web pages. The `mathjax` Dokka plugin +adds the ability to render mathematics found in source code comments. + +If MathJax plugin encounters the `@usesMathJax` KDoc tag, it adds `MathJax.js` (ver. 2) with `config=TeX-AMS_SVG` +to the generated HTML pages. + +Usage example: + +```kotlin +/** + * Some math \(\sqrt{3x-1}+(1+x)^2\) + * + * @usesMathJax + */ +class Foo {} +``` + +Note that the `@usesMathJax` tag is case-sensitive. + +The MathJax plugin is published to Maven Central as a +[separate artifact](https://mvnrepository.com/artifact/org.jetbrains.dokka/mathjax-plugin): + +```text +org.jetbrains.dokka:mathjax-plugin:1.7.20 +``` diff --git a/plugins/templating/README.md b/plugins/templating/README.md new file mode 100644 index 00000000..92eee3e2 --- /dev/null +++ b/plugins/templating/README.md @@ -0,0 +1,4 @@ +# Templating plugin + +Templating plugin is used internally by Dokka and HTML format in particular to help handle substitution +commands, resolve relative links and process templates. diff --git a/plugins/versioning/README.md b/plugins/versioning/README.md new file mode 100644 index 00000000..819ecf51 --- /dev/null +++ b/plugins/versioning/README.md @@ -0,0 +1,332 @@ +# Versioning plugin + +The versioning plugin provides the ability to host documentation for multiple versions of your library/application +with seamless switching between them. This, in turn, provides a better experience for your users. + + + +**Note:** The versioning plugin only works with Dokka's HTML format. + +Visit the [versioning plugin example project](../../examples/gradle/dokka-versioning-multimodule-example) +to see an example of it in action and how it can be configured. + +## Applying the plugin + +You can apply the versioning plugin the same way as other Dokka plugins: + +<details open> +<summary>Kotlin</summary> + +```kotlin +dependencies { + dokkaHtmlPlugin("org.jetbrains.dokka:versioning-plugin:1.7.20") +} +``` + +**Note:** When documenting multi-project builds, you need to apply the versioning +plugin within subprojects as well as in their parent project. + +</details> + +<details> +<summary>Groovy</summary> + +```groovy +dependencies { + dokkaHtmlPlugin 'org.jetbrains.dokka:versioning-plugin:1.7.20' +} +``` + +**Note:** When documenting multi-project builds, you need to apply the versioning +plugin within subprojects as well as in their parent project. + +</details> + +<details> +<summary>Maven</summary> + +```xml +<plugin> + <groupId>org.jetbrains.dokka</groupId> + <artifactId>dokka-maven-plugin</artifactId> + ... + <configuration> + <dokkaPlugins> + <plugin> + <groupId>org.jetbrains.dokka</groupId> + <artifactId>versioning-plugin</artifactId> + <version>1.7.20</version> + </plugin> + </dokkaPlugins> + </configuration> +</plugin> +``` + +</details> + +<details> +<summary>CLI</summary> + +You can find the versioning plugin's artifact on +[mvnrepository](https://mvnrepository.com/artifact/org.jetbrains.dokka/versioning-plugin/1.7.20) or by browsing +[maven central repository](https://repo1.maven.org/maven2/org/jetbrains/dokka/versioning-plugin/1.7.20) +directly, and pass it to `pluginsClasspath`. + +Via command line arguments: + +```Bash +java -jar dokka-cli-1.7.20.jar \ + -pluginsClasspath "./dokka-base-1.7.20.jar;...;./versioning-plugin-1.7.20.jar" \ + ... +``` + +Via JSON configuration: + +```json +{ + ... + "pluginsClasspath": [ + "./dokka-base-1.7.20.jar", + "...", + "./versioning-plugin-1.7.20.jar" + ], + ... +} +``` + +</details> + +## Configuration + +### Configuration options + +The table below contains all the possible configuration options for the versioning plugin and their purpose. + +| **Option** | **Description** | +|--------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `version` | The version of your application/library that documentation is going to be generated for. This will be the version shown in the dropdown menu. | +| `versionsOrdering` | An optional list of strings that represents the order that versions should appear in the dropdown menu. Must match `version` string exactly. The first item in the list is at the top of the dropdown. | +| `olderVersionsDir` | An optional path to a parent folder that contains other documentation versions. It requires a specific directory structure. For more information, see [Directory structure](#directory-structure). | +| `olderVersions` | An optional list of paths to other documentation versions. It must point to Dokka's outputs directly. This is useful if different versions can't all be in the same directory. | +| `renderVersionsNavigationOnAllPages` | An optional boolean value indicating whether to render the navigation dropdown on all pages. Set to true by default. | + +#### Directory structure + +Note that the directory passed to `olderVersionsDir` needs to follow a specific structure: + +```text +. +└── olderVersionsDir + └── 1.7.10 + ├── <dokka output> + └── 1.7.20 + ├── <dokka output> +... +``` + +### Configuration example + +<details open> +<summary>Kotlin</summary> + +```kotlin +import org.jetbrains.dokka.versioning.VersioningPlugin +import org.jetbrains.dokka.versioning.VersioningConfiguration + +buildscript { + dependencies { + classpath("org.jetbrains.dokka:versioning-plugin:1.7.20") + } +} + +tasks.dokkaHtml { + pluginConfiguration<VersioningPlugin, VersioningConfiguration> { + version = "1.5" + versionsOrdering = listOf("1.5", "1.4", "1.3", "1.2", "1.1", "alpha-2", "alpha-1") + olderVersionsDir = file("documentation/version") + olderVersions = listOf(file("documentation/alpha/alpha-2"), file("documentation/alpha/alpha-1")) + renderVersionsNavigationOnAllPages = true + } +} +``` + +Alternatively, you can configure it via JSON: + +```kotlin + val versioningConfiguration = """ + { + "version": "1.5", + "versionsOrdering": ["1.5", "1.4", "1.3", "1.2", "1.1", "alpha-2", "alpha-1"], + "olderVersionsDir": "documentation/version", + "olderVersions": ["documentation/alpha/alpha-2", "documentation/alpha/alpha-1"], + "renderVersionsNavigationOnAllPages": true + } + """ + pluginsMapConfiguration.set( + mapOf( + "org.jetbrains.dokka.versioning.VersioningPlugin" to versioningConfiguration + ) + ) +``` + +</details> + +<details> +<summary>Groovy</summary> + +```groovy +dokkaHtml { + String versioningConfiguration = """ + { + "version": "1.5", + "versionsOrdering": ["1.5", "1.4", "1.3", "1.2", "1.1", "alpha-2", "alpha-1"], + "olderVersionsDir": "documentation/version", + "olderVersions": ["documentation/alpha/alpha-2", "documentation/alpha/alpha-1"], + "renderVersionsNavigationOnAllPages": true + } + """ + pluginsMapConfiguration.set( + ["org.jetbrains.dokka.versioning.VersioningPlugin": versioningConfiguration] + ) +} +``` + +</details> + +<details> +<summary>Maven</summary> + +```xml +<plugin> + <groupId>org.jetbrains.dokka</groupId> + <artifactId>dokka-maven-plugin</artifactId> + ... + <configuration> + <pluginsConfiguration> + <org.jetbrains.dokka.versioning.VersioningPlugin> + <version>1.5</version> + <versionsOrdering> + <version>1.5</version> + <version>1.4</version> + <version>1.3</version> + <version>1.2</version> + <version>1.1</version> + <version>alpha-2</version> + <version>alpha-1</version> + </versionsOrdering> + <olderVersionsDir>${project.basedir}/documentation/version</olderVersionsDir> + <olderVersions> + <version>${project.basedir}/documentation/alpha/alpha-2</version> + <version>${project.basedir}/documentation/alpha/alpha-1</version> + </olderVersions> + <renderVersionsNavigationOnAllPages>true</renderVersionsNavigationOnAllPages> + </org.jetbrains.dokka.versioning.VersioningPlugin> + </pluginsConfiguration> + </configuration> +</plugin> +``` + +</details> + +<details> +<summary>CLI</summary> + +```Bash +java -jar dokka-cli-1.7.20.jar \ + ... + -pluginsConfiguration "org.jetbrains.dokka.versioning.VersioningPlugin={\"version\": \"1.5\", \"versionsOrdering\": [\"1.5\", \"1.4\", \"1.3\", \"1.2\", \"1.1\", \"alpha-2\", \"alpha-1\"], \"olderVersionsDir\": \"documentation/version\", \"olderVersions\": [\"documentation/alpha/alpha-2\", \"documentation/alpha/alpha-1\"], \"renderVersionsNavigationOnAllPages\": true}" + +``` + +Alternatively, via JSON configuration: +```json +{ + "moduleName": "Dokka Example", + ... + "pluginsConfiguration": [ + { + "fqPluginName": "org.jetbrains.dokka.versioning.VersioningPlugin", + "serializationFormat": "JSON", + "values": "{\"version\": \"1.5\", \"versionsOrdering\": [\"1.5\", \"1.4\", \"1.3\", \"1.2\", \"1.1\", \"alpha-2\", \"alpha-1\"], \"olderVersionsDir\": \"documentation/version\", \"olderVersions\": [\"documentation/alpha/alpha-2\", \"documentation/alpha/alpha-1\"], \"renderVersionsNavigationOnAllPages\": true}" + } + ] +} +``` + +</details> + +## Generating versioned documentation + +With the versioning plugin applied and configured, no other steps are needed. Documentation can be built in the usual way. + +Among other things, the versioning plugin adds a `version.json` file to the output folder. This file is used by the +plugin to match versions and generate version navigation. If your previously generated documentation does not have that +file, you will need to re-generate documentation for such versions. Just adding the file will not work. + +The versioning plugin also bundles all other documentation versions that have been passed through `olderVersionsDir` +and `olderVersions` configuration options by putting them inside the `older` directory. + +## Usage example + +There is no single correct way to configure the plugin, it can be tailored to your needs. However, +it can be a bit overwhelming when starting out. Below you will find one of the ways it can be configured so that you +can begin publishing versioned documentation straight away. + +The main idea behind it is the following: + +1. One directory contains all versions of your documentation. For example, `documentation/version/{doc_version}`. + This is your archive which is needed for future builds. +2. The output directory of all new builds is set to that directory as well, under `documentation/version/{new_version}`. +3. When new builds are executed, the plugin looks for previous versions of documentation in the archive directory. +4. Once new documentation has been generated, it needs to be **copied** to somewhere accessible by the user. + For example, GitHub pages or nginx static directories. It needs to be **copied**, not moved because Dokka will still + need this version for future builds, otherwise there will be a gap in the archive. +5. Once it has been safely copied, you can remove the `older` directory from the newly generated and archived version. + This helps reduce the overhead of each version bundling all previous versions, as these files are effectively duplicates. + +```kotlin +import org.jetbrains.dokka.versioning.VersioningPlugin +import org.jetbrains.dokka.versioning.VersioningConfiguration + +buildscript { + dependencies { + classpath("org.jetbrains.dokka:versioning-plugin:1.7.20") + } +} + +dependencies { + dokkaPlugin("org.jetbrains.dokka:versioning-plugin:1.7.20") +} + +tasks.dokkaHtml { + // This can be any persistent folder where + // you store documentation by version + val docVersionsDir = projectDir.resolve("documentation/version") + + // The version for which you are currently generating docs + val currentVersion = "1.3" + + // Set the output to a folder with all other versions + // as you'll need the current version for future builds + val currentDocsDir = docVersionsDir.resolve(currentVersion) + outputDirectory.set(currentDocsDir) + + pluginConfiguration<VersioningPlugin, VersioningConfiguration> { + olderVersionsDir = docVersionsDir + version = currentVersion + } + + doLast { + // This folder contains the latest documentation with all + // previous versions included, so it's ready to be published. + // Make sure it's copied and not moved - you'll still need this + // version for future builds + currentDocsDir.copyTo(file("/my/hosting")) + + // Only once current documentation has been safely moved, + // remove previous versions bundled in it. They will not + // be needed in future builds, it's just overhead. + currentDocsDir.resolve("older").deleteRecursively() + } +} +``` diff --git a/plugins/versioning/versioning-plugin-example.png b/plugins/versioning/versioning-plugin-example.png Binary files differnew file mode 100644 index 00000000..cd02c558 --- /dev/null +++ b/plugins/versioning/versioning-plugin-example.png |
