From 1618e552c136e25d86bf0708e0d760841c77c139 Mon Sep 17 00:00:00 2001 From: Błażej Kardyś Date: Tue, 5 Jan 2021 17:59:38 +0100 Subject: Versioning (#1654) * Adding versioning mechanism for multimodule * Versioning improvement * Refactor configuration, add ordering * Fix integration tests * Change packages, unignore test Co-authored-by: Marcin Aman --- plugins/templating/build.gradle.kts | 18 +++ .../templates/AddToNavigationCommandHandler.kt | 56 +++++++++ .../src/main/kotlin/templates/CommandHandler.kt | 11 ++ .../templates/DirectiveBasedTemplateProcessing.kt | 41 ++++++ .../FallbackTemplateProcessingStrategy.kt | 13 ++ .../JsonElementBasedTemplateProcessingStrategy.kt | 68 ++++++++++ .../main/kotlin/templates/PathToRootSubstitutor.kt | 14 +++ .../kotlin/templates/SubstitutionCommandHandler.kt | 60 +++++++++ .../src/main/kotlin/templates/Substitutor.kt | 7 ++ .../src/main/kotlin/templates/TemplateProcessor.kt | 56 +++++++++ .../src/main/kotlin/templates/TemplatingPlugin.kt | 50 ++++++++ .../org.jetbrains.dokka.plugability.DokkaPlugin | 1 + .../AddToNavigationCommandResolutionTest.kt | 137 +++++++++++++++++++++ .../templates/AddToSearchCommandResolutionTest.kt | 89 +++++++++++++ .../templates/SubstitutionCommandResolutionTest.kt | 69 +++++++++++ .../templates/TemplatingDokkaTestGenerator.kt | 63 ++++++++++ .../kotlin/templates/TestTemplatingGeneration.kt | 22 ++++ .../test/kotlin/templates/TestTemplatingPlugin.kt | 16 +++ 18 files changed, 791 insertions(+) create mode 100644 plugins/templating/build.gradle.kts create mode 100644 plugins/templating/src/main/kotlin/templates/AddToNavigationCommandHandler.kt create mode 100644 plugins/templating/src/main/kotlin/templates/CommandHandler.kt create mode 100644 plugins/templating/src/main/kotlin/templates/DirectiveBasedTemplateProcessing.kt create mode 100644 plugins/templating/src/main/kotlin/templates/FallbackTemplateProcessingStrategy.kt create mode 100644 plugins/templating/src/main/kotlin/templates/JsonElementBasedTemplateProcessingStrategy.kt create mode 100644 plugins/templating/src/main/kotlin/templates/PathToRootSubstitutor.kt create mode 100644 plugins/templating/src/main/kotlin/templates/SubstitutionCommandHandler.kt create mode 100644 plugins/templating/src/main/kotlin/templates/Substitutor.kt create mode 100644 plugins/templating/src/main/kotlin/templates/TemplateProcessor.kt create mode 100644 plugins/templating/src/main/kotlin/templates/TemplatingPlugin.kt create mode 100644 plugins/templating/src/main/resources/META-INF/services/org.jetbrains.dokka.plugability.DokkaPlugin create mode 100644 plugins/templating/src/test/kotlin/templates/AddToNavigationCommandResolutionTest.kt create mode 100644 plugins/templating/src/test/kotlin/templates/AddToSearchCommandResolutionTest.kt create mode 100644 plugins/templating/src/test/kotlin/templates/SubstitutionCommandResolutionTest.kt create mode 100644 plugins/templating/src/test/kotlin/templates/TemplatingDokkaTestGenerator.kt create mode 100644 plugins/templating/src/test/kotlin/templates/TestTemplatingGeneration.kt create mode 100644 plugins/templating/src/test/kotlin/templates/TestTemplatingPlugin.kt (limited to 'plugins/templating') diff --git a/plugins/templating/build.gradle.kts b/plugins/templating/build.gradle.kts new file mode 100644 index 00000000..6c160a9f --- /dev/null +++ b/plugins/templating/build.gradle.kts @@ -0,0 +1,18 @@ +import org.jetbrains.registerDokkaArtifactPublication + +registerDokkaArtifactPublication("templating-plugin") { + artifactId = "templating-plugin" +} + +dependencies { + implementation(project(":plugins:base")) + + val coroutines_version: String by project + implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:$coroutines_version") + implementation("com.fasterxml.jackson.module:jackson-module-kotlin:2.11.1") + val kotlinx_html_version: String by project + implementation("org.jetbrains.kotlinx:kotlinx-html-jvm:$kotlinx_html_version") + + implementation("org.jsoup:jsoup:1.12.1") + testImplementation(project(":plugins:base:base-test-utils")) +} \ No newline at end of file diff --git a/plugins/templating/src/main/kotlin/templates/AddToNavigationCommandHandler.kt b/plugins/templating/src/main/kotlin/templates/AddToNavigationCommandHandler.kt new file mode 100644 index 00000000..3e7e1290 --- /dev/null +++ b/plugins/templating/src/main/kotlin/templates/AddToNavigationCommandHandler.kt @@ -0,0 +1,56 @@ +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 + +class AddToNavigationCommandHandler(val context: DokkaContext) : CommandHandler { + private val navigationFragments = ConcurrentHashMap() + + override fun handleCommand(element: Element, command: Command, 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()] = element } + } + + override fun canHandle(command: Command) = 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()) + ) + } + } + } +} \ No newline at end of file diff --git a/plugins/templating/src/main/kotlin/templates/CommandHandler.kt b/plugins/templating/src/main/kotlin/templates/CommandHandler.kt new file mode 100644 index 00000000..d72092a1 --- /dev/null +++ b/plugins/templating/src/main/kotlin/templates/CommandHandler.kt @@ -0,0 +1,11 @@ +package org.jetbrains.dokka.templates + +import org.jetbrains.dokka.base.templating.Command +import org.jsoup.nodes.Element +import java.io.File + +interface CommandHandler { + fun handleCommand(element: Element, command: Command, input: File, output: File) + fun canHandle(command: Command): Boolean + fun finish(output: File) {} +} \ No newline at end of file diff --git a/plugins/templating/src/main/kotlin/templates/DirectiveBasedTemplateProcessing.kt b/plugins/templating/src/main/kotlin/templates/DirectiveBasedTemplateProcessing.kt new file mode 100644 index 00000000..c3b9aa53 --- /dev/null +++ b/plugins/templating/src/main/kotlin/templates/DirectiveBasedTemplateProcessing.kt @@ -0,0 +1,41 @@ +package org.jetbrains.dokka.templates + +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.Element +import java.io.File +import java.nio.file.Files + +class DirectiveBasedHtmlTemplateProcessingStrategy(private val context: DokkaContext) : TemplateProcessingStrategy { + + private val directiveBasedCommandHandlers = + context.plugin().query { directiveBasedCommandHandlers } + + override fun process(input: File, output: File): 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 { + handleCommand(it, parseJson(it.attr("data")), input, output) + } + Files.write(output.toPath(), listOf(document.outerHtml())) + true + } else false + + fun handleCommand(element: Element, command: Command, input: File, output: File) { + val handlers = directiveBasedCommandHandlers.filter { it.canHandle(command) } + if (handlers.isEmpty()) + context.logger.warn("Unknown templating command $command") + else + handlers.forEach { it.handleCommand(element, command, input, output) } + + } + + override fun finish(output: File) { + directiveBasedCommandHandlers.forEach { it.finish(output) } + } +} diff --git a/plugins/templating/src/main/kotlin/templates/FallbackTemplateProcessingStrategy.kt b/plugins/templating/src/main/kotlin/templates/FallbackTemplateProcessingStrategy.kt new file mode 100644 index 00000000..4e88c318 --- /dev/null +++ b/plugins/templating/src/main/kotlin/templates/FallbackTemplateProcessingStrategy.kt @@ -0,0 +1,13 @@ +package org.jetbrains.dokka.templates + +import org.jetbrains.dokka.plugability.DokkaContext +import java.io.File +import java.nio.file.Files + +class FallbackTemplateProcessingStrategy(dokkaContext: DokkaContext) : TemplateProcessingStrategy { + + override fun process(input: File, output: File): Boolean { + if(input != output) input.copyTo(output, overwrite = true) + return true + } +} \ No newline at end of file diff --git a/plugins/templating/src/main/kotlin/templates/JsonElementBasedTemplateProcessingStrategy.kt b/plugins/templating/src/main/kotlin/templates/JsonElementBasedTemplateProcessingStrategy.kt new file mode 100644 index 00000000..a2d55209 --- /dev/null +++ b/plugins/templating/src/main/kotlin/templates/JsonElementBasedTemplateProcessingStrategy.kt @@ -0,0 +1,68 @@ +package org.jetbrains.dokka.allModulesPage.templates + +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 + +abstract class BaseJsonNavigationTemplateProcessingStrategy(val context: DokkaContext) : TemplateProcessingStrategy { + abstract val navigationFileNameWithoutExtension: String + abstract val path: String + + private val fragments = ConcurrentHashMap>() + + open fun canProcess(file: File): Boolean = + file.extension == "json" && file.nameWithoutExtension == navigationFileNameWithoutExtension + + override fun process(input: File, output: File): Boolean { + val canProcess = canProcess(input) + if (canProcess) { + runCatching { parseJson(input.readText()) }.getOrNull()?.let { command -> + context.configuration.modules.find { it.name == command.moduleName }?.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/$navigationFileNameWithoutExtension.json").writeText(content) + + fragments.keys.forEach { + output.resolve(it).resolve("$path/$navigationFileNameWithoutExtension.json").writeText(content) + } + } + } + + private fun fallbackToCopy(input: File, output: File) { + context.logger.warn("Falling back to just copying file for ${input.name} even thought it should process it") + input.copyTo(output) + } + + private fun SearchRecord.withResolvedLocation(moduleName: String): SearchRecord = + copy(location = "$moduleName/$location") + +} + +class NavigationSearchTemplateStrategy(val dokkaContext: DokkaContext) : + BaseJsonNavigationTemplateProcessingStrategy(dokkaContext) { + override val navigationFileNameWithoutExtension: String = "navigation-pane" + override val path: String = "scripts" +} + +class PagesSearchTemplateStrategy(val dokkaContext: DokkaContext) : + BaseJsonNavigationTemplateProcessingStrategy(dokkaContext) { + override val navigationFileNameWithoutExtension: String = "pages" + override val path: String = "scripts" +} \ No newline at end of file diff --git a/plugins/templating/src/main/kotlin/templates/PathToRootSubstitutor.kt b/plugins/templating/src/main/kotlin/templates/PathToRootSubstitutor.kt new file mode 100644 index 00000000..da81432e --- /dev/null +++ b/plugins/templating/src/main/kotlin/templates/PathToRootSubstitutor.kt @@ -0,0 +1,14 @@ +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 + +class PathToRootSubstitutor(private val dokkaContext: DokkaContext) : Substitutor { + + override fun trySubstitute(context: TemplatingContext, 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 +} \ No newline at end of file diff --git a/plugins/templating/src/main/kotlin/templates/SubstitutionCommandHandler.kt b/plugins/templating/src/main/kotlin/templates/SubstitutionCommandHandler.kt new file mode 100644 index 00000000..c7b15137 --- /dev/null +++ b/plugins/templating/src/main/kotlin/templates/SubstitutionCommandHandler.kt @@ -0,0 +1,60 @@ +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 + +class SubstitutionCommandHandler(context: DokkaContext) : CommandHandler { + + override fun handleCommand(element: Element, command: Command, input: File, output: File) { + command as SubstitutionCommand + substitute(element, TemplatingContext(input, output, element, command)) + } + + override fun canHandle(command: Command): Boolean = command is SubstitutionCommand + + private val substitutors = context.plugin().query { substitutor } + + private fun findSubstitution(commandContext: TemplatingContext, match: MatchResult): String = + substitutors.asSequence().mapNotNull { it.trySubstitute(commandContext, match) }.firstOrNull() ?: match.value + + private fun substitute(element: Element, commandContext: TemplatingContext) { + val regex = commandContext.command.pattern.toRegex() + element.children().forEach { it.traverseToSubstitute(regex, commandContext) } + + val childrenCopy = element.children().toList() + val position = element.elementSiblingIndex() + val parent = element.parent() + element.remove() + + parent.insertChildren(position, childrenCopy) + } + + private fun Node.traverseToSubstitute(regex: Regex, commandContext: TemplatingContext) { + 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) = 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) + } +} \ No newline at end of file diff --git a/plugins/templating/src/main/kotlin/templates/Substitutor.kt b/plugins/templating/src/main/kotlin/templates/Substitutor.kt new file mode 100644 index 00000000..55463974 --- /dev/null +++ b/plugins/templating/src/main/kotlin/templates/Substitutor.kt @@ -0,0 +1,7 @@ +package org.jetbrains.dokka.templates + +import org.jetbrains.dokka.base.templating.SubstitutionCommand + +fun interface Substitutor { + fun trySubstitute(context: TemplatingContext, match: MatchResult): String? +} \ No newline at end of file diff --git a/plugins/templating/src/main/kotlin/templates/TemplateProcessor.kt b/plugins/templating/src/main/kotlin/templates/TemplateProcessor.kt new file mode 100644 index 00000000..8fbd76b6 --- /dev/null +++ b/plugins/templating/src/main/kotlin/templates/TemplateProcessor.kt @@ -0,0 +1,56 @@ +package org.jetbrains.dokka.templates + +import kotlinx.coroutines.* +import org.jetbrains.dokka.base.templating.Command +import org.jetbrains.dokka.plugability.DokkaContext +import org.jetbrains.dokka.plugability.plugin +import org.jetbrains.dokka.plugability.query +import org.jsoup.nodes.Element +import java.io.File + +interface TemplateProcessor { + fun process() +} + +interface TemplateProcessingStrategy { + fun process(input: File, output: File): Boolean + fun finish(output: File) {} +} + +class DefaultTemplateProcessor( + private val context: DokkaContext, +): TemplateProcessor { + + private val strategies: List = context.plugin().query { templateProcessingStrategy } + + override fun process() = runBlocking(Dispatchers.Default) { + coroutineScope { + context.configuration.modules.forEach { + launch { + it.sourceOutputDirectory.visit(context.configuration.outputDir.resolve(it.relativePathToOutputDirectory)) + } + } + } + strategies.map { it.finish(context.configuration.outputDir) } + Unit + } + + private suspend fun File.visit(target: File): Unit = coroutineScope { + val source = this@visit + if (source.isDirectory) { + target.mkdir() + source.list()?.forEach { + launch { source.resolve(it).visit(target.resolve(it)) } + } + } else { + strategies.first { it.process(source, target) } + } + } +} + +data class TemplatingContext( + val input: File, + val output: File, + val element: Element, + val command: T, +) \ 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 new file mode 100644 index 00000000..29ca4904 --- /dev/null +++ b/plugins/templating/src/main/kotlin/templates/TemplatingPlugin.kt @@ -0,0 +1,50 @@ +package org.jetbrains.dokka.templates + +import org.jetbrains.dokka.allModulesPage.templates.NavigationSearchTemplateStrategy +import org.jetbrains.dokka.allModulesPage.templates.PagesSearchTemplateStrategy +import org.jetbrains.dokka.plugability.DokkaPlugin + +class TemplatingPlugin : DokkaPlugin() { + + val templateProcessor by extensionPoint() + val templateProcessingStrategy by extensionPoint() + val directiveBasedCommandHandlers by extensionPoint() + + val substitutor by extensionPoint() + + val defaultTemplateProcessor by extending { + templateProcessor providing ::DefaultTemplateProcessor + } + + val directiveBasedHtmlTemplateProcessingStrategy by extending { + templateProcessingStrategy providing ::DirectiveBasedHtmlTemplateProcessingStrategy order { + before(fallbackProcessingStrategy) + } + } + val navigationSearchTemplateStrategy by extending { + templateProcessingStrategy providing ::NavigationSearchTemplateStrategy order { + before(fallbackProcessingStrategy) + } + } + + val pagesSearchTemplateStrategy by extending { + templateProcessingStrategy providing ::PagesSearchTemplateStrategy order { + before(fallbackProcessingStrategy) + } + } + + val fallbackProcessingStrategy by extending { + templateProcessingStrategy providing ::FallbackTemplateProcessingStrategy + } + + val pathToRootSubstitutor by extending { + substitutor providing ::PathToRootSubstitutor + } + + val addToNavigationCommandHandler by extending { + directiveBasedCommandHandlers providing ::AddToNavigationCommandHandler + } + val substitutionCommandHandler by extending { + directiveBasedCommandHandlers providing ::SubstitutionCommandHandler + } +} \ No newline at end of file diff --git a/plugins/templating/src/main/resources/META-INF/services/org.jetbrains.dokka.plugability.DokkaPlugin b/plugins/templating/src/main/resources/META-INF/services/org.jetbrains.dokka.plugability.DokkaPlugin new file mode 100644 index 00000000..38e2d1bf --- /dev/null +++ b/plugins/templating/src/main/resources/META-INF/services/org.jetbrains.dokka.plugability.DokkaPlugin @@ -0,0 +1 @@ +org.jetbrains.dokka.templates.TemplatingPlugin \ No newline at end of file diff --git a/plugins/templating/src/test/kotlin/templates/AddToNavigationCommandResolutionTest.kt b/plugins/templating/src/test/kotlin/templates/AddToNavigationCommandResolutionTest.kt new file mode 100644 index 00000000..19c940c2 --- /dev/null +++ b/plugins/templating/src/test/kotlin/templates/AddToNavigationCommandResolutionTest.kt @@ -0,0 +1,137 @@ +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.Rule +import org.junit.jupiter.api.Test +import org.junit.jupiter.params.ParameterizedTest +import org.junit.jupiter.params.provider.ValueSource +import org.junit.rules.TemporaryFolder +import utils.assertHtmlEqualsIgnoringWhitespace + +class AddToNavigationCommandResolutionTest : TemplatingAbstractTest() { + @get:Rule + val folder: TemporaryFolder = TemporaryFolder() + + @Test + fun `should substitute AddToNavigationCommand in root directory`() = + addToNavigationTest { + val output = folder.root.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) = + addToNavigationTest { + val output = folder.root.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(test: (DokkaContext) -> Unit) { + folder.create() + val module1 = folder.newFolder("module1") + val module2 = folder.newFolder("module2") + + 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 = folder.root + } + + val module1Navigation = module1.resolve("navigation.html") + module1Navigation.writeText(inputForModule("module1")) + val module2Navigation = module2.resolve("navigation.html") + module2Navigation.writeText(inputForModule("module2")) + + testFromData(configuration, preserveOutputLocation = true) { + submoduleProcessingStage = { ctx -> + test(ctx) + } + } + } + + private data class ModuleWithPrefix(val moduleName: String, val prefix: String? = null) +} \ No newline at end of file diff --git a/plugins/templating/src/test/kotlin/templates/AddToSearchCommandResolutionTest.kt b/plugins/templating/src/test/kotlin/templates/AddToSearchCommandResolutionTest.kt new file mode 100644 index 00000000..a962d524 --- /dev/null +++ b/plugins/templating/src/test/kotlin/templates/AddToSearchCommandResolutionTest.kt @@ -0,0 +1,89 @@ +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.Rule +import org.junit.jupiter.params.ParameterizedTest +import org.junit.jupiter.params.provider.ValueSource +import org.junit.rules.TemporaryFolder +import java.io.File +import kotlin.test.assertEquals + +class AddToSearchCommandResolutionTest : TemplatingAbstractTest() { + 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 + ) + } + + @get:Rule + val folder: TemporaryFolder = TemporaryFolder() + + @ParameterizedTest + @ValueSource(strings = ["navigation-pane.json", "pages.json"]) + fun `should merge navigation templates`(fileName: String) { + val (module1Navigation, module2Navigation) = setupTestDirectoriesWithContent(fileName) + + val outputDir = folder.root + val configuration = dokkaConfiguration { + modules = listOf( + DokkaModuleDescriptionImpl( + name = "module1", + relativePathToOutputDirectory = folder.root.resolve("module1"), + includes = emptySet(), + sourceOutputDirectory = folder.root.resolve("module1"), + ), + DokkaModuleDescriptionImpl( + name = "module2", + relativePathToOutputDirectory = folder.root.resolve("module2"), + includes = emptySet(), + sourceOutputDirectory = folder.root.resolve("module2"), + ), + ) + this.outputDir = outputDir + } + + testFromData(configuration, preserveOutputLocation = true) { + submoduleProcessingStage = { _ -> + val expected = elements.map { it.copy(location = "module1/${it.location}") } + + elements.map { it.copy(location = "module2/${it.location}") } + + val output = + parseJson>(outputDir.resolve("scripts/${fileName}").readText()) + assertEquals(expected, output.sortedBy { it.location }) + + val outputFromModule1 = parseJson>(module1Navigation.readText()) + assertEquals(expected, outputFromModule1.sortedBy { it.location }) + + val outputFromModule2 = parseJson>(module2Navigation.readText()) + assertEquals(expected, outputFromModule2.sortedBy { it.location }) + } + } + } + + private fun setupTestDirectoriesWithContent(fileName: String): List { + folder.create() + val scriptsForModule1 = folder.newFolder("module1", "scripts") + val scriptsForModule2 = folder.newFolder("module2", "scripts") + folder.newFolder("scripts") + + val module1Navigation = scriptsForModule1.resolve(fileName) + module1Navigation.writeText(toJsonString(fromModule1)) + val module2Navigation = scriptsForModule2.resolve(fileName) + module2Navigation.writeText(toJsonString(fromModule2)) + + return listOf(module1Navigation, module2Navigation) + } +} \ No newline at end of file diff --git a/plugins/templating/src/test/kotlin/templates/SubstitutionCommandResolutionTest.kt b/plugins/templating/src/test/kotlin/templates/SubstitutionCommandResolutionTest.kt new file mode 100644 index 00000000..d7143f11 --- /dev/null +++ b/plugins/templating/src/test/kotlin/templates/SubstitutionCommandResolutionTest.kt @@ -0,0 +1,69 @@ +package org.jetbrains.dokka.templates + +import kotlinx.html.a +import kotlinx.html.div +import kotlinx.html.id +import kotlinx.html.stream.createHTML +import org.jetbrains.dokka.DokkaModuleDescriptionImpl +import org.jetbrains.dokka.base.renderers.html.templateCommand +import org.jetbrains.dokka.base.templating.PathToRootSubstitutionCommand +import org.junit.Rule +import org.junit.rules.TemporaryFolder +import org.junit.jupiter.api.Test +import utils.assertHtmlEqualsIgnoringWhitespace +import java.io.File + +class SubstitutionCommandResolutionTest : TemplatingAbstractTest() { + + @get:Rule + val folder: TemporaryFolder = TemporaryFolder() + + @Test + fun `should handle PathToRootCommand`() { + 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" + } + } + + val testedFile = createDirectoriesAndWriteContent(template) + + val configuration = dokkaConfiguration { + modules = listOf( + DokkaModuleDescriptionImpl( + name = "module1", + relativePathToOutputDirectory = folder.root.resolve("module1"), + includes = emptySet(), + sourceOutputDirectory = folder.root.resolve("module1"), + ) + ) + this.outputDir = folder.root + } + + testFromData(configuration, preserveOutputLocation = true){ + submoduleProcessingStage = { + assertHtmlEqualsIgnoringWhitespace(expected, testedFile.readText()) + } + } + } + + private fun createDirectoriesAndWriteContent(content: String): File { + folder.create() + val module1 = folder.newFolder("module1") + val module1Content = module1.resolve("index.html") + module1Content.writeText(content) + return module1Content + } + +} \ No newline at end of file diff --git a/plugins/templating/src/test/kotlin/templates/TemplatingDokkaTestGenerator.kt b/plugins/templating/src/test/kotlin/templates/TemplatingDokkaTestGenerator.kt new file mode 100644 index 00000000..906fb1ea --- /dev/null +++ b/plugins/templating/src/test/kotlin/templates/TemplatingDokkaTestGenerator.kt @@ -0,0 +1,63 @@ +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 + +class TemplatingDokkaTestGenerator( + configuration: DokkaConfiguration, + logger: DokkaLogger, + testMethods: TemplatingTestMethods, + additionalPlugins: List = emptyList() +) : DokkaTestGenerator( + 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) + } + +} + +open class TemplatingTestMethods( + open val pluginsSetupStage: (DokkaContext) -> Unit, + open val submoduleProcessingStage: (DokkaContext) -> Unit, +) : TestMethods + +class TemplatingTestBuilder : TestBuilder() { + var pluginsSetupStage: (DokkaContext) -> Unit = {} + var submoduleProcessingStage: (DokkaContext) -> Unit = {} + + override fun build() = TemplatingTestMethods( + pluginsSetupStage, + submoduleProcessingStage, + ) +} + +abstract class TemplatingAbstractTest(logger: TestLogger = TestLogger(DokkaConsoleLogger)) : + AbstractTest( + ::TemplatingTestBuilder, + ::TemplatingDokkaTestGenerator, + logger, + ) diff --git a/plugins/templating/src/test/kotlin/templates/TestTemplatingGeneration.kt b/plugins/templating/src/test/kotlin/templates/TestTemplatingGeneration.kt new file mode 100644 index 00000000..0a5bae4b --- /dev/null +++ b/plugins/templating/src/test/kotlin/templates/TestTemplatingGeneration.kt @@ -0,0 +1,22 @@ +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.querySingle + +class TestTemplatingGeneration(context: DokkaContext): Generation { + + val templatingPlugin by lazy { context.plugin() } + + override fun Timer.generate() { + report("Processing submodules") + processSubmodules() + } + + fun processSubmodules() = + templatingPlugin.querySingle { templateProcessor }.process() + + override val generationName = "test template generation" +} \ No newline at end of file diff --git a/plugins/templating/src/test/kotlin/templates/TestTemplatingPlugin.kt b/plugins/templating/src/test/kotlin/templates/TestTemplatingPlugin.kt new file mode 100644 index 00000000..1ed961b8 --- /dev/null +++ b/plugins/templating/src/test/kotlin/templates/TestTemplatingPlugin.kt @@ -0,0 +1,16 @@ +package org.jetbrains.dokka.templates + +import org.jetbrains.dokka.CoreExtensions +import org.jetbrains.dokka.base.DokkaBase +import org.jetbrains.dokka.plugability.DokkaPlugin + +class TestTemplatingPlugin: DokkaPlugin() { + + val dokkaBase by lazy { plugin() } + + val allModulesPageGeneration by extending { + (CoreExtensions.generation + providing ::TestTemplatingGeneration + override dokkaBase.singleGeneration) + } +} \ No newline at end of file -- cgit