diff options
| -rw-r--r-- | docs/src/doc/docs/user_guide/versioning/versioning.md | 70 | ||||
| -rw-r--r-- | docs/src/doc/mkdocs.yml | 1 | ||||
| -rw-r--r-- | plugins/versioning/src/main/kotlin/versioning/VersioningConfiguration.kt | 2 |
3 files changed, 72 insertions, 1 deletions
diff --git a/docs/src/doc/docs/user_guide/versioning/versioning.md b/docs/src/doc/docs/user_guide/versioning/versioning.md new file mode 100644 index 00000000..fac6b005 --- /dev/null +++ b/docs/src/doc/docs/user_guide/versioning/versioning.md @@ -0,0 +1,70 @@ +# 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 plugin is applied by default but not enabled in Dokka so there is no need to apply it manually. + +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. +* 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. + +Above configuration should be placed under the `pluginsConfiguration` block specific for your build tool. +Configuration object is named `org.jetbrains.dokka.versioning.VersioningConfiguration`. + + +!!! note + In the current release versioning is available only for the multimodule. Supporting single module is scheduled for next release + +### Directory structure required + +Versioning plugins requires documentation authors to keep previous outputs in a set structure: + +``` +. +└── 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. + +### 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 [gradle documentation](../gradle/usage.md#applying-plugins) for more information about configuring Dokka with this build tool. diff --git a/docs/src/doc/mkdocs.yml b/docs/src/doc/mkdocs.yml index ac962baa..0e4794ba 100644 --- a/docs/src/doc/mkdocs.yml +++ b/docs/src/doc/mkdocs.yml @@ -50,6 +50,7 @@ nav: - Maven: user_guide/maven/usage.md - Command line: user_guide/cli/usage.md - Html frontend: user_guide/base-specific/frontend.md + - Versioning: user_guide/versioning/versioning.md - Android plugin: user_guide/android-plugin/android-plugin.md - Plugin development: - Introduction: developer_guide/introduction.md diff --git a/plugins/versioning/src/main/kotlin/versioning/VersioningConfiguration.kt b/plugins/versioning/src/main/kotlin/versioning/VersioningConfiguration.kt index 98eef33d..e01f3419 100644 --- a/plugins/versioning/src/main/kotlin/versioning/VersioningConfiguration.kt +++ b/plugins/versioning/src/main/kotlin/versioning/VersioningConfiguration.kt @@ -9,7 +9,7 @@ data class VersioningConfiguration( var versionsOrdering: List<String>? = defaultVersionsOrdering, var version: String? = defaultVersion, ) : ConfigurableBlock { - fun versionFromConfigurationOrModule(dokkaContext: DokkaContext): String = + internal fun versionFromConfigurationOrModule(dokkaContext: DokkaContext): String = version ?: dokkaContext.configuration.moduleVersion ?: "1.0" companion object { |