From fc5496fb8bb888c3a50717260dc05d8fe2d54306 Mon Sep 17 00:00:00 2001 From: vmishenev Date: Wed, 1 Sep 2021 00:03:13 +0300 Subject: [PATCH] Improve versioning plugin (#2104) - support for single module projects - version navigator is on all pages - dropdown arrow for version navigator --- core/api/core.api | 4 + core/src/main/kotlin/CoreExtensions.kt | 2 + core/src/main/kotlin/renderers/PostAction.kt | 3 + .../docs/user_guide/versioning/versioning.md | 12 +- .../it-multimodule-versioning-0/build.gradle | 3 + .../all-modules-page/api/all-modules-page.api | 6 +- plugins/all-modules-page/build.gradle.kts | 1 - .../main/kotlin/AllModulesPageGeneration.kt | 14 +- .../kotlin/MultimoduleLocationProvider.kt | 5 +- .../src/main/kotlin/MultimodulePageCreator.kt | 9 - plugins/base/api/base.api | 22 ++ plugins/base/src/main/kotlin/DokkaBase.kt | 5 +- .../generation/SingleModuleGeneration.kt | 7 + .../main/kotlin/renderers/DefaultRenderer.kt | 1 + .../kotlin/renderers/html/HtmlRenderer.kt | 10 +- .../consumers/ReplaceVersionsConsumer.kt | 25 +++ .../templating/ReplaceVersionsCommand.kt | 3 + plugins/templating/api/templating.api | 8 + .../templates/ReplaceVersionCommandHandler.kt | 22 ++ .../main/kotlin/templates/TemplatingPlugin.kt | 4 + plugins/versioning/api/versioning.api | 84 +++++--- ...aultPreviousDocumentationCopyPostAction.kt | 54 +++++ .../ReplaceVersionCommandConsumer.kt | 13 +- .../versioning/ReplaceVersionsCommand.kt | 3 +- .../versioning/VersioningConfiguration.kt | 5 + .../kotlin/versioning/VersioningHandler.kt | 104 ---------- .../kotlin/versioning/VersioningPlugin.kt | 25 ++- .../kotlin/versioning/VersioningStorage.kt | 65 ++++++ .../versioning/VersionsNavigationCreator.kt | 73 +++++-- .../kotlin/versioning/htmlPreprocessors.kt | 22 +- .../resources/dokka/not-found-version.html | 189 ++++++++++++++++++ .../resources/dokka/styles/multimodule.css | 30 ++- 32 files changed, 627 insertions(+), 206 deletions(-) create mode 100644 core/src/main/kotlin/renderers/PostAction.kt create mode 100644 plugins/base/src/main/kotlin/renderers/html/command/consumers/ReplaceVersionsConsumer.kt create mode 100644 plugins/base/src/main/kotlin/templating/ReplaceVersionsCommand.kt create mode 100644 plugins/templating/src/main/kotlin/templates/ReplaceVersionCommandHandler.kt create mode 100644 plugins/versioning/src/main/kotlin/versioning/DefaultPreviousDocumentationCopyPostAction.kt delete mode 100644 plugins/versioning/src/main/kotlin/versioning/VersioningHandler.kt create mode 100644 plugins/versioning/src/main/kotlin/versioning/VersioningStorage.kt create mode 100644 plugins/versioning/src/main/resources/dokka/not-found-version.html diff --git a/core/api/core.api b/core/api/core.api index 05a6207c9d..ed83f3a794 100644 --- a/core/api/core.api +++ b/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 } diff --git a/core/src/main/kotlin/CoreExtensions.kt b/core/src/main/kotlin/CoreExtensions.kt index 66e717b4f1..0dd5780b61 100644 --- a/core/src/main/kotlin/CoreExtensions.kt +++ b/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() val pageTransformer by coreExtensionPoint() val renderer by coreExtensionPoint() + val postActions by coreExtensionPoint() private fun coreExtensionPoint() = object { operator fun provideDelegate(thisRef: CoreExtensions, property: KProperty<*>): Lazy> = diff --git a/core/src/main/kotlin/renderers/PostAction.kt b/core/src/main/kotlin/renderers/PostAction.kt new file mode 100644 index 0000000000..e47d5d22be --- /dev/null +++ b/core/src/main/kotlin/renderers/PostAction.kt @@ -0,0 +1,3 @@ +package org.jetbrains.dokka.renderers + +interface PostAction : () -> Unit \ No newline at end of file diff --git a/docs/src/doc/docs/user_guide/versioning/versioning.md b/docs/src/doc/docs/user_guide/versioning/versioning.md index 7cb2a78350..ad1c826743 100644 --- a/docs/src/doc/docs/user_guide/versioning/versioning.md +++ b/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: diff --git a/integration-tests/gradle/projects/it-multimodule-versioning-0/build.gradle b/integration-tests/gradle/projects/it-multimodule-versioning-0/build.gradle index bceacbca44..e04e412bdb 100644 --- a/integration-tests/gradle/projects/it-multimodule-versioning-0/build.gradle +++ b/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" }"""]) diff --git a/plugins/all-modules-page/api/all-modules-page.api b/plugins/all-modules-page/api/all-modules-page.api index 1849c6d9bc..9d8bca9b48 100644 --- a/plugins/all-modules-page/api/all-modules-page.api +++ b/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 (Lorg/jetbrains/dokka/pages/RootPageNode;Lorg/jetbrains/dokka/plugability/DokkaContext;)V + public fun (Lorg/jetbrains/dokka/pages/RootPageNode;Lorg/jetbrains/dokka/plugability/DokkaContext;Ljava/lang/String;)V + public synthetic fun (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; diff --git a/plugins/all-modules-page/build.gradle.kts b/plugins/all-modules-page/build.gradle.kts index 9ab299f63a..ff9fcbd854 100644 --- a/plugins/all-modules-page/build.gradle.kts +++ b/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")) diff --git a/plugins/all-modules-page/src/main/kotlin/AllModulesPageGeneration.kt b/plugins/all-modules-page/src/main/kotlin/AllModulesPageGeneration.kt index 21c624efa4..8558750eb6 100644 --- a/plugins/all-modules-page/src/main/kotlin/AllModulesPageGeneration.kt +++ b/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() } private val templatingPlugin by lazy { context.plugin() } - private val versioningPlugin by lazy { context.plugin() } 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) diff --git a/plugins/all-modules-page/src/main/kotlin/MultimoduleLocationProvider.kt b/plugins/all-modules-page/src/main/kotlin/MultimoduleLocationProvider.kt index 1a323f63c3..dab5be094b 100644 --- a/plugins/all-modules-page/src/main/kotlin/MultimoduleLocationProvider.kt +++ b/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) diff --git a/plugins/all-modules-page/src/main/kotlin/MultimodulePageCreator.kt b/plugins/all-modules-page/src/main/kotlin/MultimodulePageCreator.kt index 4285046a16..f522fd4ca2 100644 --- a/plugins/all-modules-page/src/main/kotlin/MultimodulePageCreator.kt +++ b/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(context)?.let { - group(extra = PropertyContainer.withAll(InsertTemplateExtra(ReplaceVersionsCommand))) { } - } getMultiModuleDocumentation(context.configuration.includes).takeIf { it.isNotEmpty() }?.let { nodes -> group(kind = ContentKind.Cover) { nodes.forEach { node -> diff --git a/plugins/base/api/base.api b/plugins/base/api/base.api index 10d2c564c6..2ab821d427 100644 --- a/plugins/base/api/base.api +++ b/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 (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 ()V + public fun (Ljava/lang/String;)V + public synthetic fun (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 (Lorg/jetbrains/dokka/links/DRI;)V public final fun getDri ()Lorg/jetbrains/dokka/links/DRI; diff --git a/plugins/base/src/main/kotlin/DokkaBase.kt b/plugins/base/src/main/kotlin/DokkaBase.kt index 7e88d08f0d..fc1384618f 100644 --- a/plugins/base/src/main/kotlin/DokkaBase.kt +++ b/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 } diff --git a/plugins/base/src/main/kotlin/generation/SingleModuleGeneration.kt b/plugins/base/src/main/kotlin/generation/SingleModuleGeneration.kt index e0deef17bd..5cdeeb40f3 100644 --- a/plugins/base/src/main/kotlin/generation/SingleModuleGeneration.kt +++ b/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()) diff --git a/plugins/base/src/main/kotlin/renderers/DefaultRenderer.kt b/plugins/base/src/main/kotlin/renderers/DefaultRenderer.kt index 5eaf9fc74d..2a21337fda 100644 --- a/plugins/base/src/main/kotlin/renderers/DefaultRenderer.kt +++ b/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 diff --git a/plugins/base/src/main/kotlin/renderers/html/HtmlRenderer.kt b/plugins/base/src/main/kotlin/renderers/html/HtmlRenderer.kt index 951f097383..9a88de86af 100644 --- a/plugins/base/src/main/kotlin/renderers/html/HtmlRenderer.kt +++ b/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, 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 { diff --git a/plugins/base/src/main/kotlin/renderers/html/command/consumers/ReplaceVersionsConsumer.kt b/plugins/base/src/main/kotlin/renderers/html/command/consumers/ReplaceVersionsConsumer.kt new file mode 100644 index 0000000000..ea8cde0f4c --- /dev/null +++ b/plugins/base/src/main/kotlin/renderers/html/command/consumers/ReplaceVersionsConsumer.kt @@ -0,0 +1,25 @@ +package org.jetbrains.dokka.base.renderers.html.command.consumers + +import org.jetbrains.dokka.base.renderers.html.TemplateBlock +import org.jetbrains.dokka.base.templating.Command +import org.jetbrains.dokka.base.templating.ImmediateHtmlCommandConsumer +import org.jetbrains.dokka.base.templating.ReplaceVersionsCommand +import org.jetbrains.dokka.plugability.DokkaContext + +class ReplaceVersionsConsumer(private val context: DokkaContext) : ImmediateHtmlCommandConsumer { + override fun canProcess(command: Command) = command is ReplaceVersionsCommand + + override fun processCommand( + command: Command, + block: TemplateBlock, + tagConsumer: ImmediateResolutionTagConsumer + ) { + command as ReplaceVersionsCommand + tagConsumer.onTagContentUnsafe { +context.configuration.moduleVersion.orEmpty() } + } + + override fun processCommandAndFinalize(command: Command, block: TemplateBlock, tagConsumer: ImmediateResolutionTagConsumer): R { + PathToRootConsumer.processCommand(command, block, tagConsumer) + return tagConsumer.finalize() + } +} \ No newline at end of file diff --git a/plugins/base/src/main/kotlin/templating/ReplaceVersionsCommand.kt b/plugins/base/src/main/kotlin/templating/ReplaceVersionsCommand.kt new file mode 100644 index 0000000000..89f267b3d9 --- /dev/null +++ b/plugins/base/src/main/kotlin/templating/ReplaceVersionsCommand.kt @@ -0,0 +1,3 @@ +package org.jetbrains.dokka.base.templating + +data class ReplaceVersionsCommand(val location: String = ""): Command \ No newline at end of file diff --git a/plugins/templating/api/templating.api b/plugins/templating/api/templating.api index 0965020bba..a0fb512288 100644 --- a/plugins/templating/api/templating.api +++ b/plugins/templating/api/templating.api @@ -130,6 +130,7 @@ public final class org/jetbrains/dokka/templates/TemplatingPlugin : org/jetbrain public final fun getPagesSearchTemplateStrategy ()Lorg/jetbrains/dokka/plugability/Extension; public final fun getPathToRootSubstitutor ()Lorg/jetbrains/dokka/plugability/Extension; public final fun getProjectNameSubstitutor ()Lorg/jetbrains/dokka/plugability/Extension; + public final fun getReplaceVersionCommandHandler ()Lorg/jetbrains/dokka/plugability/Extension; public final fun getSourcesetDependencyProcessingStrategy ()Lorg/jetbrains/dokka/plugability/Extension; public final fun getSubmoduleTemplateProcessor ()Lorg/jetbrains/dokka/plugability/ExtensionPoint; public final fun getSubstitutionCommandHandler ()Lorg/jetbrains/dokka/plugability/Extension; @@ -156,6 +157,13 @@ public final class templates/ProjectNameSubstitutor : org/jetbrains/dokka/templa public fun trySubstitute (Lorg/jetbrains/dokka/templates/TemplatingContext;Lkotlin/text/MatchResult;)Ljava/lang/String; } +public final class templates/ReplaceVersionCommandHandler : org/jetbrains/dokka/templates/CommandHandler { + public fun (Lorg/jetbrains/dokka/plugability/DokkaContext;)V + public fun canHandle (Lorg/jetbrains/dokka/base/templating/Command;)Z + public fun finish (Ljava/io/File;)V + public fun handleCommand (Lorg/jsoup/nodes/Element;Lorg/jetbrains/dokka/base/templating/Command;Ljava/io/File;Ljava/io/File;)V +} + public final class templates/SourcesetDependencyProcessingStrategy : org/jetbrains/dokka/templates/TemplateProcessingStrategy { public fun (Lorg/jetbrains/dokka/plugability/DokkaContext;)V public fun finish (Ljava/io/File;)V diff --git a/plugins/templating/src/main/kotlin/templates/ReplaceVersionCommandHandler.kt b/plugins/templating/src/main/kotlin/templates/ReplaceVersionCommandHandler.kt new file mode 100644 index 0000000000..8035fc83be --- /dev/null +++ b/plugins/templating/src/main/kotlin/templates/ReplaceVersionCommandHandler.kt @@ -0,0 +1,22 @@ +package templates + +import org.jetbrains.dokka.base.templating.Command +import org.jetbrains.dokka.base.templating.ReplaceVersionsCommand +import org.jetbrains.dokka.plugability.DokkaContext +import org.jetbrains.dokka.templates.CommandHandler +import org.jsoup.nodes.Element +import org.jsoup.nodes.TextNode +import java.io.File + +class ReplaceVersionCommandHandler(private val context: DokkaContext) : CommandHandler { + + override fun canHandle(command: Command): Boolean = command is ReplaceVersionsCommand + + override fun handleCommand(element: Element, command: Command, input: File, output: File) { + val position = element.elementSiblingIndex() + val parent = element.parent() + element.remove() + context.configuration.moduleVersion?.takeIf { it.isNotEmpty() } + ?.let { parent.insertChildren(position, TextNode(it)) } + } +} \ No newline at end of file diff --git a/plugins/templating/src/main/kotlin/templates/TemplatingPlugin.kt b/plugins/templating/src/main/kotlin/templates/TemplatingPlugin.kt index 1a02d41f19..7001b1ba59 100644 --- a/plugins/templating/src/main/kotlin/templates/TemplatingPlugin.kt +++ b/plugins/templating/src/main/kotlin/templates/TemplatingPlugin.kt @@ -4,6 +4,7 @@ import org.jetbrains.dokka.allModulesPage.templates.PackageListProcessingStrateg import org.jetbrains.dokka.allModulesPage.templates.PagesSearchTemplateStrategy import org.jetbrains.dokka.plugability.DokkaPlugin import templates.ProjectNameSubstitutor +import templates.ReplaceVersionCommandHandler import templates.SourcesetDependencyProcessingStrategy class TemplatingPlugin : DokkaPlugin() { @@ -65,4 +66,7 @@ class TemplatingPlugin : DokkaPlugin() { val substitutionCommandHandler by extending { directiveBasedCommandHandlers providing ::SubstitutionCommandHandler } + val replaceVersionCommandHandler by extending { + directiveBasedCommandHandlers providing ::ReplaceVersionCommandHandler + } } diff --git a/plugins/versioning/api/versioning.api b/plugins/versioning/api/versioning.api index 8223579b63..15ebe7bea7 100644 --- a/plugins/versioning/api/versioning.api +++ b/plugins/versioning/api/versioning.api @@ -4,28 +4,45 @@ public final class org/jetbrains/dokka/versioning/ByConfigurationVersionOrdering public fun order (Ljava/util/List;)Ljava/util/List; } -public final class org/jetbrains/dokka/versioning/DefaultVersioningHandler : org/jetbrains/dokka/versioning/VersioningHandler { - public static final field Companion Lorg/jetbrains/dokka/versioning/DefaultVersioningHandler$Companion; +public final class org/jetbrains/dokka/versioning/CurrentVersion { + public fun (Ljava/lang/String;Ljava/io/File;)V + public final fun component1 ()Ljava/lang/String; + public final fun component2 ()Ljava/io/File; + public final fun copy (Ljava/lang/String;Ljava/io/File;)Lorg/jetbrains/dokka/versioning/CurrentVersion; + public static synthetic fun copy$default (Lorg/jetbrains/dokka/versioning/CurrentVersion;Ljava/lang/String;Ljava/io/File;ILjava/lang/Object;)Lorg/jetbrains/dokka/versioning/CurrentVersion; + public fun equals (Ljava/lang/Object;)Z + public final fun getDir ()Ljava/io/File; + public final fun getName ()Ljava/lang/String; + public fun hashCode ()I + public fun toString ()Ljava/lang/String; +} + +public final class org/jetbrains/dokka/versioning/DefaultPreviousDocumentationCopyPostAction : org/jetbrains/dokka/renderers/PostAction { public fun (Lorg/jetbrains/dokka/plugability/DokkaContext;)V - public fun currentVersion ()Ljava/io/File; - public final fun getContext ()Lorg/jetbrains/dokka/plugability/DokkaContext; - public fun getVersions ()Ljava/util/Map; public synthetic fun invoke ()Ljava/lang/Object; public fun invoke ()V } -public final class org/jetbrains/dokka/versioning/DefaultVersioningHandler$Companion { +public final class org/jetbrains/dokka/versioning/DefaultVersioningStorage : org/jetbrains/dokka/versioning/VersioningStorage { + public fun (Lorg/jetbrains/dokka/plugability/DokkaContext;)V + public fun createVersionFile ()V + public final fun getContext ()Lorg/jetbrains/dokka/plugability/DokkaContext; + public fun getCurrentVersion ()Lorg/jetbrains/dokka/versioning/CurrentVersion; + public fun getPreviousVersions ()Ljava/util/Map; } public final class org/jetbrains/dokka/versioning/HtmlVersionsNavigationCreator : org/jetbrains/dokka/versioning/VersionsNavigationCreator { public fun (Lorg/jetbrains/dokka/plugability/DokkaContext;)V - public final fun getContext ()Lorg/jetbrains/dokka/plugability/DokkaContext; - public fun invoke ()Ljava/lang/String; public fun invoke (Ljava/io/File;)Ljava/lang/String; } public final class org/jetbrains/dokka/versioning/MultiModuleStylesInstaller : org/jetbrains/dokka/transformers/pages/PageTransformer { - public static final field INSTANCE Lorg/jetbrains/dokka/versioning/MultiModuleStylesInstaller; + public fun (Lorg/jetbrains/dokka/plugability/DokkaContext;)V + public fun invoke (Lorg/jetbrains/dokka/pages/RootPageNode;)Lorg/jetbrains/dokka/pages/RootPageNode; +} + +public final class org/jetbrains/dokka/versioning/NotFoundPageInstaller : org/jetbrains/dokka/transformers/pages/PageTransformer { + public fun (Lorg/jetbrains/dokka/plugability/DokkaContext;)V public fun invoke (Lorg/jetbrains/dokka/pages/RootPageNode;)Lorg/jetbrains/dokka/pages/RootPageNode; } @@ -44,34 +61,48 @@ public final class org/jetbrains/dokka/versioning/ReplaceVersionCommandHandler : public fun handleCommand (Lorg/jsoup/nodes/Element;Lorg/jetbrains/dokka/base/templating/Command;Ljava/io/File;Ljava/io/File;)V } -public final class org/jetbrains/dokka/versioning/ReplaceVersionsCommand : org/jetbrains/dokka/base/templating/Command { - public static final field INSTANCE Lorg/jetbrains/dokka/versioning/ReplaceVersionsCommand; -} - public final class org/jetbrains/dokka/versioning/SemVerVersionOrdering : org/jetbrains/dokka/versioning/VersionsOrdering { public fun ()V public fun order (Ljava/util/List;)Ljava/util/List; } +public final class org/jetbrains/dokka/versioning/VersionDirs { + public fun (Ljava/io/File;Ljava/io/File;)V + public final fun component1 ()Ljava/io/File; + public final fun component2 ()Ljava/io/File; + public final fun copy (Ljava/io/File;Ljava/io/File;)Lorg/jetbrains/dokka/versioning/VersionDirs; + public static synthetic fun copy$default (Lorg/jetbrains/dokka/versioning/VersionDirs;Ljava/io/File;Ljava/io/File;ILjava/lang/Object;)Lorg/jetbrains/dokka/versioning/VersionDirs; + public fun equals (Ljava/lang/Object;)Z + public final fun getDst ()Ljava/io/File; + public final fun getSrc ()Ljava/io/File; + public fun hashCode ()I + public fun toString ()Ljava/lang/String; +} + public final class org/jetbrains/dokka/versioning/VersioningConfiguration : org/jetbrains/dokka/plugability/ConfigurableBlock { public static final field Companion Lorg/jetbrains/dokka/versioning/VersioningConfiguration$Companion; + public static final field OLDER_VERSIONS_DIR Ljava/lang/String; + public static final field VERSIONS_FILE Ljava/lang/String; public fun ()V - public fun (Ljava/io/File;Ljava/util/List;Ljava/util/List;Ljava/lang/String;)V - public synthetic fun (Ljava/io/File;Ljava/util/List;Ljava/util/List;Ljava/lang/String;ILkotlin/jvm/internal/DefaultConstructorMarker;)V + public fun (Ljava/io/File;Ljava/util/List;Ljava/util/List;Ljava/lang/String;Ljava/lang/Boolean;)V + public synthetic fun (Ljava/io/File;Ljava/util/List;Ljava/util/List;Ljava/lang/String;Ljava/lang/Boolean;ILkotlin/jvm/internal/DefaultConstructorMarker;)V public final fun component1 ()Ljava/io/File; public final fun component2 ()Ljava/util/List; public final fun component3 ()Ljava/util/List; public final fun component4 ()Ljava/lang/String; - public final fun copy (Ljava/io/File;Ljava/util/List;Ljava/util/List;Ljava/lang/String;)Lorg/jetbrains/dokka/versioning/VersioningConfiguration; - public static synthetic fun copy$default (Lorg/jetbrains/dokka/versioning/VersioningConfiguration;Ljava/io/File;Ljava/util/List;Ljava/util/List;Ljava/lang/String;ILjava/lang/Object;)Lorg/jetbrains/dokka/versioning/VersioningConfiguration; + public final fun component5 ()Ljava/lang/Boolean; + public final fun copy (Ljava/io/File;Ljava/util/List;Ljava/util/List;Ljava/lang/String;Ljava/lang/Boolean;)Lorg/jetbrains/dokka/versioning/VersioningConfiguration; + public static synthetic fun copy$default (Lorg/jetbrains/dokka/versioning/VersioningConfiguration;Ljava/io/File;Ljava/util/List;Ljava/util/List;Ljava/lang/String;Ljava/lang/Boolean;ILjava/lang/Object;)Lorg/jetbrains/dokka/versioning/VersioningConfiguration; public fun equals (Ljava/lang/Object;)Z public final fun getOlderVersions ()Ljava/util/List; public final fun getOlderVersionsDir ()Ljava/io/File; + public final fun getRenderVersionsNavigationOnAllPages ()Ljava/lang/Boolean; public final fun getVersion ()Ljava/lang/String; public final fun getVersionsOrdering ()Ljava/util/List; public fun hashCode ()I public final fun setOlderVersions (Ljava/util/List;)V public final fun setOlderVersionsDir (Ljava/io/File;)V + public final fun setRenderVersionsNavigationOnAllPages (Ljava/lang/Boolean;)V public final fun setVersion (Ljava/lang/String;)V public final fun setVersionsOrdering (Ljava/util/List;)V public fun toString ()Ljava/lang/String; @@ -80,30 +111,33 @@ public final class org/jetbrains/dokka/versioning/VersioningConfiguration : org/ public final class org/jetbrains/dokka/versioning/VersioningConfiguration$Companion { public final fun getDefaultOlderVersions ()Ljava/util/List; public final fun getDefaultOlderVersionsDir ()Ljava/io/File; + public final fun getDefaultRenderVersionsNavigationOnAllPages ()Z public final fun getDefaultVersion ()Ljava/lang/Void; public final fun getDefaultVersionsOrdering ()Ljava/util/List; } -public abstract interface class org/jetbrains/dokka/versioning/VersioningHandler : kotlin/jvm/functions/Function0 { - public abstract fun currentVersion ()Ljava/io/File; - public abstract fun getVersions ()Ljava/util/Map; -} - public final class org/jetbrains/dokka/versioning/VersioningPlugin : org/jetbrains/dokka/plugability/DokkaPlugin { public fun ()V public final fun getCssStyleInstaller ()Lorg/jetbrains/dokka/plugability/Extension; - public final fun getDefaultVersioningHandler ()Lorg/jetbrains/dokka/plugability/Extension; public final fun getDefaultVersioningNavigationCreator ()Lorg/jetbrains/dokka/plugability/Extension; + public final fun getDefaultVersioningStorage ()Lorg/jetbrains/dokka/plugability/Extension; + public final fun getNotFoundPageInstaller ()Lorg/jetbrains/dokka/plugability/Extension; + public final fun getPreviousDocumentationCopyPostAction ()Lorg/jetbrains/dokka/plugability/Extension; public final fun getReplaceVersionCommandHandler ()Lorg/jetbrains/dokka/plugability/Extension; public final fun getResolveLinkConsumer ()Lorg/jetbrains/dokka/plugability/Extension; - public final fun getVersioningHandler ()Lorg/jetbrains/dokka/plugability/ExtensionPoint; + public final fun getVersioningStorage ()Lorg/jetbrains/dokka/plugability/ExtensionPoint; public final fun getVersionsDefaultOrdering ()Lorg/jetbrains/dokka/plugability/Extension; public final fun getVersionsNavigationCreator ()Lorg/jetbrains/dokka/plugability/ExtensionPoint; public final fun getVersionsOrdering ()Lorg/jetbrains/dokka/plugability/ExtensionPoint; } +public abstract interface class org/jetbrains/dokka/versioning/VersioningStorage { + public abstract fun createVersionFile ()V + public abstract fun getCurrentVersion ()Lorg/jetbrains/dokka/versioning/CurrentVersion; + public abstract fun getPreviousVersions ()Ljava/util/Map; +} + public abstract interface class org/jetbrains/dokka/versioning/VersionsNavigationCreator { - public abstract fun invoke ()Ljava/lang/String; public abstract fun invoke (Ljava/io/File;)Ljava/lang/String; } diff --git a/plugins/versioning/src/main/kotlin/versioning/DefaultPreviousDocumentationCopyPostAction.kt b/plugins/versioning/src/main/kotlin/versioning/DefaultPreviousDocumentationCopyPostAction.kt new file mode 100644 index 0000000000..6ab81d3107 --- /dev/null +++ b/plugins/versioning/src/main/kotlin/versioning/DefaultPreviousDocumentationCopyPostAction.kt @@ -0,0 +1,54 @@ +package org.jetbrains.dokka.versioning + +import kotlinx.coroutines.Dispatchers +import kotlinx.coroutines.coroutineScope +import kotlinx.coroutines.launch +import kotlinx.coroutines.runBlocking +import org.jetbrains.dokka.renderers.PostAction +import org.jetbrains.dokka.plugability.DokkaContext +import org.jetbrains.dokka.plugability.plugin +import org.jetbrains.dokka.plugability.query +import org.jetbrains.dokka.plugability.querySingle +import org.jetbrains.dokka.templates.TemplateProcessingStrategy +import org.jetbrains.dokka.templates.TemplatingPlugin +import java.io.File + +class DefaultPreviousDocumentationCopyPostAction(private val context: DokkaContext) : PostAction { + private val versioningStorage by lazy { context.plugin().querySingle { versioningStorage } } + private val processingStrategies: List = + context.plugin().query { templateProcessingStrategy } + + override fun invoke() { + versioningStorage.createVersionFile() + versioningStorage.previousVersions.forEach { (_, dirs) -> copyVersion(dirs.src, dirs.dst) } + } + + private fun copyVersion(versionRoot: File, targetParent: File) { + targetParent.apply { mkdirs() } + val ignoreDir = versionRoot.resolve(VersioningConfiguration.OLDER_VERSIONS_DIR) + runBlocking(Dispatchers.Default) { + coroutineScope { + versionRoot.listFiles().orEmpty() + .filter { it.absolutePath != ignoreDir.absolutePath } + .forEach { versionRootContent -> + launch { + processRecursively(versionRootContent, targetParent) + } + } + } + } + } + + private fun processRecursively(versionRootContent: File, targetParent: File) { + if (versionRootContent.isDirectory) { + val target = targetParent.resolve(versionRootContent.name).also { it.mkdir() } + versionRootContent.listFiles()?.forEach { + processRecursively(it, target) + } + } else if (versionRootContent.extension == "html") processingStrategies.first { + it.process(versionRootContent, targetParent.resolve(versionRootContent.name), null) + } else { + versionRootContent.copyTo(targetParent.resolve(versionRootContent.name), overwrite = true) + } + } +} \ No newline at end of file diff --git a/plugins/versioning/src/main/kotlin/versioning/ReplaceVersionCommandConsumer.kt b/plugins/versioning/src/main/kotlin/versioning/ReplaceVersionCommandConsumer.kt index 2577b2da5c..ea524c52a1 100644 --- a/plugins/versioning/src/main/kotlin/versioning/ReplaceVersionCommandConsumer.kt +++ b/plugins/versioning/src/main/kotlin/versioning/ReplaceVersionCommandConsumer.kt @@ -8,6 +8,7 @@ import org.jetbrains.dokka.base.renderers.html.command.consumers.ImmediateResolu import org.jetbrains.dokka.base.renderers.html.templateCommandFor import org.jetbrains.dokka.base.templating.Command import org.jetbrains.dokka.base.templating.ImmediateHtmlCommandConsumer +import org.jetbrains.dokka.base.templating.ReplaceVersionsCommand import org.jetbrains.dokka.plugability.DokkaContext import org.jetbrains.dokka.plugability.plugin import org.jetbrains.dokka.plugability.querySingle @@ -16,6 +17,8 @@ class ReplaceVersionCommandConsumer(context: DokkaContext) : ImmediateHtmlComman private val versionsNavigationCreator = context.plugin().querySingle { versionsNavigationCreator } + private val versioningStorage = + context.plugin().querySingle { versioningStorage } override fun canProcess(command: Command) = command is ReplaceVersionsCommand @@ -27,7 +30,7 @@ class ReplaceVersionCommandConsumer(context: DokkaContext) : ImmediateHtmlComman command as ReplaceVersionsCommand templateCommandFor(command, tagConsumer).visit { unsafe { - +versionsNavigationCreator() + +versionsNavigationCreator(versioningStorage.currentVersion.dir.resolve(command.location)) } } } @@ -36,10 +39,12 @@ class ReplaceVersionCommandConsumer(context: DokkaContext) : ImmediateHtmlComman command: Command, block: TemplateBlock, tagConsumer: ImmediateResolutionTagConsumer - ): R = - templateCommandFor(command, tagConsumer).visitAndFinalize(tagConsumer) { + ): R { + command as ReplaceVersionsCommand + return templateCommandFor(command, tagConsumer).visitAndFinalize(tagConsumer) { unsafe { - +versionsNavigationCreator() + +versionsNavigationCreator(versioningStorage.currentVersion.dir.resolve(command.location)) } } + } } \ No newline at end of file diff --git a/plugins/versioning/src/main/kotlin/versioning/ReplaceVersionsCommand.kt b/plugins/versioning/src/main/kotlin/versioning/ReplaceVersionsCommand.kt index 2d2c8e36d6..728eac09d4 100644 --- a/plugins/versioning/src/main/kotlin/versioning/ReplaceVersionsCommand.kt +++ b/plugins/versioning/src/main/kotlin/versioning/ReplaceVersionsCommand.kt @@ -2,6 +2,7 @@ package org.jetbrains.dokka.versioning import org.jetbrains.dokka.base.templating.Command +import org.jetbrains.dokka.base.templating.ReplaceVersionsCommand import org.jetbrains.dokka.plugability.DokkaContext import org.jetbrains.dokka.plugability.plugin import org.jetbrains.dokka.plugability.querySingle @@ -9,8 +10,6 @@ import org.jetbrains.dokka.templates.CommandHandler import org.jsoup.nodes.Element import java.io.File -object ReplaceVersionsCommand : Command - class ReplaceVersionCommandHandler(context: DokkaContext) : CommandHandler { val versionsNavigationCreator by lazy { diff --git a/plugins/versioning/src/main/kotlin/versioning/VersioningConfiguration.kt b/plugins/versioning/src/main/kotlin/versioning/VersioningConfiguration.kt index f5c69cf4a8..56c7225778 100644 --- a/plugins/versioning/src/main/kotlin/versioning/VersioningConfiguration.kt +++ b/plugins/versioning/src/main/kotlin/versioning/VersioningConfiguration.kt @@ -9,6 +9,7 @@ data class VersioningConfiguration( var olderVersions: List? = defaultOlderVersions, var versionsOrdering: List? = defaultVersionsOrdering, var version: String? = defaultVersion, + var renderVersionsNavigationOnAllPages: Boolean? = defaultRenderVersionsNavigationOnAllPages ) : ConfigurableBlock { internal fun versionFromConfigurationOrModule(dokkaContext: DokkaContext): String = version ?: dokkaContext.configuration.moduleVersion ?: "1.0" @@ -25,5 +26,9 @@ data class VersioningConfiguration( val defaultOlderVersions: List? = null val defaultVersionsOrdering: List? = null val defaultVersion = null + val defaultRenderVersionsNavigationOnAllPages = true + + const val OLDER_VERSIONS_DIR = "older" + const val VERSIONS_FILE = "version.json" } } \ No newline at end of file diff --git a/plugins/versioning/src/main/kotlin/versioning/VersioningHandler.kt b/plugins/versioning/src/main/kotlin/versioning/VersioningHandler.kt deleted file mode 100644 index 1cc584b77d..0000000000 --- a/plugins/versioning/src/main/kotlin/versioning/VersioningHandler.kt +++ /dev/null @@ -1,104 +0,0 @@ -package org.jetbrains.dokka.versioning - -import com.fasterxml.jackson.annotation.JsonProperty -import com.fasterxml.jackson.databind.ObjectMapper -import com.fasterxml.jackson.module.kotlin.readValue -import kotlinx.coroutines.Dispatchers -import kotlinx.coroutines.coroutineScope -import kotlinx.coroutines.launch -import kotlinx.coroutines.runBlocking -import org.jetbrains.dokka.plugability.DokkaContext -import org.jetbrains.dokka.plugability.configuration -import org.jetbrains.dokka.plugability.plugin -import org.jetbrains.dokka.plugability.query -import org.jetbrains.dokka.templates.TemplateProcessingStrategy -import org.jetbrains.dokka.templates.TemplatingPlugin -import java.io.File - -interface VersioningHandler : () -> Unit { - fun getVersions(): Map - fun currentVersion(): File? -} - -typealias VersionId = String - -class DefaultVersioningHandler(val context: DokkaContext) : VersioningHandler { - - private val mapper = ObjectMapper() - - private lateinit var versions: Map - - private val processingStrategies: List = - context.plugin().query { templateProcessingStrategy } - - private val configuration = configuration(context) - - override fun getVersions() = versions - - override fun currentVersion() = configuration?.let { versionsConfiguration -> - versions[versionsConfiguration.versionFromConfigurationOrModule(context)] - } - - override fun invoke() { - configuration?.let { versionsConfiguration -> - versions = - mapOf(versionsConfiguration.versionFromConfigurationOrModule(context) to context.configuration.outputDir) - handlePreviousVersions(versionsConfiguration.allOlderVersions(), context.configuration.outputDir) - mapper.writeValue( - context.configuration.outputDir.resolve(VERSIONS_FILE), - Version(versionsConfiguration.versionFromConfigurationOrModule(context)) - ) - } - } - - private fun handlePreviousVersions(olderVersions: List, output: File): Map { - return versionsFrom(olderVersions) - .also { fetched -> - versions = versions + fetched.map { (key, _) -> - key to output.resolve(OLDER_VERSIONS_DIR).resolve(key) - }.toMap() - } - .onEach { (version, path) -> copyVersion(version, path, output) }.toMap() - } - - private fun versionsFrom(olderVersions: List) = - olderVersions.mapNotNull { versionDir -> - versionDir.listFiles { _, name -> name == VERSIONS_FILE }?.firstOrNull()?.let { file -> - val versionsContent = mapper.readValue(file) - Pair(versionsContent.version, versionDir) - }.also { - if (it == null) context.logger.warn("Failed to find versions file named $VERSIONS_FILE in $versionDir") - } - } - - private fun copyVersion(version: VersionId, versionRoot: File, output: File) { - val targetParent = output.resolve(OLDER_VERSIONS_DIR).resolve(version).apply { mkdirs() } - val olderDirs = versionRoot.resolve(OLDER_VERSIONS_DIR) - runBlocking(Dispatchers.Default) { - coroutineScope { - versionRoot.listFiles().orEmpty() - .filter { it.absolutePath != olderDirs.absolutePath } - .forEach { versionRootContent -> - launch { - if (versionRootContent.isDirectory) versionRootContent.copyRecursively( - targetParent.resolve(versionRootContent.name), - overwrite = true - ) - else processingStrategies.first { - it.process(versionRootContent, targetParent.resolve(versionRootContent.name), null) - } - } - } - } - } - } - - private data class Version( - @JsonProperty("version") val version: String, - ) - - companion object { - private const val OLDER_VERSIONS_DIR = "older" - private const val VERSIONS_FILE = "version.json" - } -} diff --git a/plugins/versioning/src/main/kotlin/versioning/VersioningPlugin.kt b/plugins/versioning/src/main/kotlin/versioning/VersioningPlugin.kt index 9c20a128b8..e4e8bbae63 100644 --- a/plugins/versioning/src/main/kotlin/versioning/VersioningPlugin.kt +++ b/plugins/versioning/src/main/kotlin/versioning/VersioningPlugin.kt @@ -1,5 +1,6 @@ package org.jetbrains.dokka.versioning +import org.jetbrains.dokka.CoreExtensions.postActions import org.jetbrains.dokka.base.DokkaBase import org.jetbrains.dokka.plugability.DokkaPlugin import org.jetbrains.dokka.plugability.configuration @@ -7,27 +8,36 @@ import org.jetbrains.dokka.templates.TemplatingPlugin class VersioningPlugin : DokkaPlugin() { - val versioningHandler by extensionPoint() + val versioningStorage by extensionPoint() val versionsNavigationCreator by extensionPoint() val versionsOrdering by extensionPoint() private val dokkaBase by lazy { plugin() } private val templatingPlugin by lazy { plugin() } - val defaultVersioningHandler by extending { - versioningHandler providing ::DefaultVersioningHandler + val defaultVersioningStorage by extending { + versioningStorage providing ::DefaultVersioningStorage } val defaultVersioningNavigationCreator by extending { versionsNavigationCreator providing ::HtmlVersionsNavigationCreator } val replaceVersionCommandHandler by extending { - templatingPlugin.directiveBasedCommandHandlers providing ::ReplaceVersionCommandHandler + templatingPlugin.directiveBasedCommandHandlers providing ::ReplaceVersionCommandHandler override templatingPlugin.replaceVersionCommandHandler } val resolveLinkConsumer by extending { - dokkaBase.immediateHtmlCommandConsumer providing ::ReplaceVersionCommandConsumer + dokkaBase.immediateHtmlCommandConsumer providing ::ReplaceVersionCommandConsumer override dokkaBase.replaceVersionConsumer } val cssStyleInstaller by extending { - dokkaBase.htmlPreprocessors with MultiModuleStylesInstaller order { after(dokkaBase.assetsInstaller) } + dokkaBase.htmlPreprocessors providing ::MultiModuleStylesInstaller order { + after(dokkaBase.assetsInstaller) + before(dokkaBase.customResourceInstaller) + } + } + val notFoundPageInstaller by extending { + dokkaBase.htmlPreprocessors providing ::NotFoundPageInstaller order { + after(dokkaBase.assetsInstaller) + before(dokkaBase.customResourceInstaller) + } applyIf { !delayTemplateSubstitution } } val versionsDefaultOrdering by extending { versionsOrdering providing { ctx -> @@ -36,4 +46,7 @@ class VersioningPlugin : DokkaPlugin() { } ?: SemVerVersionOrdering() } } + val previousDocumentationCopyPostAction by extending { + postActions providing ::DefaultPreviousDocumentationCopyPostAction applyIf { !delayTemplateSubstitution } + } } \ No newline at end of file diff --git a/plugins/versioning/src/main/kotlin/versioning/VersioningStorage.kt b/plugins/versioning/src/main/kotlin/versioning/VersioningStorage.kt new file mode 100644 index 0000000000..6e1dd7ca8a --- /dev/null +++ b/plugins/versioning/src/main/kotlin/versioning/VersioningStorage.kt @@ -0,0 +1,65 @@ +package org.jetbrains.dokka.versioning + +import com.fasterxml.jackson.annotation.JsonProperty +import com.fasterxml.jackson.databind.ObjectMapper +import com.fasterxml.jackson.module.kotlin.readValue +import org.jetbrains.dokka.plugability.DokkaContext +import org.jetbrains.dokka.plugability.configuration +import java.io.File + +data class VersionDirs(val src: File, val dst: File) +data class CurrentVersion(val name: String, val dir: File) + +interface VersioningStorage { + val previousVersions: Map + val currentVersion: CurrentVersion + fun createVersionFile() +} + +typealias VersionId = String + +class DefaultVersioningStorage(val context: DokkaContext) : VersioningStorage { + + private val mapper = ObjectMapper() + private val configuration = configuration(context) + + override val previousVersions: Map by lazy { + configuration?.let { versionsConfiguration -> + getPreviousVersions(versionsConfiguration.allOlderVersions(), context.configuration.outputDir) + } ?: emptyMap() + } + + override val currentVersion: CurrentVersion by lazy { + configuration?.let { versionsConfiguration -> + CurrentVersion(versionsConfiguration.versionFromConfigurationOrModule(context), + context.configuration.outputDir) + }?: CurrentVersion(context.configuration.moduleVersion.orEmpty(), context.configuration.outputDir) + } + + override fun createVersionFile() { + mapper.writeValue( + currentVersion.dir.resolve(VersioningConfiguration.VERSIONS_FILE), + Version(currentVersion.name) + ) + } + + private fun getPreviousVersions(olderVersions: List, output: File): Map = + versionsFrom(olderVersions).associate { (key, srcDir) -> + key to VersionDirs(srcDir, output.resolve(VersioningConfiguration.OLDER_VERSIONS_DIR).resolve(key)) + } + + private fun versionsFrom(olderVersions: List) = + olderVersions.mapNotNull { versionDir -> + versionDir.listFiles { _, name -> name == VersioningConfiguration.VERSIONS_FILE }?.firstOrNull() + ?.let { file -> + val versionsContent = mapper.readValue(file) + Pair(versionsContent.version, versionDir) + }.also { + if (it == null) context.logger.warn("Failed to find versions file named ${VersioningConfiguration.VERSIONS_FILE} in $versionDir") + } + } + + private data class Version( + @JsonProperty("version") val version: String, + ) +} diff --git a/plugins/versioning/src/main/kotlin/versioning/VersionsNavigationCreator.kt b/plugins/versioning/src/main/kotlin/versioning/VersionsNavigationCreator.kt index 76653d4720..876b3ccfab 100644 --- a/plugins/versioning/src/main/kotlin/versioning/VersionsNavigationCreator.kt +++ b/plugins/versioning/src/main/kotlin/versioning/VersionsNavigationCreator.kt @@ -1,53 +1,86 @@ package org.jetbrains.dokka.versioning import kotlinx.html.a -import kotlinx.html.button import kotlinx.html.div -import kotlinx.html.i import kotlinx.html.stream.appendHTML +import org.jetbrains.dokka.base.renderers.html.strike 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.utilities.urlEncoded import java.io.File -import java.nio.file.Files.isDirectory -import java.nio.file.Path interface VersionsNavigationCreator { - operator fun invoke(): String operator fun invoke(output: File): String } -class HtmlVersionsNavigationCreator(val context: DokkaContext) : VersionsNavigationCreator { +class HtmlVersionsNavigationCreator(private val context: DokkaContext) : VersionsNavigationCreator { - private val versioningHandler by lazy { context.plugin().querySingle { versioningHandler } } + private val versioningStorage by lazy { context.plugin().querySingle { versioningStorage } } private val versionsOrdering by lazy { context.plugin().querySingle { versionsOrdering } } - override fun invoke(): String = - versioningHandler.currentVersion()?.let { invoke(it) }.orEmpty() + private val isOnlyOnRootPage = + configuration(context)?.renderVersionsNavigationOnAllPages == false + + private val versions: Map by lazy { + versioningStorage.previousVersions.map { (k, v) -> k to v.dst }.toMap() + + (versioningStorage.currentVersion.name to versioningStorage.currentVersion.dir) + } override fun invoke(output: File): String { + if (versions.size == 1) { + return versioningStorage.currentVersion.name + } val position = output.takeIf { it.isDirectory } ?: output.parentFile - return versioningHandler.getVersions() + if (isOnlyOnRootPage) { + getActiveVersion(position)?.takeIf { + it.value == versioningStorage.currentVersion.dir + && it.value != position + }?.also { return@invoke it.key } + } + return versions .let { versions -> versionsOrdering.order(versions.keys.toList()).map { it to versions[it] } } .takeIf { it.isNotEmpty() } - ?.let { versions -> + ?.let { orderedVersions -> StringBuilder().appendHTML().div(classes = "versions-dropdown") { - button(classes = "versions-dropdown-button") { - versions.first { (_, versionLocation) -> versionLocation?.absolutePath == position.absolutePath } - .let { (version, _) -> - text(version) - } - i(classes = "fa fa-caret-down") + val activeVersion = getActiveVersion(position) + val relativePosition: String = activeVersion?.value?.let { output.toRelativeString(it) } ?: "index.html" + div(classes = "versions-dropdown-button") { + activeVersion?.key?.let { text(it) } } div(classes = "versions-dropdown-data") { - versions.forEach { (version, path) -> - a(href = path?.resolve("index.html")?.toRelativeString(position)) { - text(version) + orderedVersions.forEach { (version, path) -> + if (version == activeVersion?.key) { + a(href = output.name) { text(version) } + } else { + val isExistsFile = + if (version == versioningStorage.currentVersion.name) + path?.resolve(relativePosition)?.exists() == true + else + versioningStorage.previousVersions[version]?.src?.resolve(relativePosition) + ?.exists() == true + + val absolutePath = + if (isExistsFile) + path?.resolve(relativePosition) + else + versioningStorage.currentVersion.dir.resolve("not-found-version.html") + + a(href = absolutePath?.toRelativeString(position) + + if (!isExistsFile) "?v=" + version.urlEncoded() else "") { + text(version) + } } } } }.toString() }.orEmpty() } + + private fun getActiveVersion(position: File) = + versions.minByOrNull { (_, versionLocation) -> + versionLocation.let { position.toRelativeString(it).length } + } } \ No newline at end of file diff --git a/plugins/versioning/src/main/kotlin/versioning/htmlPreprocessors.kt b/plugins/versioning/src/main/kotlin/versioning/htmlPreprocessors.kt index 5852ba9e82..94400898af 100644 --- a/plugins/versioning/src/main/kotlin/versioning/htmlPreprocessors.kt +++ b/plugins/versioning/src/main/kotlin/versioning/htmlPreprocessors.kt @@ -3,22 +3,36 @@ package org.jetbrains.dokka.versioning import org.jetbrains.dokka.pages.RendererSpecificResourcePage import org.jetbrains.dokka.pages.RenderingStrategy import org.jetbrains.dokka.pages.RootPageNode +import org.jetbrains.dokka.plugability.DokkaContext import org.jetbrains.dokka.transformers.pages.PageTransformer -object MultiModuleStylesInstaller : PageTransformer { +class MultiModuleStylesInstaller(private val dokkaContext: DokkaContext) : PageTransformer { private val stylesPages = listOf( "styles/multimodule.css", ) override fun invoke(input: RootPageNode): RootPageNode = - input.modified( - children = input.children + stylesPages.toRenderSpecificResourcePage() - ).transformContentPagesTree { + input.let { root -> + if (dokkaContext.configuration.delayTemplateSubstitution) root + else root.modified(children = input.children + stylesPages.toRenderSpecificResourcePage()) + }.transformContentPagesTree { it.modified( embeddedResources = it.embeddedResources + stylesPages ) } } +class NotFoundPageInstaller(private val dokkaContext: DokkaContext) : PageTransformer { + private val notFoundPage = listOf( + "not-found-version.html", + ) + + override fun invoke(input: RootPageNode): RootPageNode = + input.let { root -> + if (dokkaContext.configuration.delayTemplateSubstitution) root + else root.modified(children = input.children + notFoundPage.toRenderSpecificResourcePage()) + } +} + private fun List.toRenderSpecificResourcePage(): List = map { RendererSpecificResourcePage(it, emptyList(), RenderingStrategy.Copy("/dokka/$it")) } diff --git a/plugins/versioning/src/main/resources/dokka/not-found-version.html b/plugins/versioning/src/main/resources/dokka/not-found-version.html new file mode 100644 index 0000000000..259a489312 --- /dev/null +++ b/plugins/versioning/src/main/resources/dokka/not-found-version.html @@ -0,0 +1,189 @@ + + + + + Unavailable page + + + + + + + + + + + NOT + FOUND + + + + + + + + + + + + + + + + + +
+
+
+ +
+
+

uh-oh!

+
You are requesting a page that not + available in documentation version +
+
+
+
+ + \ No newline at end of file diff --git a/plugins/versioning/src/main/resources/dokka/styles/multimodule.css b/plugins/versioning/src/main/resources/dokka/styles/multimodule.css index 4334d759ad..541e2eb921 100644 --- a/plugins/versioning/src/main/resources/dokka/styles/multimodule.css +++ b/plugins/versioning/src/main/resources/dokka/styles/multimodule.css @@ -8,28 +8,46 @@ padding: 5px; } -.versions-dropdown-button:hover, -.versions-dropdown-button:focus { - background-color: #f1f1f1; +.versions-dropdown-button::after { + content: ''; + -webkit-mask: url("../images/arrow_down.svg") no-repeat 50% 50%; + mask: url("../images/arrow_down.svg") no-repeat 50% 50%; + mask-size: auto; + -webkit-mask-size: cover; + mask-size: cover; + background-color: #fff; + display: inline-block; + position: relative; + top: 2px; + transform: rotate(90deg); + width: 24px; + height: 16px; } .versions-dropdown-data { display: none; position: absolute; - background-color: #f1f1f1; + background-color: #27282c; + border-style: solid; + border-width: 1px; + border-color: hsla(0,0%,100%,.6); box-shadow: 0px 8px 16px 0px rgba(0,0,0,0.2); z-index: 1; + overflow-y: auto; + max-height: 200px; + min-width: 50px; + } .versions-dropdown-data a { padding: 5px; + padding-right: 18px; text-decoration: none; display: block; - color: black; } .versions-dropdown-data a:hover { - background-color: #ddd + background-color: hsla(0,0%,100%,.1) } .versions-dropdown:hover .versions-dropdown-data {