blob: 876ec436ed4100173c68dd8a523ec05423ca8a75 (
plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
|
# Versioning plugin
Versioning plugin aims to provide users with ability to create a versioned documentation.
Therefore, users of the documentation can view different versions of the documentation by going to the main page and change versions.
Versioning can be configured using:
* version - a string value representing a version that should be displayed in the dropdown.
* olderVersionsDir - an optional file that represents the parent directory containing folders with previous Dokka outputs.
* olderVersions - an optional list of directories, each containing a previous Dokka output. Used after the contents of
`olderVersionsDir`
(if it's specified).
* versionsOrdering - an optional list of strings representing the ordering of versions that should be visible.
By default, Dokka will try to use semantic versioning to create such ordering.
* renderVersionsNavigationOnAllPages - a bool value.
By default, Dokka renders a versions navigation on all pages.
!!! note
You should enable the plugin in all submodules to render a versions navigation on all pages.
Above configuration should be placed under the `pluginsConfiguration` block specific for your build tool.
Configuration object is named `org.jetbrains.dokka.versioning.VersioningConfiguration`.
### Directory structure required
If you pass previous versions using `olderVersionsDir`, a particular directory structure is required:
```
.
└── older_versions_dir
└── 1.4.10
├── <dokka output>
└── 1.4.20
├── <dokka output>
...
```
As can be seen on the diagram, `olderVersionsDir` should be a parent directory of previous output directories.
This can be avoided by manually specifying each past output directory with `olderVersions`, or they can be used
together.
`olderVersions` directories need to contain a past Dokka output. For the above example, you would pass
`older_versions_dir/1.4.10, older_versions_dir/1.4.20`.
!!! note
The previously documentations should be generated with the versioning plugin.
### Example
Versioning plugin in gradle can be configured in 2 ways:
* by manually adding the versioning plugin to classpath and using `pluginsConfiguration`
* by using `pluginsMapConfiguration` and adding the configuration serialized as json under the `org.jetbrains.dokka.versioning.VersioningPlugin` key.
If you choose the first method the configuration may look like this:
```kotlin
buildscript {
dependencies {
classpath("org.jetbrains.dokka:versioning-plugin:<dokka_version>")
}
}
...
pluginConfiguration<org.jetbrains.dokka.versioning.VersioningPlugin, org.jetbrains.dokka.versioning.VersioningConfiguration> {
version = "1.0"
olderVersionsDir = projectDir.resolve("olderVersionsDir")
}
```
Alternatively, without adding plugin to classpath:
```kotlin
pluginsMapConfiguration.set(mapOf("org.jetbrains.dokka.versioning.VersioningPlugin" to """{ "version": "1.0" }"""))
```
Please consult the [Gradle documentation](../applying/gradle.md#applying-plugins) for more information about configuring Dokka with this build tool.
Please see the [Dokka Gradle versioning multi modules example project](https://github.com/Kotlin/dokka/tree/master/examples/gradle/dokka-versioning-multimodule-example).
Also see the [generated documentation](https://Kotlin.github.io/dokka/examples/dokka-versioning-multimodule-example/htmlMultiModule).
|
