Create documentation for versioning (#1748)

* Create documentation for versioning

* Create documentation for versioning

2 files changed, 71 insertions, 0 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