Make logo replaceable #1339

core/src/main/kotlin/configuration.kt

@@ -29,6 +29,8 @@ object DokkaDefaults {
     const val sourceSetDisplayName = "JVM"
     const val sourceSetName = "main"
     val moduleVersion: String? = null
+    val customAssets = emptyList<File>()
+    val customStylesheets = emptyList<File>()
 }
 
 enum class Platform(val key: String) {
@@ -93,6 +95,8 @@ interface DokkaConfiguration : Serializable {
     val modules: List<DokkaModuleDescription>
     val pluginsClasspath: List<File>
     val pluginsConfiguration: Map<String, String>
+    val customStyleSheets: List<File>
+    val customAssets: List<File>
 
     interface DokkaSourceSet : Serializable {
         val sourceSetID: DokkaSourceSetID

core/src/main/kotlin/defaultConfiguration.kt

@@ -14,7 +14,9 @@ data class DokkaConfigurationImpl(
     override val pluginsClasspath: List<File> = emptyList(),
     override val pluginsConfiguration: Map<String, String> = emptyMap(),
     override val modules: List<DokkaModuleDescriptionImpl> = emptyList(),
-    override val failOnWarning: Boolean = DokkaDefaults.failOnWarning
+    override val failOnWarning: Boolean = DokkaDefaults.failOnWarning,
+    override val customStyleSheets: List<File> = DokkaDefaults.customStylesheets,
+    override val customAssets: List<File> = DokkaDefaults.customAssets
 ) : DokkaConfiguration
 
 

integration-tests/gradle/projects/it-basic/build.gradle.kts

@@ -40,4 +40,6 @@ tasks.withType<DokkaTask> {
             kotlinSourceSet(kotlin.sourceSets["test"])
         }
     }
+    customStyleSheets.set(listOf(file("customResources/logo-styles.css"), file("customResources/custom-style-to-add.css")))
+    customAssets.set(listOf(file("customResources/custom-resource.svg")))
 }

integration-tests/gradle/projects/it-basic/customResources/custom-style-to-add.css

@@ -0,0 +1 @@
+/* custom stylesheet */

integration-tests/gradle/projects/it-basic/customResources/logo-styles.css

@@ -0,0 +1,3 @@
+#logo {
+    background-image: url('https://upload.wikimedia.org/wikipedia/commons/9/9d/Ubuntu_logo.svg');
+}

integration-tests/gradle/src/integrationTest/kotlin/org/jetbrains/dokka/it/gradle/BasicGradleIntegrationTest.kt

@@ -25,6 +25,8 @@ class BasicGradleIntegrationTest(override val versions: BuildVersions) : Abstrac
             .forEach { topLevelFile -> topLevelFile.copyTo(File(projectDir, topLevelFile.name)) }
 
         File(templateProjectDir, "src").copyRecursively(File(projectDir, "src"))
+        val customResourcesDir = File(templateProjectDir, "customResources")
+        if(customResourcesDir.exists() && customResourcesDir.isDirectory) customResourcesDir.copyRecursively(File(projectDir, "customResources"))
     }
 
     @Test
@@ -104,6 +106,17 @@ class BasicGradleIntegrationTest(override val versions: BuildVersions) : Abstrac
             },
             "Expected `SampleJavaClass` source link to GitHub"
         )
+
+        assertEquals(
+            """#logo{background-image:url('https://upload.wikimedia.org/wikipedia/commons/9/9d/Ubuntu_logo.svg');}""",
+            stylesDir.resolve("logo-styles.css").readText().replace("\\s".toRegex(), ""),
+        )
+        assertTrue(stylesDir.resolve("custom-style-to-add.css").isFile)
+        assertEquals("""/* custom stylesheet */""", stylesDir.resolve("custom-style-to-add.css").readText())
+        allHtmlFiles().forEach { file ->
+            if(file.name != "navigation.html") assertTrue("custom-style-to-add.css" in file.readText(), "custom styles not added to html file ${file.name}")
+        }
+        assertTrue(imagesDir.resolve("custom-resource.svg").isFile)
     }
 
     private fun File.assertJavadocOutputDir() {

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

@@ -198,14 +198,14 @@ class DokkaBase : DokkaPlugin() {
         htmlPreprocessors with NavigationPageInstaller order { after(rootCreator) }
     }
 
-    val searchPageInstaller by extending {
-        htmlPreprocessors with SearchPageInstaller order { after(rootCreator) }
-    }
-
     val resourceInstaller by extending {
         htmlPreprocessors with ResourceInstaller order { after(rootCreator) }
     }
 
+    val customResourceInstaller by extending {
+        htmlPreprocessors providing { ctx -> CustomResourceInstaller(ctx.configuration) } order { after(resourceInstaller) }
+    }
+
     val styleAndScriptsAppender by extending {
         htmlPreprocessors with StyleAndScriptsAppender order { after(rootCreator) }
     }

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

@@ -33,7 +33,7 @@ class FileWriter(val context: DokkaContext): OutputWriter {
     }
 
     override suspend fun writeResources(pathFrom: String, pathTo: String) =
-        if (javaClass.getResource(pathFrom).toURI().toString().startsWith(jarUriPrefix)) {
+        if (javaClass.getResource(pathFrom)?.toURI()?.toString()?.startsWith(jarUriPrefix) == true) {
             copyFromJar(pathFrom, pathTo)
         } else {
             copyFromDirectory(pathFrom, pathTo)
@@ -42,17 +42,22 @@ class FileWriter(val context: DokkaContext): OutputWriter {
 
     private suspend fun copyFromDirectory(pathFrom: String, pathTo: String) {
         val dest = Paths.get(root.path, pathTo).toFile()
-        val uri = javaClass.getResource(pathFrom).toURI()
+        val uri = javaClass.getResource(pathFrom)?.toURI()
+        val file = uri?.let { File(it) } ?: File(pathFrom)
         withContext(Dispatchers.IO) {
-            File(uri).copyRecursively(dest, true)
+            file.copyRecursively(dest, true)
         }
     }
 
     private suspend fun copyFromJar(pathFrom: String, pathTo: String) {
         val rebase = fun(path: String) =
             "$pathTo/${path.removePrefix(pathFrom)}"
         val dest = Paths.get(root.path, pathTo).toFile()
-        dest.mkdirsOrFail()
+        if(dest.isDirectory){
+            dest.mkdirsOrFail()
+        } else {
+            dest.parentFile.mkdirsOrFail()
+        }
         val uri = javaClass.getResource(pathFrom).toURI()
         val fs = getFileSystemForURI(uri)
         val path = fs.getPath(pathFrom)

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

@@ -7,6 +7,7 @@ import kotlinx.html.h1
 import kotlinx.html.id
 import kotlinx.html.table
 import kotlinx.html.tbody
+import org.jetbrains.dokka.DokkaConfiguration
 import org.jetbrains.dokka.base.renderers.sourceSets
 import org.jetbrains.dokka.links.DRI
 import org.jetbrains.dokka.model.DEnum
@@ -16,28 +17,6 @@ import org.jetbrains.dokka.pages.*
 import org.jetbrains.dokka.plugability.DokkaContext
 import org.jetbrains.dokka.transformers.pages.PageTransformer
 
-
-object SearchPageInstaller : PageTransformer {
-    override fun invoke(input: RootPageNode) = input.modified(children = input.children + searchPage)
-
-    private val searchPage = RendererSpecificResourcePage(
-        name = "Search",
-        children = emptyList(),
-        strategy = RenderingStrategy<HtmlRenderer> {
-            buildHtml(it, listOf("styles/style.css", "scripts/pages.js", "scripts/search.js")) {
-                h1 {
-                    id = "searchTitle"
-                    text("Search results for ")
-                }
-                table {
-                    tbody {
-                        id = "searchTable"
-                    }
-                }
-            }
-        })
-}
-
 object NavigationPageInstaller : PageTransformer {
     private val mapper = jacksonObjectMapper()
 
@@ -88,10 +67,49 @@ object NavigationPageInstaller : PageTransformer {
         }.sortedBy { it.name.toLowerCase() }
 }
 
+class CustomResourceInstaller(val dokkaConfiguration: DokkaConfiguration) : PageTransformer {
+    private val customAssets = dokkaConfiguration.customAssets.map {
+        RendererSpecificResourcePage("images/${it.name}", emptyList(), RenderingStrategy.Copy(it.absolutePath))
+    }
+
+    private val customStylesheets = dokkaConfiguration.customStyleSheets.map {
+        RendererSpecificResourcePage("styles/${it.name}", emptyList(), RenderingStrategy.Copy(it.absolutePath))
+    }
+
+    override fun invoke(input: RootPageNode): RootPageNode {
+        val customResourcesPaths = (customAssets + customStylesheets).map { it.name }.toSet()
+        val withEmbeddedResources = input.transformContentPagesTree { it.modified(embeddedResources = it.embeddedResources + customResourcesPaths) }
+        val (currentResources, otherPages) = withEmbeddedResources.children.partition { it is RendererSpecificResourcePage }
+        return input.modified(children = otherPages + currentResources.filterNot { it.name in customResourcesPaths } + customAssets + customStylesheets)
+    }
+}
+
 object ResourceInstaller : PageTransformer {
-    override fun invoke(input: RootPageNode) = input.modified(children = input.children + resourcePages)
+    override fun invoke(input: RootPageNode) =
+        input.modified(children = input.children + resourcePages).transformContentPagesTree { page ->
+            page.modified(
+                embeddedResources = page.embeddedResources + scriptsPages + stylesPages
+            )
+        }
 
-    private val resourcePages = listOf("styles", "scripts", "images").map {
+    val stylesPages = listOf(
+        "styles/style.css",
+        "styles/logo-styles.css",
+        "styles/jetbrains-mono.css"
+    )
+    val scriptsPages = listOf(
+        "scripts/clipboard.js",
+        "scripts/navigation-loader.js",
+        "scripts/platform-content-handler.js",
+        "scripts/main.js"
+    )
+    val imagesPages = listOf(
+        "images/arrow_down.svg",
+        "images/docs_logo.svg",
+        "images/logo-icon.svg"
+    )
+
+    private val resourcePages = (stylesPages + scriptsPages + imagesPages).map {
         RendererSpecificResourcePage(it, emptyList(), RenderingStrategy.Copy("/dokka/$it"))
     }
 }
@@ -100,12 +118,7 @@ object StyleAndScriptsAppender : PageTransformer {
     override fun invoke(input: RootPageNode) = input.transformContentPagesTree {
         it.modified(
             embeddedResources = it.embeddedResources + listOf(
-                "styles/style.css",
-                "scripts/navigationLoader.js",
-                "scripts/platformContentHandler.js",
                 "scripts/sourceset_dependencies.js",
-                "scripts/clipboard.js",
-                "styles/jetbrains-mono.css"
             )
         )
     }

plugins/base/src/main/resources/dokka/styles/logo-styles.css

@@ -0,0 +1,3 @@
+#logo {
+    background-image: url(../images/docs_logo.svg);
+}

plugins/base/src/main/resources/dokka/styles/style.css

@@ -195,7 +195,6 @@
     background-size: 125px 26px;
     border-bottom: 1px solid #DADFE6;
     background-repeat: no-repeat;
-    background-image: url(../images/docs_logo.svg);
     background-origin: content-box;
     padding-left: 24px;
     padding-top: 24px;

runners/cli/src/main/kotlin/cli/main.kt

@@ -64,6 +64,16 @@ class GlobalArguments(args: Array<String>) : DokkaConfiguration {
         "Throw an exception if the generation exited with warnings"
     ).default(DokkaDefaults.failOnWarning)
 
+    override val customStyleSheets by parser.option(
+        ArgTypeFile,
+        description = "Custom stylesheets to add to output files"
+    ).delimiter(";")
+
+    override val customAssets by parser.option(
+        ArgTypeFile,
+        description = "Custom assets to add to output files"
+    ).delimiter(";")
+
     val globalPackageOptions by parser.option(
         ArgType.String,
         description = "List of package source sets in format \"prefix,-deprecated,-privateApi,+warnUndocumented,+suppress;...\" "
@@ -254,7 +264,7 @@ object ArgTypeFile : ArgType<File>(true) {
 object ArgTypePlatform : ArgType<Platform>(true) {
     override fun convert(value: kotlin.String, name: kotlin.String): Platform = Platform.fromString(value)
     override val description: kotlin.String
-        get() = "{ String thar represents paltform }"
+        get() = "{ String thar represents platform }"
 }
 
 object ArgTypePlugin : ArgType<Map<String, String>>(true) {

runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/AbstractDokkaTask.kt

@@ -8,9 +8,11 @@ import org.gradle.api.DefaultTask
 import org.gradle.api.Task
 import org.gradle.api.artifacts.Configuration
 import org.gradle.api.plugins.JavaBasePlugin
+import org.gradle.api.provider.ListProperty
 import org.gradle.api.provider.MapProperty
 import org.gradle.api.provider.Property
 import org.gradle.api.tasks.*
+import org.gradle.kotlin.dsl.listProperty
 import org.gradle.kotlin.dsl.mapProperty
 import org.jetbrains.dokka.DokkaBootstrap
 import org.jetbrains.dokka.DokkaConfigurationImpl
@@ -51,6 +53,12 @@ abstract class AbstractDokkaTask(
     @Input
     val pluginsConfiguration: MapProperty<String, String> = project.objects.mapProperty()
 
+    @Input
+    val customStyleSheets: ListProperty<File> = project.objects.listProperty()
+
+    @Input
+    val customAssets: ListProperty<File> = project.objects.listProperty()
+
     @Classpath
     val plugins: Configuration = project.maybeCreateDokkaPluginConfiguration(name)
 

runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/DokkaTask.kt

@@ -44,7 +44,9 @@ abstract class DokkaTask : AbstractDokkaTask(DokkaBootstrapImpl::class) {
             failOnWarning = failOnWarning.getSafe(),
             sourceSets = unsuppressedSourceSets.build(),
             pluginsConfiguration = pluginsConfiguration.getSafe(),
-            pluginsClasspath = plugins.resolve().toList()
+            pluginsClasspath = plugins.resolve().toList(),
+            customAssets = customAssets?.getSafe() ?: emptyList(),
+            customStyleSheets = customStyleSheets?.getSafe() ?: emptyList()
         )
     }
 }