diff options
Diffstat (limited to 'dokka-subprojects/plugin-templating')
24 files changed, 1397 insertions, 0 deletions
diff --git a/dokka-subprojects/plugin-templating/README.md b/dokka-subprojects/plugin-templating/README.md new file mode 100644 index 00000000..92eee3e2 --- /dev/null +++ b/dokka-subprojects/plugin-templating/README.md @@ -0,0 +1,4 @@ +# Templating plugin + +Templating plugin is used internally by Dokka and HTML format in particular to help handle substitution +commands, resolve relative links and process templates. diff --git a/dokka-subprojects/plugin-templating/api/plugin-templating.api b/dokka-subprojects/plugin-templating/api/plugin-templating.api new file mode 100644 index 00000000..aedd8ef3 --- /dev/null +++ b/dokka-subprojects/plugin-templating/api/plugin-templating.api @@ -0,0 +1,185 @@ +public abstract class org/jetbrains/dokka/allModulesPage/templates/BaseJsonNavigationTemplateProcessingStrategy : org/jetbrains/dokka/templates/TemplateProcessingStrategy { + public fun <init> (Lorg/jetbrains/dokka/plugability/DokkaContext;)V + public fun canProcess (Ljava/io/File;)Z + public fun finish (Ljava/io/File;)V + public final fun getContext ()Lorg/jetbrains/dokka/plugability/DokkaContext; + public abstract fun getNavigationFileNameWithoutExtension ()Ljava/lang/String; + public abstract fun getPath ()Ljava/lang/String; + public fun process (Ljava/io/File;Ljava/io/File;Lorg/jetbrains/dokka/DokkaConfiguration$DokkaModuleDescription;)Z +} + +public final class org/jetbrains/dokka/allModulesPage/templates/PackageListProcessingStrategy : org/jetbrains/dokka/templates/TemplateProcessingStrategy { + public fun <init> (Lorg/jetbrains/dokka/plugability/DokkaContext;)V + public fun finish (Ljava/io/File;)V + public final fun getContext ()Lorg/jetbrains/dokka/plugability/DokkaContext; + public fun process (Ljava/io/File;Ljava/io/File;Lorg/jetbrains/dokka/DokkaConfiguration$DokkaModuleDescription;)Z +} + +public final class org/jetbrains/dokka/allModulesPage/templates/PagesSearchTemplateStrategy : org/jetbrains/dokka/allModulesPage/templates/BaseJsonNavigationTemplateProcessingStrategy { + public fun <init> (Lorg/jetbrains/dokka/plugability/DokkaContext;)V + public final fun getDokkaContext ()Lorg/jetbrains/dokka/plugability/DokkaContext; + public fun getNavigationFileNameWithoutExtension ()Ljava/lang/String; + public fun getPath ()Ljava/lang/String; +} + +public final class org/jetbrains/dokka/templates/AddToNavigationCommandHandler : org/jetbrains/dokka/templates/CommandHandler { + public fun <init> (Lorg/jetbrains/dokka/plugability/DokkaContext;)V + public fun canHandle (Lorg/jetbrains/dokka/base/templating/Command;)Z + public fun finish (Ljava/io/File;)V + public final fun getContext ()Lorg/jetbrains/dokka/plugability/DokkaContext; + public fun handleCommand (Lorg/jsoup/nodes/Element;Lorg/jetbrains/dokka/base/templating/Command;Ljava/io/File;Ljava/io/File;)V + public fun handleCommandAsComment (Lorg/jetbrains/dokka/base/templating/Command;Ljava/util/List;Ljava/io/File;Ljava/io/File;)V + public fun handleCommandAsTag (Lorg/jetbrains/dokka/base/templating/Command;Lorg/jsoup/nodes/Element;Ljava/io/File;Ljava/io/File;)V +} + +public abstract interface class org/jetbrains/dokka/templates/CommandHandler { + public abstract fun canHandle (Lorg/jetbrains/dokka/base/templating/Command;)Z + public abstract fun finish (Ljava/io/File;)V + public abstract fun handleCommand (Lorg/jsoup/nodes/Element;Lorg/jetbrains/dokka/base/templating/Command;Ljava/io/File;Ljava/io/File;)V + public abstract fun handleCommandAsComment (Lorg/jetbrains/dokka/base/templating/Command;Ljava/util/List;Ljava/io/File;Ljava/io/File;)V + public abstract fun handleCommandAsTag (Lorg/jetbrains/dokka/base/templating/Command;Lorg/jsoup/nodes/Element;Ljava/io/File;Ljava/io/File;)V +} + +public final class org/jetbrains/dokka/templates/CommandHandler$DefaultImpls { + public static fun finish (Lorg/jetbrains/dokka/templates/CommandHandler;Ljava/io/File;)V + public static fun handleCommand (Lorg/jetbrains/dokka/templates/CommandHandler;Lorg/jsoup/nodes/Element;Lorg/jetbrains/dokka/base/templating/Command;Ljava/io/File;Ljava/io/File;)V + public static fun handleCommandAsComment (Lorg/jetbrains/dokka/templates/CommandHandler;Lorg/jetbrains/dokka/base/templating/Command;Ljava/util/List;Ljava/io/File;Ljava/io/File;)V + public static fun handleCommandAsTag (Lorg/jetbrains/dokka/templates/CommandHandler;Lorg/jetbrains/dokka/base/templating/Command;Lorg/jsoup/nodes/Element;Ljava/io/File;Ljava/io/File;)V +} + +public final class org/jetbrains/dokka/templates/DefaultMultiModuleTemplateProcessor : org/jetbrains/dokka/templates/MultiModuleTemplateProcessor { + public fun <init> (Lorg/jetbrains/dokka/plugability/DokkaContext;)V + public final fun getContext ()Lorg/jetbrains/dokka/plugability/DokkaContext; + public fun process (Lorg/jetbrains/dokka/pages/RootPageNode;)V +} + +public final class org/jetbrains/dokka/templates/DefaultSubmoduleTemplateProcessor : org/jetbrains/dokka/templates/SubmoduleTemplateProcessor { + public fun <init> (Lorg/jetbrains/dokka/plugability/DokkaContext;)V + public fun process (Ljava/util/List;)Lorg/jetbrains/dokka/templates/TemplatingResult; +} + +public final class org/jetbrains/dokka/templates/DirectiveBasedHtmlTemplateProcessingStrategy : org/jetbrains/dokka/templates/TemplateProcessingStrategy { + public fun <init> (Lorg/jetbrains/dokka/plugability/DokkaContext;)V + public fun finish (Ljava/io/File;)V + public final fun handleCommandAsComment (Lorg/jetbrains/dokka/base/templating/Command;Ljava/util/List;Ljava/io/File;Ljava/io/File;)V + public final fun handleCommandAsTag (Lorg/jsoup/nodes/Element;Lorg/jetbrains/dokka/base/templating/Command;Ljava/io/File;Ljava/io/File;)V + public fun process (Ljava/io/File;Ljava/io/File;Lorg/jetbrains/dokka/DokkaConfiguration$DokkaModuleDescription;)Z +} + +public final class org/jetbrains/dokka/templates/FallbackTemplateProcessingStrategy : org/jetbrains/dokka/templates/TemplateProcessingStrategy { + public fun <init> ()V + public fun finish (Ljava/io/File;)V + public fun process (Ljava/io/File;Ljava/io/File;Lorg/jetbrains/dokka/DokkaConfiguration$DokkaModuleDescription;)Z +} + +public abstract interface class org/jetbrains/dokka/templates/MultiModuleTemplateProcessor : org/jetbrains/dokka/templates/TemplateProcessor { + public abstract fun process (Lorg/jetbrains/dokka/pages/RootPageNode;)V +} + +public final class org/jetbrains/dokka/templates/PathToRootSubstitutor : org/jetbrains/dokka/templates/Substitutor { + public fun <init> (Lorg/jetbrains/dokka/plugability/DokkaContext;)V + public fun trySubstitute (Lorg/jetbrains/dokka/templates/TemplatingContext;Lkotlin/text/MatchResult;)Ljava/lang/String; +} + +public abstract interface class org/jetbrains/dokka/templates/SubmoduleTemplateProcessor : org/jetbrains/dokka/templates/TemplateProcessor { + public abstract fun process (Ljava/util/List;)Lorg/jetbrains/dokka/templates/TemplatingResult; +} + +public final class org/jetbrains/dokka/templates/SubstitutionCommandHandler : org/jetbrains/dokka/templates/CommandHandler { + public fun <init> (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 fun handleCommandAsComment (Lorg/jetbrains/dokka/base/templating/Command;Ljava/util/List;Ljava/io/File;Ljava/io/File;)V + public fun handleCommandAsTag (Lorg/jetbrains/dokka/base/templating/Command;Lorg/jsoup/nodes/Element;Ljava/io/File;Ljava/io/File;)V +} + +public abstract interface class org/jetbrains/dokka/templates/Substitutor { + public abstract fun trySubstitute (Lorg/jetbrains/dokka/templates/TemplatingContext;Lkotlin/text/MatchResult;)Ljava/lang/String; +} + +public abstract interface class org/jetbrains/dokka/templates/TemplateProcessingStrategy { + public abstract fun finish (Ljava/io/File;)V + public abstract fun process (Ljava/io/File;Ljava/io/File;Lorg/jetbrains/dokka/DokkaConfiguration$DokkaModuleDescription;)Z +} + +public final class org/jetbrains/dokka/templates/TemplateProcessingStrategy$DefaultImpls { + public static fun finish (Lorg/jetbrains/dokka/templates/TemplateProcessingStrategy;Ljava/io/File;)V +} + +public abstract interface class org/jetbrains/dokka/templates/TemplateProcessor { +} + +public final class org/jetbrains/dokka/templates/TemplatingContext { + public fun <init> (Ljava/io/File;Ljava/io/File;Ljava/util/List;Lorg/jetbrains/dokka/base/templating/Command;)V + public final fun component1 ()Ljava/io/File; + public final fun component2 ()Ljava/io/File; + public final fun component3 ()Ljava/util/List; + public final fun component4 ()Lorg/jetbrains/dokka/base/templating/Command; + public final fun copy (Ljava/io/File;Ljava/io/File;Ljava/util/List;Lorg/jetbrains/dokka/base/templating/Command;)Lorg/jetbrains/dokka/templates/TemplatingContext; + public static synthetic fun copy$default (Lorg/jetbrains/dokka/templates/TemplatingContext;Ljava/io/File;Ljava/io/File;Ljava/util/List;Lorg/jetbrains/dokka/base/templating/Command;ILjava/lang/Object;)Lorg/jetbrains/dokka/templates/TemplatingContext; + public fun equals (Ljava/lang/Object;)Z + public final fun getBody ()Ljava/util/List; + public final fun getCommand ()Lorg/jetbrains/dokka/base/templating/Command; + public final fun getInput ()Ljava/io/File; + public final fun getOutput ()Ljava/io/File; + public fun hashCode ()I + public fun toString ()Ljava/lang/String; +} + +public final class org/jetbrains/dokka/templates/TemplatingPlugin : org/jetbrains/dokka/plugability/DokkaPlugin { + public fun <init> ()V + public final fun getAddToNavigationCommandHandler ()Lorg/jetbrains/dokka/plugability/Extension; + public final fun getDefaultMultiModuleTemplateProcessor ()Lorg/jetbrains/dokka/plugability/Extension; + public final fun getDefaultSubmoduleTemplateProcessor ()Lorg/jetbrains/dokka/plugability/Extension; + public final fun getDirectiveBasedCommandHandlers ()Lorg/jetbrains/dokka/plugability/ExtensionPoint; + public final fun getDirectiveBasedHtmlTemplateProcessingStrategy ()Lorg/jetbrains/dokka/plugability/Extension; + public final fun getFallbackProcessingStrategy ()Lorg/jetbrains/dokka/plugability/Extension; + public final fun getMultimoduleTemplateProcessor ()Lorg/jetbrains/dokka/plugability/ExtensionPoint; + public final fun getPackageListProcessingStrategy ()Lorg/jetbrains/dokka/plugability/Extension; + 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; + public final fun getSubstitutor ()Lorg/jetbrains/dokka/plugability/ExtensionPoint; + public final fun getTemplateProcessingStrategy ()Lorg/jetbrains/dokka/plugability/ExtensionPoint; +} + +public final class org/jetbrains/dokka/templates/TemplatingResult { + public fun <init> ()V + public fun <init> (Ljava/util/List;)V + public synthetic fun <init> (Ljava/util/List;ILkotlin/jvm/internal/DefaultConstructorMarker;)V + public final fun component1 ()Ljava/util/List; + public final fun copy (Ljava/util/List;)Lorg/jetbrains/dokka/templates/TemplatingResult; + public static synthetic fun copy$default (Lorg/jetbrains/dokka/templates/TemplatingResult;Ljava/util/List;ILjava/lang/Object;)Lorg/jetbrains/dokka/templates/TemplatingResult; + public fun equals (Ljava/lang/Object;)Z + public final fun getModules ()Ljava/util/List; + public fun hashCode ()I + public final fun plus (Lorg/jetbrains/dokka/templates/TemplatingResult;)Lorg/jetbrains/dokka/templates/TemplatingResult; + public fun toString ()Ljava/lang/String; +} + +public final class templates/ProjectNameSubstitutor : org/jetbrains/dokka/templates/Substitutor { + public fun <init> (Lorg/jetbrains/dokka/plugability/DokkaContext;)V + 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 <init> (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 fun handleCommandAsComment (Lorg/jetbrains/dokka/base/templating/Command;Ljava/util/List;Ljava/io/File;Ljava/io/File;)V + public fun handleCommandAsTag (Lorg/jetbrains/dokka/base/templating/Command;Lorg/jsoup/nodes/Element;Ljava/io/File;Ljava/io/File;)V +} + +public final class templates/SourcesetDependencyProcessingStrategy : org/jetbrains/dokka/templates/TemplateProcessingStrategy { + public fun <init> (Lorg/jetbrains/dokka/plugability/DokkaContext;)V + public fun finish (Ljava/io/File;)V + public final fun getContext ()Lorg/jetbrains/dokka/plugability/DokkaContext; + public fun process (Ljava/io/File;Ljava/io/File;Lorg/jetbrains/dokka/DokkaConfiguration$DokkaModuleDescription;)Z +} + diff --git a/dokka-subprojects/plugin-templating/build.gradle.kts b/dokka-subprojects/plugin-templating/build.gradle.kts new file mode 100644 index 00000000..e92e7b50 --- /dev/null +++ b/dokka-subprojects/plugin-templating/build.gradle.kts @@ -0,0 +1,30 @@ +/* + * Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license. + */ + +import dokkabuild.overridePublicationArtifactId + +plugins { + id("dokkabuild.kotlin-jvm") + id("dokkabuild.publish-jvm") +} + +overridePublicationArtifactId("templating-plugin") + +dependencies { + compileOnly(projects.dokkaSubprojects.dokkaCore) + + api(libs.jsoup) + + implementation(projects.dokkaSubprojects.pluginBase) + + implementation(kotlin("reflect")) + implementation(libs.kotlinx.coroutines.core) + + testImplementation(kotlin("test")) + testImplementation(libs.junit.jupiterParams) + + testImplementation(projects.dokkaSubprojects.pluginBaseTestUtils) + testImplementation(projects.dokkaSubprojects.coreTestApi) + testImplementation(libs.kotlinx.html) +} diff --git a/dokka-subprojects/plugin-templating/src/main/kotlin/org/jetbrains/dokka/allModulesPage/templates/JsonElementBasedTemplateProcessingStrategy.kt b/dokka-subprojects/plugin-templating/src/main/kotlin/org/jetbrains/dokka/allModulesPage/templates/JsonElementBasedTemplateProcessingStrategy.kt new file mode 100644 index 00000000..8c6cee03 --- /dev/null +++ b/dokka-subprojects/plugin-templating/src/main/kotlin/org/jetbrains/dokka/allModulesPage/templates/JsonElementBasedTemplateProcessingStrategy.kt @@ -0,0 +1,67 @@ +/* + * Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license. + */ + +package org.jetbrains.dokka.allModulesPage.templates + +import org.jetbrains.dokka.DokkaConfiguration.DokkaModuleDescription +import org.jetbrains.dokka.base.renderers.html.SearchRecord +import org.jetbrains.dokka.base.templating.AddToSearch +import org.jetbrains.dokka.base.templating.parseJson +import org.jetbrains.dokka.base.templating.toJsonString +import org.jetbrains.dokka.plugability.DokkaContext +import org.jetbrains.dokka.templates.TemplateProcessingStrategy +import java.io.File +import java.util.concurrent.ConcurrentHashMap + +public abstract class BaseJsonNavigationTemplateProcessingStrategy( + public val context: DokkaContext +) : TemplateProcessingStrategy { + public abstract val navigationFileNameWithoutExtension: String + public abstract val path: String + + private val fragments = ConcurrentHashMap<String, List<SearchRecord>>() + + public open fun canProcess(file: File): Boolean = + file.extension == "json" && file.nameWithoutExtension == navigationFileNameWithoutExtension + + override fun process(input: File, output: File, moduleContext: DokkaModuleDescription?): Boolean { + val canProcess = canProcess(input) + if (canProcess) { + runCatching { parseJson<AddToSearch>(input.readText()) }.getOrNull()?.let { command -> + moduleContext?.relativePathToOutputDirectory + ?.relativeToOrSelf(context.configuration.outputDir) + ?.let { key -> + fragments[key.toString()] = command.elements + } + } ?: fallbackToCopy(input, output) + } + return canProcess + } + + override fun finish(output: File) { + if (fragments.isNotEmpty()) { + val content = toJsonString(fragments.entries.flatMap { (moduleName, navigation) -> + navigation.map { it.withResolvedLocation(moduleName) } + }) + output.resolve(path).mkdirs() + output.resolve("$path/$navigationFileNameWithoutExtension.json").writeText(content) + } + } + + private fun fallbackToCopy(input: File, output: File) { + context.logger.warn("Falling back to just copying ${input.name} file even though it should have been processed") + input.copyTo(output) + } + + private fun SearchRecord.withResolvedLocation(moduleName: String): SearchRecord = + copy(location = "$moduleName/$location") + +} + +public class PagesSearchTemplateStrategy( + public val dokkaContext: DokkaContext +) : BaseJsonNavigationTemplateProcessingStrategy(dokkaContext) { + override val navigationFileNameWithoutExtension: String = "pages" + override val path: String = "scripts" +} diff --git a/dokka-subprojects/plugin-templating/src/main/kotlin/org/jetbrains/dokka/allModulesPage/templates/PackageListProcessingStrategy.kt b/dokka-subprojects/plugin-templating/src/main/kotlin/org/jetbrains/dokka/allModulesPage/templates/PackageListProcessingStrategy.kt new file mode 100644 index 00000000..4da45e3f --- /dev/null +++ b/dokka-subprojects/plugin-templating/src/main/kotlin/org/jetbrains/dokka/allModulesPage/templates/PackageListProcessingStrategy.kt @@ -0,0 +1,56 @@ +/* + * Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license. + */ + +package org.jetbrains.dokka.allModulesPage.templates + +import org.jetbrains.dokka.DokkaConfiguration.DokkaModuleDescription +import org.jetbrains.dokka.base.renderers.PackageListService +import org.jetbrains.dokka.base.resolvers.shared.PackageList +import org.jetbrains.dokka.base.resolvers.shared.PackageList.Companion.PACKAGE_LIST_NAME +import org.jetbrains.dokka.plugability.DokkaContext +import org.jetbrains.dokka.templates.TemplateProcessingStrategy +import java.io.File + +public class PackageListProcessingStrategy( + public val context: DokkaContext +) : TemplateProcessingStrategy { + private val fragments = mutableSetOf<PackageList>() + + private fun canProcess(file: File, moduleContext: DokkaModuleDescription?): Boolean = + file.extension.isBlank() && file.nameWithoutExtension == PACKAGE_LIST_NAME && moduleContext != null + + override fun process(input: File, output: File, moduleContext: DokkaModuleDescription?): Boolean { + val canProcess = canProcess(input, moduleContext) + if (canProcess) { + val packageList = PackageList.load(input.toURI().toURL(), 8, true) + val moduleFilename = moduleContext?.name?.let { "$it/" } + packageList?.copy( + modules = mapOf(moduleContext?.name.orEmpty() to packageList.modules.getOrDefault(PackageList.SINGLE_MODULE_NAME, emptySet())), + locations = packageList.locations.entries.associate { it.key to "$moduleFilename${it.value}" } + )?.let { fragments.add(it) } ?: fallbackToCopy(input, output) + } + return canProcess + } + + override fun finish(output: File) { + if (fragments.isNotEmpty()) { + val linkFormat = fragments.first().linkFormat + + if (!fragments.all { it.linkFormat == linkFormat }) { + context.logger.error("Link format is inconsistent between modules: " + fragments.joinToString { it.linkFormat.formatName } ) + } + + val locations: Map<String, String> = fragments.map { it.locations }.fold(emptyMap()) { acc, el -> acc + el } + val modules: Map<String, Set<String>> = fragments.map { it.modules }.fold(emptyMap()) { acc, el -> acc + el } + val mergedPackageList = PackageListService.renderPackageList(locations, modules, linkFormat.formatName, linkFormat.linkExtension) + output.mkdirs() + output.resolve(PACKAGE_LIST_NAME).writeText(mergedPackageList) + } + } + + private fun fallbackToCopy(input: File, output: File) { + context.logger.warn("Falling back to just copying ${input.name} file even though it should have been processed") + input.copyTo(output) + } +} diff --git a/dokka-subprojects/plugin-templating/src/main/kotlin/org/jetbrains/dokka/templates/AddToNavigationCommandHandler.kt b/dokka-subprojects/plugin-templating/src/main/kotlin/org/jetbrains/dokka/templates/AddToNavigationCommandHandler.kt new file mode 100644 index 00000000..78c6c684 --- /dev/null +++ b/dokka-subprojects/plugin-templating/src/main/kotlin/org/jetbrains/dokka/templates/AddToNavigationCommandHandler.kt @@ -0,0 +1,62 @@ +/* + * Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license. + */ + +package org.jetbrains.dokka.templates + +import org.jetbrains.dokka.base.templating.AddToNavigationCommand +import org.jetbrains.dokka.base.templating.Command +import org.jetbrains.dokka.plugability.DokkaContext +import org.jsoup.nodes.Attributes +import org.jsoup.nodes.Element +import org.jsoup.parser.Tag +import java.io.File +import java.nio.file.Files +import java.util.concurrent.ConcurrentHashMap + +public class AddToNavigationCommandHandler( + public val context: DokkaContext +) : CommandHandler { + private val navigationFragments = ConcurrentHashMap<String, Element>() + + override fun handleCommandAsTag(command: Command, body: Element, input: File, output: File) { + command as AddToNavigationCommand + context.configuration.modules.find { it.name == command.moduleName } + ?.relativePathToOutputDirectory + ?.relativeToOrSelf(context.configuration.outputDir) + ?.let { key -> navigationFragments[key.toString()] = body } + } + + override fun canHandle(command: Command): Boolean = command is AddToNavigationCommand + + override fun finish(output: File) { + if (navigationFragments.isNotEmpty()) { + val attributes = Attributes().apply { + put("class", "sideMenu") + } + val node = Element(Tag.valueOf("div"), "", attributes) + navigationFragments.entries.sortedBy { it.key }.forEach { (moduleName, command) -> + command.select("a").forEach { a -> + a.attr("href").also { a.attr("href", "${moduleName}/${it}") } + } + command.childNodes().toList().forEachIndexed { index, child -> + if (index == 0) { + child.attr("id", "$moduleName-nav-submenu") + } + node.appendChild(child) + } + } + + Files.write(output.resolve("navigation.html").toPath(), listOf(node.outerHtml())) + node.select("a").forEach { a -> + a.attr("href").also { a.attr("href", "../${it}") } + } + navigationFragments.keys.forEach { + Files.write( + output.resolve(it).resolve("navigation.html").toPath(), + listOf(node.outerHtml()) + ) + } + } + } +} diff --git a/dokka-subprojects/plugin-templating/src/main/kotlin/org/jetbrains/dokka/templates/CommandHandler.kt b/dokka-subprojects/plugin-templating/src/main/kotlin/org/jetbrains/dokka/templates/CommandHandler.kt new file mode 100644 index 00000000..c06d52c3 --- /dev/null +++ b/dokka-subprojects/plugin-templating/src/main/kotlin/org/jetbrains/dokka/templates/CommandHandler.kt @@ -0,0 +1,25 @@ +/* + * Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license. + */ + +package org.jetbrains.dokka.templates + +import org.jetbrains.dokka.base.templating.Command +import org.jsoup.nodes.Element +import org.jsoup.nodes.Node +import java.io.File + + +public interface CommandHandler { + @Deprecated("This was renamed to handleCommandAsTag", ReplaceWith("handleCommandAsTag(command, element, input, output)")) + public fun handleCommand(element: Element, command: Command, input: File, output: File) { } + + @Suppress("DEPRECATION") + public fun handleCommandAsTag(command: Command, body: Element, input: File, output: File) { + handleCommand(body, command, input, output) + } + public fun handleCommandAsComment(command: Command, body: List<Node>, input: File, output: File) { } + public fun canHandle(command: Command): Boolean + public fun finish(output: File) {} +} + diff --git a/dokka-subprojects/plugin-templating/src/main/kotlin/org/jetbrains/dokka/templates/DirectiveBasedTemplateProcessing.kt b/dokka-subprojects/plugin-templating/src/main/kotlin/org/jetbrains/dokka/templates/DirectiveBasedTemplateProcessing.kt new file mode 100644 index 00000000..c36f2834 --- /dev/null +++ b/dokka-subprojects/plugin-templating/src/main/kotlin/org/jetbrains/dokka/templates/DirectiveBasedTemplateProcessing.kt @@ -0,0 +1,102 @@ +/* + * Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license. + */ + +package org.jetbrains.dokka.templates + +import org.jetbrains.dokka.DokkaConfiguration +import org.jetbrains.dokka.base.renderers.html.TEMPLATE_COMMAND_BEGIN_BORDER +import org.jetbrains.dokka.base.renderers.html.TEMPLATE_COMMAND_END_BORDER +import org.jetbrains.dokka.base.renderers.html.TEMPLATE_COMMAND_SEPARATOR +import org.jetbrains.dokka.base.templating.Command +import org.jetbrains.dokka.base.templating.parseJson +import org.jetbrains.dokka.plugability.DokkaContext +import org.jetbrains.dokka.plugability.plugin +import org.jetbrains.dokka.plugability.query +import org.jsoup.Jsoup +import org.jsoup.nodes.Comment +import org.jsoup.nodes.Element +import org.jsoup.nodes.Node +import org.jsoup.nodes.TextNode +import java.io.File +import java.nio.file.Files + +public class DirectiveBasedHtmlTemplateProcessingStrategy(private val context: DokkaContext) : TemplateProcessingStrategy { + + private val directiveBasedCommandHandlers = + context.plugin<TemplatingPlugin>().query { directiveBasedCommandHandlers } + + override fun process(input: File, output: File, moduleContext: DokkaConfiguration.DokkaModuleDescription?): Boolean = + if (input.isFile && input.extension == "html") { + val document = Jsoup.parse(input, "UTF-8") + document.outputSettings().indentAmount(0).prettyPrint(false) + + document.select("dokka-template-command").forEach { + handleCommandAsTag(it, parseJson(it.attr("data")), input, output) + } + extractCommandsFromComments(document) { command, body -> + val bodyTrimed = + body.dropWhile { node -> (node is TextNode && node.isBlank).also { if (it) node.remove() } } + .dropLastWhile { node -> (node is TextNode && node.isBlank).also { if (it) node.remove() } } + handleCommandAsComment(command, bodyTrimed, input, output) + } + + Files.write(output.toPath(), listOf(document.outerHtml())) + true + } else false + + public fun handleCommandAsTag(element: Element, command: Command, input: File, output: File) { + traverseHandlers(command) { handleCommandAsTag(command, element, input, output) } + } + + public fun handleCommandAsComment(command: Command, body: List<Node>, input: File, output: File) { + traverseHandlers(command) { handleCommandAsComment(command, body, input, output) } + } + + private fun traverseHandlers(command: Command, action: CommandHandler.() -> Unit) { + val handlers = directiveBasedCommandHandlers.filter { it.canHandle(command) } + if (handlers.isEmpty()) + context.logger.warn("Unknown templating command $command") + else + handlers.forEach(action) + } + + private fun extractCommandsFromComments( + node: Node, + startFrom: Int = 0, + handler: (command: Command, body: List<Node>) -> Unit + ) { + val nodes: MutableList<Node> = mutableListOf() + var lastStartBorder: Comment? = null + var firstStartBorder: Comment? = null + for (index in startFrom until node.childNodeSize()) { + when (val currentChild = node.childNode(index)) { + is Comment -> if (currentChild.data.startsWith(TEMPLATE_COMMAND_BEGIN_BORDER)) { + lastStartBorder = currentChild + firstStartBorder = firstStartBorder ?: currentChild + nodes.clear() + } else if (lastStartBorder != null && currentChild.data.startsWith(TEMPLATE_COMMAND_END_BORDER)) { + lastStartBorder.remove() + val cmd = lastStartBorder.data + .removePrefix("$TEMPLATE_COMMAND_BEGIN_BORDER$TEMPLATE_COMMAND_SEPARATOR") + .let { parseJson<Command>(it) } + + handler(cmd, nodes) + currentChild.remove() + extractCommandsFromComments(node, firstStartBorder?.siblingIndex() ?: 0, handler) + return + } else { + if (lastStartBorder != null) nodes.add(currentChild) + } + else -> { + extractCommandsFromComments(currentChild, handler = handler) + if (lastStartBorder != null) nodes.add(currentChild) + } + } + } + } + + override fun finish(output: File) { + directiveBasedCommandHandlers.forEach { it.finish(output) } + } +} diff --git a/dokka-subprojects/plugin-templating/src/main/kotlin/org/jetbrains/dokka/templates/FallbackTemplateProcessingStrategy.kt b/dokka-subprojects/plugin-templating/src/main/kotlin/org/jetbrains/dokka/templates/FallbackTemplateProcessingStrategy.kt new file mode 100644 index 00000000..a76d8eae --- /dev/null +++ b/dokka-subprojects/plugin-templating/src/main/kotlin/org/jetbrains/dokka/templates/FallbackTemplateProcessingStrategy.kt @@ -0,0 +1,16 @@ +/* + * Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license. + */ + +package org.jetbrains.dokka.templates + +import org.jetbrains.dokka.DokkaConfiguration +import java.io.File + +public class FallbackTemplateProcessingStrategy : TemplateProcessingStrategy { + + override fun process(input: File, output: File, moduleContext: DokkaConfiguration.DokkaModuleDescription?): Boolean { + if (input != output) input.copyTo(output, overwrite = true) + return true + } +} diff --git a/dokka-subprojects/plugin-templating/src/main/kotlin/org/jetbrains/dokka/templates/PathToRootSubstitutor.kt b/dokka-subprojects/plugin-templating/src/main/kotlin/org/jetbrains/dokka/templates/PathToRootSubstitutor.kt new file mode 100644 index 00000000..2ba290cf --- /dev/null +++ b/dokka-subprojects/plugin-templating/src/main/kotlin/org/jetbrains/dokka/templates/PathToRootSubstitutor.kt @@ -0,0 +1,20 @@ +/* + * Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license. + */ + +package org.jetbrains.dokka.templates + +import org.jetbrains.dokka.base.templating.PathToRootSubstitutionCommand +import org.jetbrains.dokka.base.templating.SubstitutionCommand +import org.jetbrains.dokka.plugability.DokkaContext +import java.io.File + +public class PathToRootSubstitutor( + private val dokkaContext: DokkaContext +) : Substitutor { + + override fun trySubstitute(context: TemplatingContext<SubstitutionCommand>, match: MatchResult): String? = + if (context.command is PathToRootSubstitutionCommand) { + context.output.toPath().parent.relativize(dokkaContext.configuration.outputDir.toPath()).toString().split(File.separator).joinToString(separator = "/", postfix = "/") { it } + } else null +} diff --git a/dokka-subprojects/plugin-templating/src/main/kotlin/org/jetbrains/dokka/templates/ProjectNameSubstitutor.kt b/dokka-subprojects/plugin-templating/src/main/kotlin/org/jetbrains/dokka/templates/ProjectNameSubstitutor.kt new file mode 100644 index 00000000..9b22f31b --- /dev/null +++ b/dokka-subprojects/plugin-templating/src/main/kotlin/org/jetbrains/dokka/templates/ProjectNameSubstitutor.kt @@ -0,0 +1,19 @@ +/* + * Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license. + */ + +package templates + +import org.jetbrains.dokka.base.templating.ProjectNameSubstitutionCommand +import org.jetbrains.dokka.base.templating.SubstitutionCommand +import org.jetbrains.dokka.plugability.DokkaContext +import org.jetbrains.dokka.templates.Substitutor +import org.jetbrains.dokka.templates.TemplatingContext + +public class ProjectNameSubstitutor( + private val dokkaContext: DokkaContext +) : Substitutor { + + override fun trySubstitute(context: TemplatingContext<SubstitutionCommand>, match: MatchResult): String? = + dokkaContext.configuration.moduleName.takeIf { context.command is ProjectNameSubstitutionCommand } +} diff --git a/dokka-subprojects/plugin-templating/src/main/kotlin/org/jetbrains/dokka/templates/ReplaceVersionCommandHandler.kt b/dokka-subprojects/plugin-templating/src/main/kotlin/org/jetbrains/dokka/templates/ReplaceVersionCommandHandler.kt new file mode 100644 index 00000000..28820278 --- /dev/null +++ b/dokka-subprojects/plugin-templating/src/main/kotlin/org/jetbrains/dokka/templates/ReplaceVersionCommandHandler.kt @@ -0,0 +1,31 @@ +/* + * Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license. + */ + +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 + +public class ReplaceVersionCommandHandler( + private val context: DokkaContext +) : CommandHandler { + + override fun canHandle(command: Command): Boolean = command is ReplaceVersionsCommand + + override fun handleCommandAsTag(command: Command, body: Element, input: File, output: File) { + val parent = body.parent() + if (parent != null) { + val position = body.elementSiblingIndex() + body.remove() + + context.configuration.moduleVersion?.takeIf { it.isNotEmpty() } + ?.let { parent.insertChildren(position, TextNode(it)) } + } + } +} diff --git a/dokka-subprojects/plugin-templating/src/main/kotlin/org/jetbrains/dokka/templates/SourcesetDependencyProcessingStrategy.kt b/dokka-subprojects/plugin-templating/src/main/kotlin/org/jetbrains/dokka/templates/SourcesetDependencyProcessingStrategy.kt new file mode 100644 index 00000000..38a08eea --- /dev/null +++ b/dokka-subprojects/plugin-templating/src/main/kotlin/org/jetbrains/dokka/templates/SourcesetDependencyProcessingStrategy.kt @@ -0,0 +1,40 @@ +/* + * Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license. + */ + +package templates + +import org.jetbrains.dokka.DokkaConfiguration +import org.jetbrains.dokka.base.templating.AddToSourcesetDependencies +import org.jetbrains.dokka.base.templating.parseJson +import org.jetbrains.dokka.base.templating.toJsonString +import org.jetbrains.dokka.plugability.DokkaContext +import org.jetbrains.dokka.templates.TemplateProcessingStrategy +import java.io.File +import java.util.concurrent.ConcurrentHashMap + +private typealias Entry = Map<String, List<String>> + +public class SourcesetDependencyProcessingStrategy( + public val context: DokkaContext +) : TemplateProcessingStrategy { + private val fileName = "sourceset_dependencies.js" + private val fragments = ConcurrentHashMap<String, Entry>() + + override fun finish(output: File) { + if (fragments.isNotEmpty()) { + val content = fragments.values.fold(emptyMap<String, List<String>>()) { acc, e -> acc + e } + .let { "sourceset_dependencies = '${toJsonString(it)}'" } + output.resolve("scripts").mkdirs() + output.resolve("scripts/$fileName").writeText(content) + } + } + + override fun process(input: File, output: File, moduleContext: DokkaConfiguration.DokkaModuleDescription?): Boolean = + input.takeIf { it.name == fileName } + ?.runCatching { parseJson<AddToSourcesetDependencies>(input.readText()) } + ?.getOrNull() + ?.also { (moduleName, content) -> + fragments += (moduleName to content) + } != null +} diff --git a/dokka-subprojects/plugin-templating/src/main/kotlin/org/jetbrains/dokka/templates/SubstitutionCommandHandler.kt b/dokka-subprojects/plugin-templating/src/main/kotlin/org/jetbrains/dokka/templates/SubstitutionCommandHandler.kt new file mode 100644 index 00000000..0c030439 --- /dev/null +++ b/dokka-subprojects/plugin-templating/src/main/kotlin/org/jetbrains/dokka/templates/SubstitutionCommandHandler.kt @@ -0,0 +1,71 @@ +/* + * Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license. + */ + +package org.jetbrains.dokka.templates + +import org.jetbrains.dokka.base.templating.Command +import org.jetbrains.dokka.base.templating.SubstitutionCommand +import org.jetbrains.dokka.plugability.DokkaContext +import org.jetbrains.dokka.plugability.plugin +import org.jetbrains.dokka.plugability.query +import org.jsoup.nodes.DataNode +import org.jsoup.nodes.Element +import org.jsoup.nodes.Node +import org.jsoup.nodes.TextNode +import java.io.File + +public class SubstitutionCommandHandler(context: DokkaContext) : CommandHandler { + + override fun handleCommandAsTag(command: Command, body: Element, input: File, output: File) { + command as SubstitutionCommand + val childrenCopy = body.children().toList() + substitute(childrenCopy, TemplatingContext(input, output, childrenCopy, command)) + + val position = body.elementSiblingIndex() + val parent = body.parent() + body.remove() + + parent?.insertChildren(position, childrenCopy) + } + + override fun handleCommandAsComment(command: Command, body: List<Node>, input: File, output: File) { + command as SubstitutionCommand + substitute(body, TemplatingContext(input, output, body, command)) + } + + override fun canHandle(command: Command): Boolean = command is SubstitutionCommand + + override fun finish(output: File) { } + + private val substitutors = context.plugin<TemplatingPlugin>().query { substitutor } + + private fun findSubstitution(commandContext: TemplatingContext<SubstitutionCommand>, match: MatchResult): String = + substitutors.asSequence().mapNotNull { it.trySubstitute(commandContext, match) }.firstOrNull() ?: match.value + + private fun substitute(elements: List<Node>, commandContext: TemplatingContext<SubstitutionCommand>) { + val regex = commandContext.command.pattern.toRegex() + elements.forEach { it.traverseToSubstitute(regex, commandContext) } + } + + private fun Node.traverseToSubstitute(regex: Regex, commandContext: TemplatingContext<SubstitutionCommand>) { + when (this) { + is TextNode -> replaceWith(TextNode(wholeText.substitute(regex, commandContext))) + is DataNode -> replaceWith(DataNode(wholeData.substitute(regex, commandContext))) + is Element -> { + attributes().forEach { attr(it.key, it.value.substitute(regex, commandContext)) } + childNodes().forEach { it.traverseToSubstitute(regex, commandContext) } + } + } + } + + private fun String.substitute(regex: Regex, commandContext: TemplatingContext<SubstitutionCommand>) = buildString { + var lastOffset = 0 + regex.findAll(this@substitute).forEach { match -> + append(this@substitute, lastOffset, match.range.first) + append(findSubstitution(commandContext, match)) + lastOffset = match.range.last + 1 + } + append(this@substitute, lastOffset, this@substitute.length) + } +} diff --git a/dokka-subprojects/plugin-templating/src/main/kotlin/org/jetbrains/dokka/templates/Substitutor.kt b/dokka-subprojects/plugin-templating/src/main/kotlin/org/jetbrains/dokka/templates/Substitutor.kt new file mode 100644 index 00000000..4dc4d353 --- /dev/null +++ b/dokka-subprojects/plugin-templating/src/main/kotlin/org/jetbrains/dokka/templates/Substitutor.kt @@ -0,0 +1,11 @@ +/* + * Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license. + */ + +package org.jetbrains.dokka.templates + +import org.jetbrains.dokka.base.templating.SubstitutionCommand + +public fun interface Substitutor { + public fun trySubstitute(context: TemplatingContext<SubstitutionCommand>, match: MatchResult): String? +} diff --git a/dokka-subprojects/plugin-templating/src/main/kotlin/org/jetbrains/dokka/templates/TemplateProcessor.kt b/dokka-subprojects/plugin-templating/src/main/kotlin/org/jetbrains/dokka/templates/TemplateProcessor.kt new file mode 100644 index 00000000..762e3c8b --- /dev/null +++ b/dokka-subprojects/plugin-templating/src/main/kotlin/org/jetbrains/dokka/templates/TemplateProcessor.kt @@ -0,0 +1,104 @@ +/* + * Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license. + */ + +package org.jetbrains.dokka.templates + +import kotlinx.coroutines.Dispatchers +import kotlinx.coroutines.coroutineScope +import kotlinx.coroutines.runBlocking +import org.jetbrains.dokka.DokkaConfiguration.DokkaModuleDescription +import org.jetbrains.dokka.base.DokkaBase +import org.jetbrains.dokka.base.templating.Command +import org.jetbrains.dokka.model.withDescendants +import org.jetbrains.dokka.pages.RootPageNode +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.jsoup.nodes.Node +import java.io.File + +public interface TemplateProcessor + +public interface SubmoduleTemplateProcessor : TemplateProcessor { + public fun process(modules: List<DokkaModuleDescription>): TemplatingResult +} + +public interface MultiModuleTemplateProcessor : TemplateProcessor { + public fun process(generatedPagesTree: RootPageNode) +} + +public interface TemplateProcessingStrategy { + public fun process(input: File, output: File, moduleContext: DokkaModuleDescription?): Boolean + public fun finish(output: File) {} +} + +public class DefaultSubmoduleTemplateProcessor( + private val context: DokkaContext, +) : SubmoduleTemplateProcessor { + + private val strategies: List<TemplateProcessingStrategy> = + context.plugin<TemplatingPlugin>().query { templateProcessingStrategy } + + private val configuredModulesPaths = + context.configuration.modules.associate { it.sourceOutputDirectory.absolutePath to it.name } + + override fun process(modules: List<DokkaModuleDescription>): TemplatingResult { + return runBlocking(Dispatchers.Default) { + coroutineScope { + modules.fold(TemplatingResult()) { acc, module -> + acc + module.sourceOutputDirectory.visit(context.configuration.outputDir.resolve(module.relativePathToOutputDirectory), module) + } + } + } + } + + private suspend fun File.visit(target: File, module: DokkaModuleDescription, acc: TemplatingResult = TemplatingResult()): TemplatingResult = + coroutineScope { + val source = this@visit + if (source.isDirectory) { + target.mkdirs() + val files = source.list().orEmpty() + val accWithSelf = configuredModulesPaths[source.absolutePath] + ?.takeIf { files.firstOrNull { !it.startsWith(".") } != null } + ?.let { acc.copy(modules = acc.modules + it) } + ?: acc + + files.fold(accWithSelf) { acc, path -> + source.resolve(path).visit(target.resolve(path), module, acc) + } + } else { + strategies.first { it.process(source, target, module) } + acc + } + } +} + +public class DefaultMultiModuleTemplateProcessor( + public val context: DokkaContext, +) : MultiModuleTemplateProcessor { + private val strategies: List<TemplateProcessingStrategy> = + context.plugin<TemplatingPlugin>().query { templateProcessingStrategy } + + private val locationProviderFactory = context.plugin<DokkaBase>().querySingle { locationProviderFactory } + + override fun process(generatedPagesTree: RootPageNode) { + val locationProvider = locationProviderFactory.getLocationProvider(generatedPagesTree) + generatedPagesTree.withDescendants().mapNotNull { pageNode -> locationProvider.resolve(pageNode)?.let { File(it) } } + .forEach { location -> strategies.first { it.process(location, location, null) } } + } +} + +public data class TemplatingContext<out T : Command>( + val input: File, + val output: File, + val body: List<Node>, + val command: T, +) + +public data class TemplatingResult(val modules: List<String> = emptyList()) { + public operator fun plus(rhs: TemplatingResult): TemplatingResult { + return TemplatingResult((modules + rhs.modules).distinct()) + } +} diff --git a/dokka-subprojects/plugin-templating/src/main/kotlin/org/jetbrains/dokka/templates/TemplatingPlugin.kt b/dokka-subprojects/plugin-templating/src/main/kotlin/org/jetbrains/dokka/templates/TemplatingPlugin.kt new file mode 100644 index 00000000..8a2e5a2a --- /dev/null +++ b/dokka-subprojects/plugin-templating/src/main/kotlin/org/jetbrains/dokka/templates/TemplatingPlugin.kt @@ -0,0 +1,80 @@ +/* + * Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license. + */ + +package org.jetbrains.dokka.templates + +import org.jetbrains.dokka.allModulesPage.templates.PackageListProcessingStrategy +import org.jetbrains.dokka.allModulesPage.templates.PagesSearchTemplateStrategy +import org.jetbrains.dokka.plugability.* +import templates.ProjectNameSubstitutor +import templates.ReplaceVersionCommandHandler +import templates.SourcesetDependencyProcessingStrategy + +@Suppress("unused") +public class TemplatingPlugin : DokkaPlugin() { + + public val submoduleTemplateProcessor: ExtensionPoint<SubmoduleTemplateProcessor> by extensionPoint() + public val multimoduleTemplateProcessor: ExtensionPoint<MultiModuleTemplateProcessor> by extensionPoint() + public val templateProcessingStrategy: ExtensionPoint<TemplateProcessingStrategy> by extensionPoint() + public val directiveBasedCommandHandlers: ExtensionPoint<CommandHandler> by extensionPoint() + public val substitutor: ExtensionPoint<Substitutor> by extensionPoint() + + public val defaultSubmoduleTemplateProcessor: Extension<SubmoduleTemplateProcessor, *, *> by extending { + submoduleTemplateProcessor providing ::DefaultSubmoduleTemplateProcessor + } + + public val defaultMultiModuleTemplateProcessor: Extension<MultiModuleTemplateProcessor, *, *> by extending { + multimoduleTemplateProcessor providing ::DefaultMultiModuleTemplateProcessor + } + + public val directiveBasedHtmlTemplateProcessingStrategy: Extension<TemplateProcessingStrategy, *, *> by extending { + templateProcessingStrategy providing ::DirectiveBasedHtmlTemplateProcessingStrategy order { + before(fallbackProcessingStrategy) + } + } + + public val sourcesetDependencyProcessingStrategy: Extension<TemplateProcessingStrategy, *, *> by extending { + templateProcessingStrategy providing ::SourcesetDependencyProcessingStrategy order { + before(fallbackProcessingStrategy) + } + } + + public val pagesSearchTemplateStrategy: Extension<TemplateProcessingStrategy, *, *> by extending { + templateProcessingStrategy providing ::PagesSearchTemplateStrategy order { + before(fallbackProcessingStrategy) + } + } + + public val packageListProcessingStrategy: Extension<TemplateProcessingStrategy, *, *> by extending { + templateProcessingStrategy providing ::PackageListProcessingStrategy order { + before(fallbackProcessingStrategy) + } + } + + public val fallbackProcessingStrategy: Extension<TemplateProcessingStrategy, *, *> by extending { + templateProcessingStrategy with FallbackTemplateProcessingStrategy() + } + + public val pathToRootSubstitutor: Extension<Substitutor, *, *> by extending { + substitutor providing ::PathToRootSubstitutor + } + + public val projectNameSubstitutor: Extension<Substitutor, *, *> by extending { + substitutor providing ::ProjectNameSubstitutor + } + + public val addToNavigationCommandHandler: Extension<CommandHandler, *, *> by extending { + directiveBasedCommandHandlers providing ::AddToNavigationCommandHandler + } + public val substitutionCommandHandler: Extension<CommandHandler, *, *> by extending { + directiveBasedCommandHandlers providing ::SubstitutionCommandHandler + } + public val replaceVersionCommandHandler: Extension<CommandHandler, *, *> by extending { + directiveBasedCommandHandlers providing ::ReplaceVersionCommandHandler + } + + @OptIn(DokkaPluginApiPreview::class) + override fun pluginApiPreviewAcknowledgement(): PluginApiPreviewAcknowledgement = + PluginApiPreviewAcknowledgement +} diff --git a/dokka-subprojects/plugin-templating/src/main/resources/META-INF/services/org.jetbrains.dokka.plugability.DokkaPlugin b/dokka-subprojects/plugin-templating/src/main/resources/META-INF/services/org.jetbrains.dokka.plugability.DokkaPlugin new file mode 100644 index 00000000..e6771ac5 --- /dev/null +++ b/dokka-subprojects/plugin-templating/src/main/resources/META-INF/services/org.jetbrains.dokka.plugability.DokkaPlugin @@ -0,0 +1,5 @@ +# +# Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license. +# + +org.jetbrains.dokka.templates.TemplatingPlugin diff --git a/dokka-subprojects/plugin-templating/src/test/kotlin/org/jetbrains/dokka/templates/AddToNavigationCommandResolutionTest.kt b/dokka-subprojects/plugin-templating/src/test/kotlin/org/jetbrains/dokka/templates/AddToNavigationCommandResolutionTest.kt new file mode 100644 index 00000000..8492fba1 --- /dev/null +++ b/dokka-subprojects/plugin-templating/src/test/kotlin/org/jetbrains/dokka/templates/AddToNavigationCommandResolutionTest.kt @@ -0,0 +1,143 @@ +/* + * Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license. + */ + +package org.jetbrains.dokka.templates + +import kotlinx.html.a +import kotlinx.html.div +import kotlinx.html.id +import kotlinx.html.span +import kotlinx.html.stream.createHTML +import org.jetbrains.dokka.DokkaModuleDescriptionImpl +import org.jetbrains.dokka.base.renderers.html.templateCommand +import org.jetbrains.dokka.base.templating.AddToNavigationCommand +import org.jetbrains.dokka.plugability.DokkaContext +import org.junit.jupiter.api.io.TempDir +import org.junit.jupiter.params.ParameterizedTest +import org.junit.jupiter.params.provider.ValueSource +import utils.assertHtmlEqualsIgnoringWhitespace +import java.io.File +import kotlin.test.Test + +class AddToNavigationCommandResolutionTest : TemplatingAbstractTest() { + + @Test + fun `should substitute AddToNavigationCommand in root directory`(@TempDir outputDirectory: File) { + addToNavigationTest(outputDirectory) { + val output = outputDirectory.resolve("navigation.html").readText() + val expected = expectedOutput( + ModuleWithPrefix("module1"), + ModuleWithPrefix("module2") + ) + assertHtmlEqualsIgnoringWhitespace(expected, output) + } + } + + @ParameterizedTest + @ValueSource(strings = ["module1", "module2"]) + fun `should substitute AddToNavigationCommand in modules directory`( + moduleName: String, + @TempDir outputDirectory: File + ) { + addToNavigationTest(outputDirectory) { + val output = outputDirectory.resolve(moduleName).resolve("navigation.html").readText() + val expected = expectedOutput( + ModuleWithPrefix("module1", ".."), + ModuleWithPrefix("module2", "..") + ) + assertHtmlEqualsIgnoringWhitespace(expected, output) + } + } + + private fun expectedOutput(vararg modulesWithPrefix: ModuleWithPrefix) = createHTML(prettyPrint = true) + .div("sideMenu") { + modulesWithPrefix.forEach { (moduleName, prefix) -> + val relativePrefix = prefix?.let { "$it/" } ?: "" + div("sideMenuPart") { + id = "$moduleName-nav-submenu" + div("overview") { + a { + href = "$relativePrefix$moduleName/module-page.html" + span { + +"module-$moduleName" + } + } + } + div("sideMenuPart") { + id = "$moduleName-nav-submenu-0" + div("overview") { + a { + href = "$relativePrefix$moduleName/$moduleName/package-page.html" + span { + +"package-$moduleName" + } + } + } + } + } + } + } + + private fun inputForModule(moduleName: String) = createHTML() + .templateCommand(AddToNavigationCommand(moduleName)) { + div("sideMenuPart") { + id = "$moduleName-nav-submenu" + div("overview") { + a { + href = "module-page.html" + span { + +"module-$moduleName" + } + } + } + div("sideMenuPart") { + id = "$moduleName-nav-submenu-0" + div("overview") { + a { + href = "$moduleName/package-page.html" + span { + +"package-$moduleName" + } + } + } + } + } + } + + private fun addToNavigationTest(outputDirectory: File, test: (DokkaContext) -> Unit) { + val module1 = outputDirectory.resolve("module1").also { it.mkdirs() } + val module2 = outputDirectory.resolve("module2").also { it.mkdirs() } + + val configuration = dokkaConfiguration { + modules = listOf( + DokkaModuleDescriptionImpl( + name = "module1", + relativePathToOutputDirectory = module1, + includes = emptySet(), + sourceOutputDirectory = module1, + ), + DokkaModuleDescriptionImpl( + name = "module2", + relativePathToOutputDirectory = module2, + includes = emptySet(), + sourceOutputDirectory = module2, + ), + ) + this.outputDir = outputDirectory + } + + val module1Navigation = module1.resolve("navigation.html") + module1Navigation.writeText(inputForModule("module1")) + val module2Navigation = module2.resolve("navigation.html") + module2Navigation.writeText(inputForModule("module2")) + + testFromData(configuration, useOutputLocationFromConfig = true) { + finishProcessingSubmodules = { ctx -> + test(ctx) + } + } + } + + private data class ModuleWithPrefix(val moduleName: String, val prefix: String? = null) +} diff --git a/dokka-subprojects/plugin-templating/src/test/kotlin/org/jetbrains/dokka/templates/AddToSearchCommandResolutionTest.kt b/dokka-subprojects/plugin-templating/src/test/kotlin/org/jetbrains/dokka/templates/AddToSearchCommandResolutionTest.kt new file mode 100644 index 00000000..ae8ab941 --- /dev/null +++ b/dokka-subprojects/plugin-templating/src/test/kotlin/org/jetbrains/dokka/templates/AddToSearchCommandResolutionTest.kt @@ -0,0 +1,82 @@ +/* + * Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license. + */ + +package org.jetbrains.dokka.templates + +import org.jetbrains.dokka.DokkaModuleDescriptionImpl +import org.jetbrains.dokka.base.renderers.html.SearchRecord +import org.jetbrains.dokka.base.templating.AddToSearch +import org.jetbrains.dokka.base.templating.parseJson +import org.jetbrains.dokka.base.templating.toJsonString +import org.junit.jupiter.api.io.TempDir +import org.junit.jupiter.params.ParameterizedTest +import org.junit.jupiter.params.provider.ValueSource +import java.io.File +import kotlin.test.assertEquals + +class AddToSearchCommandResolutionTest : TemplatingAbstractTest() { + + @ParameterizedTest + @ValueSource(strings = ["pages.json"]) + fun `should merge navigation templates`(fileName: String, @TempDir outputDirectory: File) { + setupTestDirectoriesWithContent(outputDirectory, fileName) + + val configuration = dokkaConfiguration { + modules = listOf( + DokkaModuleDescriptionImpl( + name = "module1", + relativePathToOutputDirectory = outputDirectory.resolve("module1"), + includes = emptySet(), + sourceOutputDirectory = outputDirectory.resolve("module1"), + ), + DokkaModuleDescriptionImpl( + name = "module2", + relativePathToOutputDirectory = outputDirectory.resolve("module2"), + includes = emptySet(), + sourceOutputDirectory = outputDirectory.resolve("module2"), + ), + ) + this.outputDir = outputDirectory + } + + testFromData(configuration, useOutputLocationFromConfig = true) { + finishProcessingSubmodules = { _ -> + val expected = elements.map { it.copy(location = "module1/${it.location}") } + + elements.map { it.copy(location = "module2/${it.location}") } + + val output = + parseJson<List<SearchRecord>>(outputDirectory.resolve("scripts/${fileName}").readText()) + assertEquals(expected, output.sortedBy { it.location }) + } + } + } + + private fun setupTestDirectoriesWithContent(outputDirectory: File, fileName: String): List<File> { + val scriptsForModule1 = outputDirectory.resolve("module1/scripts").also { it.mkdirs() } + val scriptsForModule2 = outputDirectory.resolve("module2/scripts").also { it.mkdirs() } + outputDirectory.resolve("scripts").also { it.mkdirs() } + + val module1Navigation = scriptsForModule1.resolve(fileName) + module1Navigation.writeText(toJsonString(fromModule1)) + val module2Navigation = scriptsForModule2.resolve(fileName) + module2Navigation.writeText(toJsonString(fromModule2)) + + return listOf(module1Navigation, module2Navigation) + } + + companion object { + val elements = listOf( + SearchRecord(name = "name1", location = "location1"), + SearchRecord(name = "name2", location = "location2") + ) + val fromModule1 = AddToSearch( + moduleName = "module1", + elements = elements + ) + val fromModule2 = AddToSearch( + moduleName = "module2", + elements = elements + ) + } +} diff --git a/dokka-subprojects/plugin-templating/src/test/kotlin/org/jetbrains/dokka/templates/SubstitutionCommandResolutionTest.kt b/dokka-subprojects/plugin-templating/src/test/kotlin/org/jetbrains/dokka/templates/SubstitutionCommandResolutionTest.kt new file mode 100644 index 00000000..b619afbb --- /dev/null +++ b/dokka-subprojects/plugin-templating/src/test/kotlin/org/jetbrains/dokka/templates/SubstitutionCommandResolutionTest.kt @@ -0,0 +1,110 @@ +/* + * Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license. + */ + +package org.jetbrains.dokka.templates + +import kotlinx.html.a +import kotlinx.html.div +import kotlinx.html.id +import kotlinx.html.span +import kotlinx.html.stream.createHTML +import org.jetbrains.dokka.DokkaModuleDescriptionImpl +import org.jetbrains.dokka.base.renderers.html.templateCommand +import org.jetbrains.dokka.base.renderers.html.templateCommandAsHtmlComment +import org.jetbrains.dokka.base.templating.PathToRootSubstitutionCommand +import org.junit.jupiter.api.io.TempDir +import utils.assertHtmlEqualsIgnoringWhitespace +import java.io.File +import kotlin.test.Test + +class SubstitutionCommandResolutionTest : TemplatingAbstractTest() { + + @Test + fun `should handle PathToRootCommand`(@TempDir outputDirectory: File) { + val template = createHTML() + .templateCommand(PathToRootSubstitutionCommand(pattern = "###", default = "default")) { + a { + href = "###index.html" + div { + id = "logo" + } + } + } + + val expected = createHTML().a { + href = "../index.html" + div { + id = "logo" + } + } + checkSubstitutedResult(outputDirectory, template, expected) + } + + @Test + fun `should handle PathToRootCommand as HTML comment`(@TempDir outputDirectory: File) { + val template = createHTML().span { + templateCommandAsHtmlComment(PathToRootSubstitutionCommand(pattern = "###", default = "default")) { + this@span.a { + href = "###index.html" + div { + id = "logo" + } + } + templateCommandAsHtmlComment(PathToRootSubstitutionCommand(pattern = "####", default = "default")) { + this@span.a { + href = "####index.html" + div { + id = "logo" + } + } + } + } + } + + val expected = createHTML().span { + a { + href = "../index.html" + div { + id = "logo" + } + } + a { + href = "../index.html" + div { + id = "logo" + } + } + } + checkSubstitutedResult(outputDirectory, template, expected) + } + + private fun checkSubstitutedResult(outputDirectory: File, template: String, expected:String) { + val testedFile = createDirectoriesAndWriteContent(outputDirectory, template) + + val configuration = dokkaConfiguration { + modules = listOf( + DokkaModuleDescriptionImpl( + name = "module1", + relativePathToOutputDirectory = outputDirectory.resolve("module1"), + includes = emptySet(), + sourceOutputDirectory = outputDirectory.resolve("module1"), + ) + ) + this.outputDir = outputDirectory + } + + testFromData(configuration, useOutputLocationFromConfig = true){ + finishProcessingSubmodules = { + assertHtmlEqualsIgnoringWhitespace(expected, testedFile.readText()) + } + } + } + + private fun createDirectoriesAndWriteContent(outputDirectory: File, content: String): File { + val module1 = outputDirectory.resolve("module1").also { it.mkdirs() } + val module1Content = module1.resolve("index.html") + module1Content.writeText(content) + return module1Content + } +} diff --git a/dokka-subprojects/plugin-templating/src/test/kotlin/org/jetbrains/dokka/templates/TemplatingDokkaTestGenerator.kt b/dokka-subprojects/plugin-templating/src/test/kotlin/org/jetbrains/dokka/templates/TemplatingDokkaTestGenerator.kt new file mode 100644 index 00000000..53f0d279 --- /dev/null +++ b/dokka-subprojects/plugin-templating/src/test/kotlin/org/jetbrains/dokka/templates/TemplatingDokkaTestGenerator.kt @@ -0,0 +1,74 @@ +/* + * Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license. + */ + +package org.jetbrains.dokka.templates + +import org.jetbrains.dokka.CoreExtensions +import org.jetbrains.dokka.DokkaConfiguration +import org.jetbrains.dokka.DokkaGenerator +import org.jetbrains.dokka.plugability.DokkaContext +import org.jetbrains.dokka.plugability.DokkaPlugin +import org.jetbrains.dokka.testApi.logger.TestLogger +import org.jetbrains.dokka.testApi.testRunner.AbstractTest +import org.jetbrains.dokka.testApi.testRunner.DokkaTestGenerator +import org.jetbrains.dokka.testApi.testRunner.TestBuilder +import org.jetbrains.dokka.testApi.testRunner.TestMethods +import org.jetbrains.dokka.utilities.DokkaConsoleLogger +import org.jetbrains.dokka.utilities.DokkaLogger +import org.jetbrains.dokka.utilities.LoggingLevel + +class TemplatingDokkaTestGenerator( + configuration: DokkaConfiguration, + logger: DokkaLogger, + testMethods: TemplatingTestMethods, + additionalPlugins: List<DokkaPlugin> = emptyList() +) : DokkaTestGenerator<TemplatingTestMethods>( + configuration, + logger, + testMethods, + additionalPlugins + TemplatingPlugin() + TestTemplatingPlugin() +) { + override fun generate() = with(testMethods) { + val dokkaGenerator = DokkaGenerator(configuration, logger) + + val context = + dokkaGenerator.initializePlugins(configuration, logger, additionalPlugins) + + pluginsSetupStage(context) + + val generation = context.single(CoreExtensions.generation) as TestTemplatingGeneration + + generation.processSubmodules() + submoduleProcessingStage(context) + + generation.finishProcessing() + finishProcessingSubmodules(context) + } + +} + +open class TemplatingTestMethods( + open val pluginsSetupStage: (DokkaContext) -> Unit, + open val submoduleProcessingStage: (DokkaContext) -> Unit, + open val finishProcessingSubmodules: (DokkaContext) -> Unit, +) : TestMethods + +class TemplatingTestBuilder : TestBuilder<TemplatingTestMethods>() { + var pluginsSetupStage: (DokkaContext) -> Unit = {} + var submoduleProcessingStage: (DokkaContext) -> Unit = {} + var finishProcessingSubmodules: (DokkaContext) -> Unit = {} + + override fun build() = TemplatingTestMethods( + pluginsSetupStage, + submoduleProcessingStage, + finishProcessingSubmodules, + ) +} + +abstract class TemplatingAbstractTest(logger: TestLogger = TestLogger(DokkaConsoleLogger(LoggingLevel.DEBUG))) : + AbstractTest<TemplatingTestMethods, TemplatingTestBuilder, TemplatingDokkaTestGenerator>( + ::TemplatingTestBuilder, + ::TemplatingDokkaTestGenerator, + logger, + ) diff --git a/dokka-subprojects/plugin-templating/src/test/kotlin/org/jetbrains/dokka/templates/TestTemplatingGeneration.kt b/dokka-subprojects/plugin-templating/src/test/kotlin/org/jetbrains/dokka/templates/TestTemplatingGeneration.kt new file mode 100644 index 00000000..0180b2ab --- /dev/null +++ b/dokka-subprojects/plugin-templating/src/test/kotlin/org/jetbrains/dokka/templates/TestTemplatingGeneration.kt @@ -0,0 +1,34 @@ +/* + * Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license. + */ + +package org.jetbrains.dokka.templates + +import org.jetbrains.dokka.Timer +import org.jetbrains.dokka.generation.Generation +import org.jetbrains.dokka.plugability.DokkaContext +import org.jetbrains.dokka.plugability.plugin +import org.jetbrains.dokka.plugability.query +import org.jetbrains.dokka.plugability.querySingle + +class TestTemplatingGeneration(private val context: DokkaContext) : Generation { + + val templatingPlugin by lazy { context.plugin<TemplatingPlugin>() } + + override fun Timer.generate() { + report("Processing submodules") + processSubmodules() + + report("Finishing processing") + finishProcessing() + } + + fun processSubmodules() = + templatingPlugin.querySingle { submoduleTemplateProcessor }.process(context.configuration.modules) + + fun finishProcessing() = + templatingPlugin.query { templateProcessingStrategy }.forEach { it.finish(context.configuration.outputDir) } + + + override val generationName = "test template generation" +} diff --git a/dokka-subprojects/plugin-templating/src/test/kotlin/org/jetbrains/dokka/templates/TestTemplatingPlugin.kt b/dokka-subprojects/plugin-templating/src/test/kotlin/org/jetbrains/dokka/templates/TestTemplatingPlugin.kt new file mode 100644 index 00000000..f1d5d919 --- /dev/null +++ b/dokka-subprojects/plugin-templating/src/test/kotlin/org/jetbrains/dokka/templates/TestTemplatingPlugin.kt @@ -0,0 +1,26 @@ +/* + * Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license. + */ + +package org.jetbrains.dokka.templates + +import org.jetbrains.dokka.CoreExtensions +import org.jetbrains.dokka.base.DokkaBase +import org.jetbrains.dokka.plugability.DokkaPlugin +import org.jetbrains.dokka.plugability.DokkaPluginApiPreview +import org.jetbrains.dokka.plugability.PluginApiPreviewAcknowledgement + +class TestTemplatingPlugin: DokkaPlugin() { + + val dokkaBase by lazy { plugin<DokkaBase>() } + + val allModulesPageGeneration by extending { + (CoreExtensions.generation + providing ::TestTemplatingGeneration + override dokkaBase.singleGeneration) + } + + @OptIn(DokkaPluginApiPreview::class) + override fun pluginApiPreviewAcknowledgement(): PluginApiPreviewAcknowledgement = + PluginApiPreviewAcknowledgement +} |