diff options
18 files changed, 681 insertions, 39 deletions
diff --git a/core/test-api/src/main/kotlin/testApi/testRunner/TestDokkaConfigurationBuilder.kt b/core/test-api/src/main/kotlin/testApi/testRunner/TestDokkaConfigurationBuilder.kt index e3d5016a..87e85c02 100644 --- a/core/test-api/src/main/kotlin/testApi/testRunner/TestDokkaConfigurationBuilder.kt +++ b/core/test-api/src/main/kotlin/testApi/testRunner/TestDokkaConfigurationBuilder.kt @@ -26,25 +26,26 @@ class TestDokkaConfigurationBuilder { field = value } var moduleVersion: String = "1.0-SNAPSHOT" - var outputDir: String = "out" + var outputDir: File = File("out") var format: String = "html" var offlineMode: Boolean = false var cacheRoot: String? = null var pluginsClasspath: List<File> = emptyList() var pluginsConfigurations: MutableList<PluginConfigurationImpl> = mutableListOf() var failOnWarning: Boolean = false + var modules: List<DokkaModuleDescriptionImpl> = emptyList() private val lazySourceSets = mutableListOf<Lazy<DokkaSourceSetImpl>>() fun build() = DokkaConfigurationImpl( moduleName = moduleName, moduleVersion = moduleVersion, - outputDir = File(outputDir), + outputDir = outputDir, cacheRoot = cacheRoot?.let(::File), offlineMode = offlineMode, sourceSets = lazySourceSets.map { it.value }.toList(), pluginsClasspath = pluginsClasspath, pluginsConfiguration = pluginsConfigurations, - modules = emptyList(), + modules = modules, failOnWarning = failOnWarning, ) diff --git a/core/test-api/src/main/kotlin/testApi/testRunner/TestRunner.kt b/core/test-api/src/main/kotlin/testApi/testRunner/TestRunner.kt index 1e758fec..9a010135 100644 --- a/core/test-api/src/main/kotlin/testApi/testRunner/TestRunner.kt +++ b/core/test-api/src/main/kotlin/testApi/testRunner/TestRunner.kt @@ -7,7 +7,6 @@ import org.jetbrains.dokka.pages.RootPageNode import org.jetbrains.dokka.plugability.DokkaContext import org.jetbrains.dokka.plugability.DokkaPlugin import org.jetbrains.dokka.testApi.logger.TestLogger -import org.jetbrains.dokka.utilities.DokkaConsoleLogger import org.jetbrains.dokka.utilities.DokkaLogger import org.junit.rules.TemporaryFolder import testApi.testRunner.TestDokkaConfigurationBuilder @@ -20,7 +19,7 @@ import java.nio.file.Path import java.nio.file.Paths // TODO: take dokka configuration from file -abstract class AbstractTest< M: TestMethods, T : TestBuilder<M>, D: DokkaTestGenerator<M> >( +abstract class AbstractTest<M : TestMethods, T : TestBuilder<M>, D : DokkaTestGenerator<M>>( protected val testBuilder: () -> T, protected val dokkaTestGenerator: (DokkaConfiguration, DokkaLogger, M, List<DokkaPlugin>) -> D, protected val logger: TestLogger, @@ -32,19 +31,22 @@ abstract class AbstractTest< M: TestMethods, T : TestBuilder<M>, D: DokkaTestGen protected fun testFromData( configuration: DokkaConfigurationImpl, cleanupOutput: Boolean = true, + preserveOutputLocation: Boolean = false, pluginOverrides: List<DokkaPlugin> = emptyList(), block: T.() -> Unit ) { val testMethods = testBuilder().apply(block).build() - val tempDir = getTempDir(cleanupOutput) - if (!cleanupOutput) - logger.info("Output generated under: ${tempDir.root.absolutePath}") - val newConfiguration = + val configurationToUse = if (!preserveOutputLocation) { + val tempDir = getTempDir(cleanupOutput) + if (!cleanupOutput) + logger.info("Output generated under: ${tempDir.root.absolutePath}") configuration.copy( outputDir = tempDir.root ) + } else configuration + dokkaTestGenerator( - newConfiguration, + configurationToUse, logger, testMethods, pluginOverrides @@ -169,7 +171,9 @@ abstract class AbstractTest< M: TestMethods, T : TestBuilder<M>, D: DokkaTestGen } } -open class TestMethods( +interface TestMethods + +open class CoreTestMethods( open val pluginsSetupStage: (DokkaContext) -> Unit, open val verificationStage: (() -> Unit) -> Unit, open val documentablesCreationStage: (List<DModule>) -> Unit, @@ -178,13 +182,13 @@ open class TestMethods( open val pagesGenerationStage: (RootPageNode) -> Unit, open val pagesTransformationStage: (RootPageNode) -> Unit, open val renderingStage: (RootPageNode, DokkaContext) -> Unit -) +) : TestMethods -abstract class TestBuilder<M: TestMethods> { +abstract class TestBuilder<M : TestMethods> { abstract fun build(): M } -abstract class DokkaTestGenerator<T: TestMethods>( +abstract class DokkaTestGenerator<T : TestMethods>( protected val configuration: DokkaConfiguration, protected val logger: DokkaLogger, protected val testMethods: T, diff --git a/integration-tests/gradle/src/integrationTest/kotlin/org/jetbrains/dokka/it/gradle/MultiModule0IntegrationTest.kt b/integration-tests/gradle/src/integrationTest/kotlin/org/jetbrains/dokka/it/gradle/MultiModule0IntegrationTest.kt index 47b9620b..c3ea8e52 100644 --- a/integration-tests/gradle/src/integrationTest/kotlin/org/jetbrains/dokka/it/gradle/MultiModule0IntegrationTest.kt +++ b/integration-tests/gradle/src/integrationTest/kotlin/org/jetbrains/dokka/it/gradle/MultiModule0IntegrationTest.kt @@ -58,6 +58,7 @@ class MultiModule0IntegrationTest(override val versions: BuildVersions) : Abstra assertNoHrefToMissingLocalFileOrDirectory(file) assertNoEmptyLinks(file) assertNoEmptySpans(file) + assertNoUnsubstitutedTemplatesInHtml(file) } val modulesFile = File(outputDir, "index.html") @@ -72,5 +73,17 @@ class MultiModule0IntegrationTest(override val versions: BuildVersions) : Abstra "moduleC" in modulesFileText, "Expected moduleC being mentioned in -modules.html" ) + + val gfmOutputDir = File(projectDir, "moduleA/build/dokka/gfmMultiModule") + assertTrue(gfmOutputDir.isDirectory, "Missing dokka GFM output directory") + + assertTrue( + gfmOutputDir.allGfmFiles().any(), + "Expected at least one md file being generated" + ) + + gfmOutputDir.allGfmFiles().forEach { file -> + assertFalse("GfmCommand" in file.readText()) + } } } diff --git a/integration-tests/gradle/src/integrationTest/kotlin/org/jetbrains/dokka/it/gradle/kotlin/CoroutinesGradleIntegrationTest.kt b/integration-tests/gradle/src/integrationTest/kotlin/org/jetbrains/dokka/it/gradle/kotlin/CoroutinesGradleIntegrationTest.kt index b4978ea9..a1caef68 100644 --- a/integration-tests/gradle/src/integrationTest/kotlin/org/jetbrains/dokka/it/gradle/kotlin/CoroutinesGradleIntegrationTest.kt +++ b/integration-tests/gradle/src/integrationTest/kotlin/org/jetbrains/dokka/it/gradle/kotlin/CoroutinesGradleIntegrationTest.kt @@ -45,6 +45,7 @@ class CoroutinesGradleIntegrationTest(override val versions: BuildVersions) : Ab // assertNoHrefToMissingLocalFileOrDirectory(file) assertNoEmptyLinks(file) assertNoEmptySpans(file) + assertNoUnsubstitutedTemplatesInHtml(file) } } } diff --git a/integration-tests/gradle/src/integrationTest/kotlin/org/jetbrains/dokka/it/gradle/kotlin/StdlibGradleIntegrationTest.kt b/integration-tests/gradle/src/integrationTest/kotlin/org/jetbrains/dokka/it/gradle/kotlin/StdlibGradleIntegrationTest.kt index ca768962..4f56ba55 100644 --- a/integration-tests/gradle/src/integrationTest/kotlin/org/jetbrains/dokka/it/gradle/kotlin/StdlibGradleIntegrationTest.kt +++ b/integration-tests/gradle/src/integrationTest/kotlin/org/jetbrains/dokka/it/gradle/kotlin/StdlibGradleIntegrationTest.kt @@ -45,6 +45,7 @@ class StdlibGradleIntegrationTest(override val versions: BuildVersions) : Abstra // assertNoHrefToMissingLocalFileOrDirectory(file) assertNoEmptyLinks(file) assertNoEmptySpans(file) + assertNoUnsubstitutedTemplatesInHtml(file) } } } diff --git a/integration-tests/src/main/kotlin/org/jetbrains/dokka/it/AbstractIntegrationTest.kt b/integration-tests/src/main/kotlin/org/jetbrains/dokka/it/AbstractIntegrationTest.kt index 7c08b534..a47adbc4 100644 --- a/integration-tests/src/main/kotlin/org/jetbrains/dokka/it/AbstractIntegrationTest.kt +++ b/integration-tests/src/main/kotlin/org/jetbrains/dokka/it/AbstractIntegrationTest.kt @@ -18,13 +18,12 @@ abstract class AbstractIntegrationTest { val projectDir get() = File(temporaryTestFolder.root, "project") - fun File.allDescendentsWithExtension(extension: String): Sequence<File> { - return this.walkTopDown().filter { it.isFile && it.extension == extension } - } + fun File.allDescendentsWithExtension(extension: String): Sequence<File> = + this.walkTopDown().filter { it.isFile && it.extension == extension } - fun File.allHtmlFiles(): Sequence<File> { - return allDescendentsWithExtension("html") - } + fun File.allHtmlFiles(): Sequence<File> = allDescendentsWithExtension("html") + + fun File.allGfmFiles(): Sequence<File> = allDescendentsWithExtension("md") protected fun assertContainsNoErrorClass(file: File) { val fileText = file.readText() @@ -103,4 +102,12 @@ abstract class AbstractIntegrationTest { "Unexpected empty <span></span> in file ${file.path}" ) } + + protected fun assertNoUnsubstitutedTemplatesInHtml(file: File) { + val parsedFile = Jsoup.parse(file, "UTF-8") + assertTrue( + parsedFile.select("dokka-template-command").isEmpty(), + "Expected all templates to be substituted" + ) + } } diff --git a/plugins/all-modules-page/build.gradle.kts b/plugins/all-modules-page/build.gradle.kts index ecf8a384..c6e88574 100644 --- a/plugins/all-modules-page/build.gradle.kts +++ b/plugins/all-modules-page/build.gradle.kts @@ -6,10 +6,17 @@ registerDokkaArtifactPublication("dokkaAllModulesPage") { dependencies { implementation(project(":plugins:base")) + testImplementation(project(":plugins:base")) + testImplementation(project(":plugins:base:base-test-utils")) + testImplementation(project(":plugins:gfm")) + testImplementation(project(":plugins:gfm:gfm-template-processing")) val coroutines_version: String by project implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:$coroutines_version") implementation("org.jsoup:jsoup:1.12.1") implementation("com.fasterxml.jackson.module:jackson-module-kotlin:2.11.1") + + val kotlinx_html_version: String by project + testImplementation("org.jetbrains.kotlinx:kotlinx-html-jvm:$kotlinx_html_version") }
\ No newline at end of file diff --git a/plugins/all-modules-page/src/test/kotlin/MultiModuleDokkaTestGenerator.kt b/plugins/all-modules-page/src/test/kotlin/MultiModuleDokkaTestGenerator.kt new file mode 100644 index 00000000..c8542dfe --- /dev/null +++ b/plugins/all-modules-page/src/test/kotlin/MultiModuleDokkaTestGenerator.kt @@ -0,0 +1,81 @@ +package org.jetbrains.dokka.allModulesPage + +import org.jetbrains.dokka.CoreExtensions +import org.jetbrains.dokka.DokkaConfiguration +import org.jetbrains.dokka.DokkaGenerator +import org.jetbrains.dokka.pages.RootPageNode +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 MultiModuleDokkaTestGenerator( + configuration: DokkaConfiguration, + logger: DokkaLogger, + testMethods: MultiModuleTestMethods, + additionalPlugins: List<DokkaPlugin> = emptyList() +) : DokkaTestGenerator<MultiModuleTestMethods>( + configuration, + logger, + testMethods, + additionalPlugins + AllModulesPagePlugin() +) { + override fun generate() = with(testMethods) { + val dokkaGenerator = DokkaGenerator(configuration, logger) + + val context = + dokkaGenerator.initializePlugins(configuration, logger, additionalPlugins + AllModulesPagePlugin()) + pluginsSetupStage(context) + + val generation = context.single(CoreExtensions.generation) as AllModulesPageGeneration + + val allModulesPage = generation.createAllModulesPage() + allModulesPageCreationStage(allModulesPage) + + val transformedPages = generation.transformAllModulesPage(allModulesPage) + pagesTransformationStage(transformedPages) + + generation.render(transformedPages) + renderingStage(transformedPages, context) + + generation.processSubmodules() + submoduleProcessingStage(context) + } + +} + +open class MultiModuleTestMethods( + open val pluginsSetupStage: (DokkaContext) -> Unit, + open val allModulesPageCreationStage: (RootPageNode) -> Unit, + open val pagesTransformationStage: (RootPageNode) -> Unit, + open val renderingStage: (RootPageNode, DokkaContext) -> Unit, + open val submoduleProcessingStage: (DokkaContext) -> Unit, +) : TestMethods + +class MultiModuleTestBuilder : TestBuilder<MultiModuleTestMethods>() { + var pluginsSetupStage: (DokkaContext) -> Unit = {} + var allModulesPageCreationStage: (RootPageNode) -> Unit = {} + var pagesTransformationStage: (RootPageNode) -> Unit = {} + var renderingStage: (RootPageNode, DokkaContext) -> Unit = { _, _ -> } + var submoduleProcessingStage: (DokkaContext) -> Unit = {} + + override fun build() = MultiModuleTestMethods( + pluginsSetupStage, + allModulesPageCreationStage, + pagesTransformationStage, + renderingStage, + submoduleProcessingStage, + ) +} + +abstract class MultiModuleAbstractTest(logger: TestLogger = TestLogger(DokkaConsoleLogger)) : + AbstractTest<MultiModuleTestMethods, MultiModuleTestBuilder, MultiModuleDokkaTestGenerator>( + ::MultiModuleTestBuilder, + ::MultiModuleDokkaTestGenerator, + logger, + ) diff --git a/plugins/all-modules-page/src/test/kotlin/org/jetbrains/dokka/allModulesPage/templates/AddToNavigationCommandResolutionTest.kt b/plugins/all-modules-page/src/test/kotlin/org/jetbrains/dokka/allModulesPage/templates/AddToNavigationCommandResolutionTest.kt new file mode 100644 index 00000000..f917916a --- /dev/null +++ b/plugins/all-modules-page/src/test/kotlin/org/jetbrains/dokka/allModulesPage/templates/AddToNavigationCommandResolutionTest.kt @@ -0,0 +1,137 @@ +package org.jetbrains.dokka.allModulesPage.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.allModulesPage.MultiModuleAbstractTest +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 + +class AddToNavigationCommandResolutionTest : MultiModuleAbstractTest() { + @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/all-modules-page/src/test/kotlin/org/jetbrains/dokka/allModulesPage/templates/AddToSearchCommandResolutionTest.kt b/plugins/all-modules-page/src/test/kotlin/org/jetbrains/dokka/allModulesPage/templates/AddToSearchCommandResolutionTest.kt new file mode 100644 index 00000000..238134c7 --- /dev/null +++ b/plugins/all-modules-page/src/test/kotlin/org/jetbrains/dokka/allModulesPage/templates/AddToSearchCommandResolutionTest.kt @@ -0,0 +1,90 @@ +package org.jetbrains.dokka.allModulesPage.templates + +import org.jetbrains.dokka.DokkaModuleDescriptionImpl +import org.jetbrains.dokka.allModulesPage.MultiModuleAbstractTest +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 : MultiModuleAbstractTest() { + 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<List<SearchRecord>>(outputDir.resolve("scripts/${fileName}").readText()) + assertEquals(expected, output.sortedBy { it.location }) + + val outputFromModule1 = parseJson<List<SearchRecord>>(module1Navigation.readText()) + assertEquals(expected, outputFromModule1.sortedBy { it.location }) + + val outputFromModule2 = parseJson<List<SearchRecord>>(module2Navigation.readText()) + assertEquals(expected, outputFromModule2.sortedBy { it.location }) + } + } + } + + private fun setupTestDirectoriesWithContent(fileName: String): List<File> { + 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/all-modules-page/src/test/kotlin/org/jetbrains/dokka/allModulesPage/templates/ResolveLinkCommandResolutionTest.kt b/plugins/all-modules-page/src/test/kotlin/org/jetbrains/dokka/allModulesPage/templates/ResolveLinkCommandResolutionTest.kt new file mode 100644 index 00000000..1b4e8638 --- /dev/null +++ b/plugins/all-modules-page/src/test/kotlin/org/jetbrains/dokka/allModulesPage/templates/ResolveLinkCommandResolutionTest.kt @@ -0,0 +1,107 @@ +package org.jetbrains.dokka.allModulesPage.templates + +import kotlinx.html.a +import kotlinx.html.span +import kotlinx.html.stream.createHTML +import org.jetbrains.dokka.DokkaModuleDescriptionImpl +import org.jetbrains.dokka.allModulesPage.MultiModuleAbstractTest +import org.jetbrains.dokka.base.renderers.html.templateCommand +import org.jetbrains.dokka.base.resolvers.shared.RecognizedLinkFormat +import org.jetbrains.dokka.base.templating.ResolveLinkCommand +import org.jetbrains.dokka.links.DRI +import org.junit.Rule +import org.junit.jupiter.api.Test +import org.junit.rules.TemporaryFolder +import java.io.File + +class ResolveLinkCommandResolutionTest : MultiModuleAbstractTest() { + @get:Rule + val folder: TemporaryFolder = TemporaryFolder() + + fun 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 = folder.root + } + + @Test + fun `should resolve link to another module`() { + val testedDri = DRI( + packageName = "package2", + classNames = "Sample", + ) + val link = createHTML().templateCommand(ResolveLinkCommand(testedDri)) { + span { + +"Sample" + } + } + + val expected = createHTML().a { + href = "../../module2/module2/package2/-sample/index.html" + span { + +"Sample" + } + } + + val contentFile = setup(link) + val configuration = configuration() + + testFromData(configuration, preserveOutputLocation = true) { + submoduleProcessingStage = { + assertHtmlEqualsIgnoringWhitespace(expected, contentFile.readText()) + } + } + } + + @Test + fun `should produce content when link is not resolvable`() { + val testedDri = DRI( + packageName = "not-resolvable-package", + classNames = "Sample", + ) + val link = createHTML().templateCommand(ResolveLinkCommand(testedDri)) { + span { + +"Sample" + } + } + + val expected = createHTML().span { + attributes["data-unresolved-link"] = testedDri.toString() + span { + +"Sample" + } + } + + val contentFile = setup(link) + val configuration = configuration() + + testFromData(configuration, preserveOutputLocation = true) { + submoduleProcessingStage = { + assertHtmlEqualsIgnoringWhitespace(expected, contentFile.readText()) + } + } + } + + fun setup(content: String): File { + folder.create() + val innerModule1 = folder.newFolder("module1", "module1") + val innerModule2 = folder.newFolder("module2", "module2") + val packageList = innerModule2.resolve("package-list") + packageList.writeText(mockedPackageListForPackages(RecognizedLinkFormat.DokkaHtml, "package2")) + val contentFile = innerModule1.resolve("index.html") + contentFile.writeText(content) + return contentFile + } +}
\ No newline at end of file diff --git a/plugins/all-modules-page/src/test/kotlin/org/jetbrains/dokka/allModulesPage/templates/ResolveLinkGfmCommandResolutionTest.kt b/plugins/all-modules-page/src/test/kotlin/org/jetbrains/dokka/allModulesPage/templates/ResolveLinkGfmCommandResolutionTest.kt new file mode 100644 index 00000000..62aa9338 --- /dev/null +++ b/plugins/all-modules-page/src/test/kotlin/org/jetbrains/dokka/allModulesPage/templates/ResolveLinkGfmCommandResolutionTest.kt @@ -0,0 +1,74 @@ +package org.jetbrains.dokka.allModulesPage.templates + +import org.jetbrains.dokka.DokkaModuleDescriptionImpl +import org.jetbrains.dokka.allModulesPage.MultiModuleAbstractTest +import org.jetbrains.dokka.base.resolvers.shared.RecognizedLinkFormat +import org.jetbrains.dokka.gfm.GfmCommand.Companion.templateCommand +import org.jetbrains.dokka.gfm.GfmPlugin +import org.jetbrains.dokka.gfm.ResolveLinkGfmCommand +import org.jetbrains.dokka.gfm.templateProcessing.GfmTemplateProcessingPlugin +import org.jetbrains.dokka.links.DRI +import org.junit.Rule +import org.junit.jupiter.api.Test +import org.junit.rules.TemporaryFolder +import java.io.File +import kotlin.test.assertEquals + +class ResolveLinkGfmCommandResolutionTest : MultiModuleAbstractTest() { + @get:Rule + val folder: TemporaryFolder = TemporaryFolder() + + fun 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 = folder.root + } + + @Test + fun `should resolve link to another module`(){ + val testedDri = DRI( + packageName = "package2", + classNames = "Sample", + ) + + val link = StringBuilder().apply { + templateCommand(ResolveLinkGfmCommand(testedDri)){ + append("Sample text inside") + } + }.toString() + + val expected = "[Sample text inside](../../module2/module2/package2/-sample/index.md)" + + val content = setup(link) + val configuration = configuration() + + testFromData(configuration, pluginOverrides = listOf(GfmTemplateProcessingPlugin(), GfmPlugin()), preserveOutputLocation = true) { + submoduleProcessingStage = { + assertEquals(expected, content.readText().trim()) + } + } + } + + fun setup(content: String): File { + folder.create() + val innerModule1 = folder.newFolder("module1", "module1") + val innerModule2 = folder.newFolder("module2", "module2") + val packageList = innerModule2.resolve("package-list") + packageList.writeText(mockedPackageListForPackages(RecognizedLinkFormat.DokkaGFM, "package2")) + val contentFile = innerModule1.resolve("index.md") + contentFile.writeText(content) + return contentFile + } +}
\ No newline at end of file diff --git a/plugins/all-modules-page/src/test/kotlin/org/jetbrains/dokka/allModulesPage/templates/SubstitutionCommandResolutionTest.kt b/plugins/all-modules-page/src/test/kotlin/org/jetbrains/dokka/allModulesPage/templates/SubstitutionCommandResolutionTest.kt new file mode 100644 index 00000000..89984b46 --- /dev/null +++ b/plugins/all-modules-page/src/test/kotlin/org/jetbrains/dokka/allModulesPage/templates/SubstitutionCommandResolutionTest.kt @@ -0,0 +1,69 @@ +package org.jetbrains.dokka.allModulesPage.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.allModulesPage.MultiModuleAbstractTest +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 java.io.File + +class SubstitutionCommandResolutionTest : MultiModuleAbstractTest() { + + @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/all-modules-page/src/test/kotlin/org/jetbrains/dokka/allModulesPage/templates/assertHtmlEqualsIgnoringWhitespace.kt b/plugins/all-modules-page/src/test/kotlin/org/jetbrains/dokka/allModulesPage/templates/assertHtmlEqualsIgnoringWhitespace.kt new file mode 100644 index 00000000..5a9ff531 --- /dev/null +++ b/plugins/all-modules-page/src/test/kotlin/org/jetbrains/dokka/allModulesPage/templates/assertHtmlEqualsIgnoringWhitespace.kt @@ -0,0 +1,18 @@ +package org.jetbrains.dokka.allModulesPage.templates + +import junit.framework.Assert.assertEquals +import org.jsoup.Jsoup + +/** + * Parses it using JSOUP, trims whitespace at the end of the line and asserts if they are equal + * parsing is required to unify the formatting + */ +fun assertHtmlEqualsIgnoringWhitespace(expected: String, actual: String) { + assertEquals( + Jsoup.parse(expected).outerHtml().trimSpacesAtTheEndOfLine(), + Jsoup.parse(actual).outerHtml().trimSpacesAtTheEndOfLine() + ) +} + +private fun String.trimSpacesAtTheEndOfLine(): String = + replace(" \n", "\n")
\ No newline at end of file diff --git a/plugins/all-modules-page/src/test/kotlin/org/jetbrains/dokka/allModulesPage/templates/mockedPackageListFactory.kt b/plugins/all-modules-page/src/test/kotlin/org/jetbrains/dokka/allModulesPage/templates/mockedPackageListFactory.kt new file mode 100644 index 00000000..7a10041b --- /dev/null +++ b/plugins/all-modules-page/src/test/kotlin/org/jetbrains/dokka/allModulesPage/templates/mockedPackageListFactory.kt @@ -0,0 +1,12 @@ +package org.jetbrains.dokka.allModulesPage.templates + +import org.jetbrains.dokka.base.renderers.PackageListService +import org.jetbrains.dokka.base.resolvers.shared.RecognizedLinkFormat + +internal fun mockedPackageListForPackages(format: RecognizedLinkFormat, vararg packages: String): String = + """ + ${PackageListService.DOKKA_PARAM_PREFIX}.format:${format.formatName} + ${PackageListService.DOKKA_PARAM_PREFIX}.linkExtension:${format.linkExtension} + + ${packages.sorted().joinToString(separator = "\n", postfix = "\n") { it }} + """.trimIndent()
\ No newline at end of file diff --git a/plugins/base/base-test-utils/src/main/kotlin/testRunner/baseTestApi.kt b/plugins/base/base-test-utils/src/main/kotlin/testRunner/baseTestApi.kt index a0c681eb..b8143a30 100644 --- a/plugins/base/base-test-utils/src/main/kotlin/testRunner/baseTestApi.kt +++ b/plugins/base/base-test-utils/src/main/kotlin/testRunner/baseTestApi.kt @@ -9,10 +9,7 @@ import org.jetbrains.dokka.pages.RootPageNode 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.testApi.testRunner.* import org.jetbrains.dokka.utilities.DokkaConsoleLogger import org.jetbrains.dokka.utilities.DokkaLogger @@ -69,7 +66,7 @@ data class BaseTestMethods( override val pagesGenerationStage: (RootPageNode) -> Unit, override val pagesTransformationStage: (RootPageNode) -> Unit, override val renderingStage: (RootPageNode, DokkaContext) -> Unit -) : TestMethods( +) : CoreTestMethods( pluginsSetupStage, verificationStage, documentablesCreationStage, diff --git a/plugins/base/src/main/kotlin/resolvers/shared/PackageList.kt b/plugins/base/src/main/kotlin/resolvers/shared/PackageList.kt index 089bda55..a96cab82 100644 --- a/plugins/base/src/main/kotlin/resolvers/shared/PackageList.kt +++ b/plugins/base/src/main/kotlin/resolvers/shared/PackageList.kt @@ -14,7 +14,10 @@ data class PackageList( if (offlineMode && url.protocol.toLowerCase() != "file") return null - val packageListStream = url.readContent() + val packageListStream = kotlin.runCatching { url.readContent() }.onFailure { + println("Failed to download package-list from $url") + return null + }.getOrThrow() val (params, packages) = packageListStream .bufferedReader() diff --git a/plugins/gfm/gfm-template-processing/src/main/kotlin/org/jetbrains/dokka/gfm/templateProcessing/GfmTemplateProcessingStrategy.kt b/plugins/gfm/gfm-template-processing/src/main/kotlin/org/jetbrains/dokka/gfm/templateProcessing/GfmTemplateProcessingStrategy.kt index b2ef4d06..3f2bbd3e 100644 --- a/plugins/gfm/gfm-template-processing/src/main/kotlin/org/jetbrains/dokka/gfm/templateProcessing/GfmTemplateProcessingStrategy.kt +++ b/plugins/gfm/gfm-template-processing/src/main/kotlin/org/jetbrains/dokka/gfm/templateProcessing/GfmTemplateProcessingStrategy.kt @@ -15,28 +15,35 @@ import org.jetbrains.dokka.links.DRI import org.jetbrains.dokka.plugability.DokkaContext import org.jetbrains.dokka.plugability.plugin import org.jetbrains.dokka.plugability.querySingle +import java.io.BufferedWriter import java.io.File -class GfmTemplateProcessingStrategy(context: DokkaContext) : TemplateProcessingStrategy { +class GfmTemplateProcessingStrategy(val context: DokkaContext) : TemplateProcessingStrategy { - private val externalModuleLinkResolver = context.plugin<AllModulesPagePlugin>().querySingle { externalModuleLinkResolver } + private val externalModuleLinkResolver = + context.plugin<AllModulesPagePlugin>().querySingle { externalModuleLinkResolver } override suspend fun process(input: File, output: File): Boolean = coroutineScope { if (input.extension == "md") { launch(IO) { input.bufferedReader().use { reader -> - output.bufferedWriter().use { writer -> - do { - val line = reader.readLine() - if (line != null) { - writer.write(line.replace(templateCommandRegex) { - when (val command = parseJson<GfmCommand>(it.command)) { - is ResolveLinkGfmCommand -> resolveLink(output, command.dri, it.label) - } - }) - writer.newLine() + //This should also work whenever we have a misconfigured dokka and output is pointing to the input + //the same way that html processing does + if (input.absolutePath == output.absolutePath) { + context.logger.info("Attempting to process GFM templates in place for directory $input, this suggests miss configuration.") + val lines = reader.readLines() + output.bufferedWriter().use { writer -> + lines.forEach { line -> + writer.processAndWrite(line, output) } - } while (line != null) + + } + } else { + output.bufferedWriter().use { writer -> + reader.lineSequence().forEach { line -> + writer.processAndWrite(line, output) + } + } } } } @@ -44,6 +51,19 @@ class GfmTemplateProcessingStrategy(context: DokkaContext) : TemplateProcessingS } else false } + private fun BufferedWriter.processAndWrite(line: String, output: File) = + processLine(line, output).run { + write(this) + newLine() + } + + private fun processLine(line: String, output: File): String = + line.replace(templateCommandRegex) { + when (val command = parseJson<GfmCommand>(it.command)) { + is ResolveLinkGfmCommand -> resolveLink(output, command.dri, it.label) + } + } + private fun resolveLink(fileContext: File, dri: DRI, label: String): String = externalModuleLinkResolver.resolve(dri, fileContext)?.let { address -> "[$label]($address)" |