Improve versioning plugin (#2104)

- support for single module projects
- version navigator is on all pages
- dropdown arrow for version navigator

core/api/core.api

@@ -16,6 +16,7 @@ public final class org/jetbrains/dokka/CoreExtensions {
 	public final fun getDocumentableTransformer ()Lorg/jetbrains/dokka/plugability/ExtensionPoint;
 	public final fun getGeneration ()Lorg/jetbrains/dokka/plugability/ExtensionPoint;
 	public final fun getPageTransformer ()Lorg/jetbrains/dokka/plugability/ExtensionPoint;
+	public final fun getPostActions ()Lorg/jetbrains/dokka/plugability/ExtensionPoint;
 	public final fun getPreGenerationCheck ()Lorg/jetbrains/dokka/plugability/ExtensionPoint;
 	public final fun getRenderer ()Lorg/jetbrains/dokka/plugability/ExtensionPoint;
 	public final fun getSourceToDocumentableTranslator ()Lorg/jetbrains/dokka/plugability/ExtensionPoint;
@@ -4288,6 +4289,9 @@ public abstract interface class org/jetbrains/dokka/plugability/WithUnsafeExtens
 	public abstract fun getExtensionsSuppressed ()Ljava/util/List;
 }
 
+public abstract interface class org/jetbrains/dokka/renderers/PostAction : kotlin/jvm/functions/Function0 {
+}
+
 public abstract interface class org/jetbrains/dokka/renderers/Renderer {
 	public abstract fun render (Lorg/jetbrains/dokka/pages/RootPageNode;)V
 }

core/src/main/kotlin/CoreExtensions.kt

@@ -2,6 +2,7 @@ package org.jetbrains.dokka
 
 import org.jetbrains.dokka.generation.Generation
 import org.jetbrains.dokka.plugability.*
+import org.jetbrains.dokka.renderers.PostAction
 import org.jetbrains.dokka.renderers.Renderer
 import org.jetbrains.dokka.transformers.documentation.DocumentableMerger
 import org.jetbrains.dokka.transformers.documentation.DocumentableToPageTranslator
@@ -21,6 +22,7 @@ object CoreExtensions {
     val documentableToPageTranslator by coreExtensionPoint<DocumentableToPageTranslator>()
     val pageTransformer by coreExtensionPoint<PageTransformer>()
     val renderer by coreExtensionPoint<Renderer>()
+    val postActions by coreExtensionPoint<PostAction>()
 
     private fun <T : Any> coreExtensionPoint() = object {
         operator fun provideDelegate(thisRef: CoreExtensions, property: KProperty<*>): Lazy<ExtensionPoint<T>> =

core/src/main/kotlin/renderers/PostAction.kt

@@ -0,0 +1,3 @@
+package org.jetbrains.dokka.renderers
+
+interface PostAction : () -> Unit

docs/src/doc/docs/user_guide/versioning/versioning.md

@@ -3,8 +3,6 @@
 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.
@@ -14,14 +12,16 @@ Versioning can be configured using:
   (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`.
 
 
-!!! note
-    In the current release versioning is available only for the multimodule. Supporting single module is scheduled for next release
-
 ### Directory structure required
 
 If you pass previous versions using `olderVersionsDir`, a particular directory structure is required:

integration-tests/gradle/projects/it-multimodule-versioning-0/build.gradle

@@ -9,6 +9,7 @@ apply from: '../template.root.gradle.kts'
 
 dependencies {
     implementation "org.jetbrains.kotlin:kotlin-stdlib"
+    dokkaPlugin "org.jetbrains.dokka:versioning-plugin:${System.getenv("DOKKA_VERSION")}"
 }
 
 
@@ -24,6 +25,7 @@ dokkaHtmlMultiModule {
 tasks.register('dokkaHtmlMultiModuleBaseVersion', DokkaMultiModuleTask){
     dependencies {
         dokkaPlugin("org.jetbrains.dokka:all-modules-page-plugin:${System.getenv("DOKKA_VERSION")}")
+        dokkaPlugin("org.jetbrains.dokka:versioning-plugin:${System.getenv("DOKKA_VERSION")}")
     }
     outputDirectory.set(file(projectDir.toPath().resolve("dokkas").resolve("1.0")))
     pluginsMapConfiguration.set(["org.jetbrains.dokka.versioning.VersioningPlugin": """{ "version": "1.0" }"""])
@@ -33,6 +35,7 @@ tasks.register('dokkaHtmlMultiModuleBaseVersion', DokkaMultiModuleTask){
 tasks.register('dokkaHtmlMultiModuleNextVersion', DokkaMultiModuleTask){
     dependencies {
         dokkaPlugin("org.jetbrains.dokka:all-modules-page-plugin:${System.getenv("DOKKA_VERSION")}")
+        dokkaPlugin("org.jetbrains.dokka:versioning-plugin:${System.getenv("DOKKA_VERSION")}")
     }
     outputDirectory.set(file(projectDir.toPath().resolve("dokkas").resolve("1.1")))
     pluginsMapConfiguration.set(["org.jetbrains.dokka.versioning.VersioningPlugin": """{ "version": "1.1", "olderVersionsDir": "$projectDir/dokkas" }"""])

plugins/all-modules-page/api/all-modules-page.api

@@ -4,10 +4,10 @@ public final class org/jetbrains/dokka/allModulesPage/AllModulesPageGeneration :
 	public final fun finishProcessingSubmodules ()V
 	public fun generate (Lorg/jetbrains/dokka/Timer;)V
 	public fun getGenerationName ()Ljava/lang/String;
-	public final fun handlePreviousDocs ()V
 	public final fun processMultiModule (Lorg/jetbrains/dokka/pages/RootPageNode;)V
 	public final fun processSubmodules ()Lorg/jetbrains/dokka/allModulesPage/AllModulesPageGeneration$DefaultAllModulesContext;
 	public final fun render (Lorg/jetbrains/dokka/pages/RootPageNode;)V
+	public final fun runPostActions ()V
 	public final fun transformAllModulesPage (Lorg/jetbrains/dokka/pages/RootPageNode;)Lorg/jetbrains/dokka/pages/RootPageNode;
 }
 
@@ -51,8 +51,10 @@ public abstract interface class org/jetbrains/dokka/allModulesPage/ExternalModul
 }
 
 public class org/jetbrains/dokka/allModulesPage/MultimoduleLocationProvider : org/jetbrains/dokka/base/resolvers/local/DokkaBaseLocationProvider {
-	public fun <init> (Lorg/jetbrains/dokka/pages/RootPageNode;Lorg/jetbrains/dokka/plugability/DokkaContext;)V
+	public fun <init> (Lorg/jetbrains/dokka/pages/RootPageNode;Lorg/jetbrains/dokka/plugability/DokkaContext;Ljava/lang/String;)V
+	public synthetic fun <init> (Lorg/jetbrains/dokka/pages/RootPageNode;Lorg/jetbrains/dokka/plugability/DokkaContext;Ljava/lang/String;ILkotlin/jvm/internal/DefaultConstructorMarker;)V
 	public fun ancestors (Lorg/jetbrains/dokka/pages/PageNode;)Ljava/util/List;
+	public final fun getExtension ()Ljava/lang/String;
 	public fun pathToRoot (Lorg/jetbrains/dokka/pages/PageNode;)Ljava/lang/String;
 	public fun resolve (Lorg/jetbrains/dokka/links/DRI;Ljava/util/Set;Lorg/jetbrains/dokka/pages/PageNode;)Ljava/lang/String;
 	public fun resolve (Lorg/jetbrains/dokka/pages/PageNode;Lorg/jetbrains/dokka/pages/PageNode;Z)Ljava/lang/String;

plugins/all-modules-page/build.gradle.kts

@@ -7,7 +7,6 @@ registerDokkaArtifactPublication("dokkaAllModulesPage") {
 dependencies {
     implementation(project(":plugins:base"))
     implementation(project(":plugins:templating"))
-    implementation(project(":plugins:versioning"))
     testImplementation(project(":plugins:base"))
     testImplementation(project(":plugins:base:base-test-utils"))
     testImplementation(project(":plugins:gfm"))

plugins/all-modules-page/src/main/kotlin/AllModulesPageGeneration.kt

@@ -11,13 +11,11 @@ import org.jetbrains.dokka.plugability.querySingle
 import org.jetbrains.dokka.templates.TemplatingPlugin
 import org.jetbrains.dokka.templates.TemplatingResult
 import org.jetbrains.dokka.transformers.pages.CreationContext
-import org.jetbrains.dokka.versioning.VersioningPlugin
 
 class AllModulesPageGeneration(private val context: DokkaContext) : Generation {
 
     private val allModulesPagePlugin by lazy { context.plugin<AllModulesPagePlugin>() }
     private val templatingPlugin by lazy { context.plugin<TemplatingPlugin>() }
-    private val versioningPlugin by lazy { context.plugin<VersioningPlugin>() }
 
     override fun Timer.generate() {
         report("Processing submodules")
@@ -26,9 +24,6 @@ class AllModulesPageGeneration(private val context: DokkaContext) : Generation {
         report("Creating all modules page")
         val pages = createAllModulesPage(generationContext)
 
-        report("Copy previous documentation")
-        handlePreviousDocs()
-
         report("Transforming pages")
         val transformedPages = transformAllModulesPage(pages)
 
@@ -40,12 +35,13 @@ class AllModulesPageGeneration(private val context: DokkaContext) : Generation {
 
         report("Finish submodule processing")
         finishProcessingSubmodules()
+
+        report("Running post-actions")
+        runPostActions()
     }
 
     override val generationName = "index page for project"
 
-    fun handlePreviousDocs() = versioningPlugin.querySingle { versioningHandler }.invoke()
-
     fun createAllModulesPage(allModulesContext: DefaultAllModulesContext) =
         allModulesPagePlugin.querySingle { allModulesPageCreator }.invoke(allModulesContext)
 
@@ -56,6 +52,10 @@ class AllModulesPageGeneration(private val context: DokkaContext) : Generation {
         context.single(CoreExtensions.renderer).render(transformedPages)
     }
 
+    fun runPostActions() {
+        context[CoreExtensions.postActions].forEach { it() }
+    }
+
     fun processSubmodules() =
         templatingPlugin.querySingle { submoduleTemplateProcessor }
             .process(context.configuration.modules)

plugins/all-modules-page/src/main/kotlin/MultimoduleLocationProvider.kt

@@ -12,7 +12,8 @@ import org.jetbrains.dokka.plugability.DokkaContext
 import org.jetbrains.dokka.plugability.plugin
 import org.jetbrains.dokka.plugability.querySingle
 
-open class MultimoduleLocationProvider(private val root: RootPageNode, dokkaContext: DokkaContext) :
+open class MultimoduleLocationProvider(private val root: RootPageNode, dokkaContext: DokkaContext,
+                                       val extension: String = ".html") :
     DokkaBaseLocationProvider(root, dokkaContext) {
 
     private val defaultLocationProvider =
@@ -27,7 +28,7 @@ open class MultimoduleLocationProvider(private val root: RootPageNode, dokkaCont
             ?.let(externalModuleLinkResolver::resolveLinkToModuleIndex)
 
     override fun resolve(node: PageNode, context: PageNode?, skipExtension: Boolean) =
-        if (node is ContentPage && MultimodulePageCreator.MULTIMODULE_ROOT_DRI in node.dri) pathToRoot(root) + "index"
+        if (node is ContentPage && MultimodulePageCreator.MULTIMODULE_ROOT_DRI in node.dri) pathToRoot(root) + "index" + if (!skipExtension) extension else ""
         else defaultLocationProvider.resolve(node, context, skipExtension)
 
     override fun pathToRoot(from: PageNode): String = defaultLocationProvider.pathToRoot(from)

plugins/all-modules-page/src/main/kotlin/MultimodulePageCreator.kt

@@ -19,14 +19,10 @@ import org.jetbrains.dokka.model.doc.P
 import org.jetbrains.dokka.model.properties.PropertyContainer
 import org.jetbrains.dokka.pages.*
 import org.jetbrains.dokka.plugability.DokkaContext
-import org.jetbrains.dokka.plugability.configuration
 import org.jetbrains.dokka.plugability.plugin
 import org.jetbrains.dokka.plugability.querySingle
 import org.jetbrains.dokka.transformers.pages.PageCreator
 import org.jetbrains.dokka.utilities.DokkaLogger
-import org.jetbrains.dokka.versioning.ReplaceVersionsCommand
-import org.jetbrains.dokka.versioning.VersioningConfiguration
-import org.jetbrains.dokka.versioning.VersioningPlugin
 import java.io.File
 
 class MultimodulePageCreator(
@@ -46,11 +42,6 @@ class MultimodulePageCreator(
             kind = ContentKind.Cover,
             sourceSets = sourceSetData
         ) {
-            /* The line below checks if there is a provided configuration for versioning.
-             If not, we are skipping the template for inserting versions navigation */
-            configuration<VersioningPlugin, VersioningConfiguration>(context)?.let {
-                group(extra = PropertyContainer.withAll(InsertTemplateExtra(ReplaceVersionsCommand))) { }
-            }
             getMultiModuleDocumentation(context.configuration.includes).takeIf { it.isNotEmpty() }?.let { nodes ->
                 group(kind = ContentKind.Cover) {
                     nodes.forEach { node ->

plugins/base/api/base.api

@@ -42,6 +42,7 @@ public final class org/jetbrains/dokka/base/DokkaBase : org/jetbrains/dokka/plug
 	public final fun getPathToRootConsumer ()Lorg/jetbrains/dokka/plugability/Extension;
 	public final fun getPreMergeDocumentableTransformer ()Lorg/jetbrains/dokka/plugability/ExtensionPoint;
 	public final fun getPsiToDocumentableTranslator ()Lorg/jetbrains/dokka/plugability/Extension;
+	public final fun getReplaceVersionConsumer ()Lorg/jetbrains/dokka/plugability/Extension;
 	public final fun getResolveLinkConsumer ()Lorg/jetbrains/dokka/plugability/Extension;
 	public final fun getRootCreator ()Lorg/jetbrains/dokka/plugability/Extension;
 	public final fun getSameMethodNameMerger ()Lorg/jetbrains/dokka/plugability/Extension;
@@ -99,6 +100,7 @@ public final class org/jetbrains/dokka/base/generation/SingleModuleGeneration :
 	public final fun mergeDocumentationModels (Ljava/util/List;)Lorg/jetbrains/dokka/model/DModule;
 	public final fun render (Lorg/jetbrains/dokka/pages/RootPageNode;)V
 	public final fun reportAfterRendering ()V
+	public final fun runPostActions ()V
 	public final fun transformDocumentationModelAfterMerge (Lorg/jetbrains/dokka/model/DModule;)Lorg/jetbrains/dokka/model/DModule;
 	public final fun transformDocumentationModelBeforeMerge (Ljava/util/List;)Ljava/util/List;
 	public final fun transformPages (Lorg/jetbrains/dokka/pages/RootPageNode;)Lorg/jetbrains/dokka/pages/RootPageNode;
@@ -534,6 +536,13 @@ public final class org/jetbrains/dokka/base/renderers/html/command/consumers/Pat
 	public fun processCommandAndFinalize (Lorg/jetbrains/dokka/base/templating/Command;Lkotlin/jvm/functions/Function1;Lorg/jetbrains/dokka/base/renderers/html/command/consumers/ImmediateResolutionTagConsumer;)Ljava/lang/Object;
 }
 
+public final class org/jetbrains/dokka/base/renderers/html/command/consumers/ReplaceVersionsConsumer : org/jetbrains/dokka/base/templating/ImmediateHtmlCommandConsumer {
+	public fun <init> (Lorg/jetbrains/dokka/plugability/DokkaContext;)V
+	public fun canProcess (Lorg/jetbrains/dokka/base/templating/Command;)Z
+	public fun processCommand (Lorg/jetbrains/dokka/base/templating/Command;Lkotlin/jvm/functions/Function1;Lorg/jetbrains/dokka/base/renderers/html/command/consumers/ImmediateResolutionTagConsumer;)V
+	public fun processCommandAndFinalize (Lorg/jetbrains/dokka/base/templating/Command;Lkotlin/jvm/functions/Function1;Lorg/jetbrains/dokka/base/renderers/html/command/consumers/ImmediateResolutionTagConsumer;)Ljava/lang/Object;
+}
+
 public final class org/jetbrains/dokka/base/renderers/html/command/consumers/ResolveLinkConsumer : org/jetbrains/dokka/base/templating/ImmediateHtmlCommandConsumer {
 	public static final field INSTANCE Lorg/jetbrains/dokka/base/renderers/html/command/consumers/ResolveLinkConsumer;
 	public fun canProcess (Lorg/jetbrains/dokka/base/templating/Command;)Z
@@ -955,6 +964,19 @@ public final class org/jetbrains/dokka/base/templating/ProjectNameSubstitutionCo
 	public fun toString ()Ljava/lang/String;
 }
 
+public final class org/jetbrains/dokka/base/templating/ReplaceVersionsCommand : org/jetbrains/dokka/base/templating/Command {
+	public fun <init> ()V
+	public fun <init> (Ljava/lang/String;)V
+	public synthetic fun <init> (Ljava/lang/String;ILkotlin/jvm/internal/DefaultConstructorMarker;)V
+	public final fun component1 ()Ljava/lang/String;
+	public final fun copy (Ljava/lang/String;)Lorg/jetbrains/dokka/base/templating/ReplaceVersionsCommand;
+	public static synthetic fun copy$default (Lorg/jetbrains/dokka/base/templating/ReplaceVersionsCommand;Ljava/lang/String;ILjava/lang/Object;)Lorg/jetbrains/dokka/base/templating/ReplaceVersionsCommand;
+	public fun equals (Ljava/lang/Object;)Z
+	public final fun getLocation ()Ljava/lang/String;
+	public fun hashCode ()I
+	public fun toString ()Ljava/lang/String;
+}
+
 public final class org/jetbrains/dokka/base/templating/ResolveLinkCommand : org/jetbrains/dokka/base/templating/Command {
 	public fun <init> (Lorg/jetbrains/dokka/links/DRI;)V
 	public final fun getDri ()Lorg/jetbrains/dokka/links/DRI;

plugins/base/src/main/kotlin/DokkaBase.kt

@@ -28,6 +28,7 @@ import org.jetbrains.dokka.base.translators.descriptors.DefaultDescriptorToDocum
 import org.jetbrains.dokka.base.translators.documentables.DefaultDocumentableToPageTranslator
 import org.jetbrains.dokka.base.translators.psi.DefaultPsiToDocumentableTranslator
 import org.jetbrains.dokka.base.generation.SingleModuleGeneration
+import org.jetbrains.dokka.base.renderers.html.command.consumers.ReplaceVersionsConsumer
 import org.jetbrains.dokka.plugability.DokkaPlugin
 import org.jetbrains.dokka.transformers.documentation.PreMergeDocumentableTransformer
 import org.jetbrains.dokka.transformers.pages.PageTransformer
@@ -242,7 +243,9 @@ class DokkaBase : DokkaPlugin() {
     val resolveLinkConsumer by extending {
         immediateHtmlCommandConsumer with ResolveLinkConsumer
     }
-
+    val replaceVersionConsumer by extending {
+        immediateHtmlCommandConsumer providing ::ReplaceVersionsConsumer
+    }
     val pathToRootConsumer by extending {
         immediateHtmlCommandConsumer with PathToRootConsumer
     }

plugins/base/src/main/kotlin/generation/SingleModuleGeneration.kt

@@ -46,6 +46,9 @@ class SingleModuleGeneration(private val context: DokkaContext) : Generation {
         report("Rendering")
         render(transformedPages)
 
+        report("Running post-actions")
+        runPostActions()
+
         reportAfterRendering()
     }
 
@@ -76,6 +79,10 @@ class SingleModuleGeneration(private val context: DokkaContext) : Generation {
         context.single(CoreExtensions.renderer).render(transformedPages)
     }
 
+    fun runPostActions() {
+        context[CoreExtensions.postActions].forEach { it() }
+    }
+
     fun validityCheck(context: DokkaContext) {
         val (preGenerationCheckResult, checkMessages) = context[CoreExtensions.preGenerationCheck].fold(
             Pair(true, emptyList<String>())

plugins/base/src/main/kotlin/renderers/DefaultRenderer.kt

@@ -12,6 +12,7 @@ import org.jetbrains.dokka.pages.*
 import org.jetbrains.dokka.plugability.DokkaContext
 import org.jetbrains.dokka.plugability.plugin
 import org.jetbrains.dokka.plugability.querySingle
+import org.jetbrains.dokka.renderers.PostAction
 import org.jetbrains.dokka.renderers.Renderer
 import org.jetbrains.dokka.transformers.pages.PageTransformer
 

plugins/base/src/main/kotlin/renderers/html/HtmlRenderer.kt

@@ -13,10 +13,7 @@ import org.jetbrains.dokka.base.renderers.isImage
 import org.jetbrains.dokka.base.renderers.pageId
 import org.jetbrains.dokka.base.resolvers.anchors.SymbolAnchorHint
 import org.jetbrains.dokka.base.resolvers.local.DokkaBaseLocationProvider
-import org.jetbrains.dokka.base.templating.InsertTemplateExtra
-import org.jetbrains.dokka.base.templating.PathToRootSubstitutionCommand
-import org.jetbrains.dokka.base.templating.ProjectNameSubstitutionCommand
-import org.jetbrains.dokka.base.templating.ResolveLinkCommand
+import org.jetbrains.dokka.base.templating.*
 import org.jetbrains.dokka.links.DRI
 import org.jetbrains.dokka.model.DisplaySourceSet
 import org.jetbrains.dokka.model.properties.PropertyContainer
@@ -757,6 +754,7 @@ open class HtmlRenderer(
         get() = URI(this).isAbsolute
 
     open fun buildHtml(page: PageNode, resources: List<String>, content: FlowContent.() -> Unit): String {
+        val path = locationProvider.resolve(page)
         val pathToRoot = locationProvider.pathToRoot(page)
         return createHTML().prepareForTemplates().html {
             head {
@@ -821,9 +819,7 @@ open class HtmlRenderer(
                     div("library-name") {
                         clickableLogo(page, pathToRoot)
                     }
-                    context.configuration.moduleVersion?.let { moduleVersion ->
-                        div { text(moduleVersion) }
-                    }
+                    div { templateCommand(ReplaceVersionsCommand(path.orEmpty())) }
                     div("pull-right d-flex") {
                         filterButtons(page)
                         button {