Dokka platform changes needed to implement Devsite requirements.

15 files changed, 89 insertions, 28 deletions

diff --git a/core/src/main/kotlin/Formats/ExtraOutlineServices.kt b/core/src/main/kotlin/Formats/ExtraOutlineServices.kt
new file mode 100644
index 000000000..e4eeac01a
--- /dev/null
+++ b/core/src/main/kotlin/Formats/ExtraOutlineServices.kt
@@ -0,0 +1,20 @@
+package org.jetbrains.dokka
+
+import java.io.File
+
+/**
+ * Outline service that is responsible for generating a single outline format.
+ *
+ * TODO: port existing implementations of ExtraOutlineService to OutlineService, and remove this.
+ */
+interface ExtraOutlineService {
+    fun getFileName(): String
+    fun getFile(location: Location): File
+    fun format(node: DocumentationNode): String
+}
+
+/**
+ * Holder of all of the extra outline services needed for a StandardFormat, in addition to the main
+ * [OutlineFormatService].
+ */
+abstract class ExtraOutlineServices(vararg val services: ExtraOutlineService)
diff --git a/core/src/main/kotlin/Formats/FormatDescriptor.kt b/core/src/main/kotlin/Formats/FormatDescriptor.kt
index fc925f409..e422aa14a 100644
--- a/core/src/main/kotlin/Formats/FormatDescriptor.kt
+++ b/core/src/main/kotlin/Formats/FormatDescriptor.kt
@@ -12,4 +12,5 @@ interface FormatDescriptor {
     val javaDocumentationBuilderClass: KClass<out JavaDocumentationBuilder>
     val sampleProcessingService: KClass<out SampleProcessingService>
     val packageListServiceClass: KClass<out PackageListService>?
+    val extraOutlineServices: KClass<out ExtraOutlineServices>?
 }
diff --git a/core/src/main/kotlin/Formats/HtmlFormatService.kt b/core/src/main/kotlin/Formats/HtmlFormatService.kt
index b66724348..ce9acb26c 100644
--- a/core/src/main/kotlin/Formats/HtmlFormatService.kt
+++ b/core/src/main/kotlin/Formats/HtmlFormatService.kt
@@ -105,6 +105,8 @@ open class HtmlFormatService @Inject constructor(@Named("folders") locationServi
         callback("/dokka/styles/style.css", "style.css")
     }
 
+    override fun getOutlineFileName(): String = "index"
+
     override fun createOutputBuilder(to: StringBuilder, location: Location) =
         HtmlOutputBuilder(to, location, locationService, languageService, extension, impliedPlatforms, templateService)
 
@@ -114,7 +116,7 @@ open class HtmlFormatService @Inject constructor(@Named("folders") locationServi
         templateService.appendFooter(to)
     }
 
-    override fun getOutlineFileName(location: Location): File {
+    override fun getOutlineFile(location: Location): File {
         return File("${location.path}-outline.html")
     }
 
@@ -133,7 +135,7 @@ open class HtmlFormatService @Inject constructor(@Named("folders") locationServi
     }
 }
 
-private fun LocationService.calcPathToRoot(location: Location): Path {
+fun LocationService.calcPathToRoot(location: Location): Path {
     val path = Paths.get(location.path)
     return path.parent?.relativize(Paths.get(root.path + '/')) ?: path
 }
diff --git a/core/src/main/kotlin/Formats/OutlineService.kt b/core/src/main/kotlin/Formats/OutlineService.kt
index 3c31ba57f..42151ffbb 100644
--- a/core/src/main/kotlin/Formats/OutlineService.kt
+++ b/core/src/main/kotlin/Formats/OutlineService.kt
@@ -6,8 +6,8 @@ import java.io.File
  * Service for building the outline of the package contents.
  */
 interface OutlineFormatService {
-    fun getOutlineFileName(location: Location): File
-
+    fun getOutlineFile(location: Location): File
+    fun getOutlineFileName(): String
     fun appendOutlineHeader(location: Location, node: DocumentationNode, to: StringBuilder)
     fun appendOutlineLevel(to: StringBuilder, body: () -> Unit)
 
diff --git a/core/src/main/kotlin/Formats/StandardFormats.kt b/core/src/main/kotlin/Formats/StandardFormats.kt
index fad65ff1f..cc96b22a9 100644
--- a/core/src/main/kotlin/Formats/StandardFormats.kt
+++ b/core/src/main/kotlin/Formats/StandardFormats.kt
@@ -10,10 +10,11 @@ abstract class KotlinFormatDescriptorBase : FormatDescriptor {
     override val packageDocumentationBuilderClass = KotlinPackageDocumentationBuilder::class
     override val javaDocumentationBuilderClass = KotlinJavaDocumentationBuilder::class
 
-    override val generatorServiceClass = FileGenerator::class
+    override val generatorServiceClass: KClass<out Generator> = FileGenerator::class
     override val outlineServiceClass: KClass<out OutlineFormatService>? = null
     override val sampleProcessingService: KClass<out SampleProcessingService> = DefaultSampleProcessingService::class
     override val packageListServiceClass: KClass<out PackageListService>? = DefaultPackageListService::class
+    override val extraOutlineServices: KClass<out ExtraOutlineServices>? = null
 }
 
 class HtmlFormatDescriptor : KotlinFormatDescriptorBase() {
@@ -29,6 +30,7 @@ class HtmlAsJavaFormatDescriptor : FormatDescriptor {
     override val javaDocumentationBuilderClass = JavaPsiDocumentationBuilder::class
     override val sampleProcessingService: KClass<out SampleProcessingService> = DefaultSampleProcessingService::class
     override val packageListServiceClass: KClass<out PackageListService>? = DefaultPackageListService::class
+    override val extraOutlineServices: KClass<out ExtraOutlineServices>? = null
 }
 
 class KotlinWebsiteFormatDescriptor : KotlinFormatDescriptorBase() {
diff --git a/core/src/main/kotlin/Formats/StructuredFormatService.kt b/core/src/main/kotlin/Formats/StructuredFormatService.kt
index a8b000b7b..63f51f958 100644
--- a/core/src/main/kotlin/Formats/StructuredFormatService.kt
+++ b/core/src/main/kotlin/Formats/StructuredFormatService.kt
@@ -286,7 +286,7 @@ abstract class StructuredOutputBuilder(val to: StringBuilder,
                 singleNode.appendPlatforms()
                 appendContent(singleNode.content)
             } else {
-                val breakdownByName = nodes.groupBy { node -> node.name }
+                val breakdownByName = nodes.groupBy { node -> getNameForHeader(node) }
                 for ((name, items) in breakdownByName) {
                     if (!noHeader)
                         appendHeader { appendText(name) }
@@ -295,7 +295,11 @@ abstract class StructuredOutputBuilder(val to: StringBuilder,
             }
         }
 
-        private fun appendDocumentation(overloads: Iterable<DocumentationNode>, isSingleNode: Boolean) {
+        open fun getNameForHeader(node: DocumentationNode): String {
+            return node.name
+        }
+
+        fun appendDocumentation(overloads: Iterable<DocumentationNode>, isSingleNode: Boolean) {
             val breakdownBySummary = overloads.groupByTo(LinkedHashMap()) { node -> node.content }
 
             if (breakdownBySummary.size == 1) {
@@ -311,7 +315,7 @@ abstract class StructuredOutputBuilder(val to: StringBuilder,
             }
         }
 
-        private fun formatOverloadGroup(items: List<DocumentationNode>, isSingleNode: Boolean = false) {
+        fun formatOverloadGroup(items: List<DocumentationNode>, isSingleNode: Boolean = false) {
             for ((index, item) in items.withIndex()) {
                 if (index > 0) appendLine()
                 val rendered = languageService.render(item)
@@ -377,7 +381,7 @@ abstract class StructuredOutputBuilder(val to: StringBuilder,
             }
         }
 
-        private fun DocumentationNode.appendPlatforms() {
+        fun DocumentationNode.appendPlatforms() {
             val platforms = if (isModuleOrPackage())
                 platformsToShow.toSet() + platformsOfItems(members)
             else
@@ -437,7 +441,7 @@ abstract class StructuredOutputBuilder(val to: StringBuilder,
         }
     }
 
-    inner class GroupNodePageBuilder(val node: DocumentationNode) : PageBuilder(listOf(node)) {
+    open inner class GroupNodePageBuilder(val node: DocumentationNode) : PageBuilder(listOf(node)) {
 
         override fun build() {
             val breakdownByLocation = node.path.filterNot { it.name.isEmpty() }.map { link(node, it) }
@@ -467,7 +471,7 @@ abstract class StructuredOutputBuilder(val to: StringBuilder,
         }
     }
 
-    inner class SingleNodePageBuilder(val node: DocumentationNode, noHeader: Boolean = false)
+    open inner class SingleNodePageBuilder(val node: DocumentationNode, noHeader: Boolean = false)
         : PageBuilder(listOf(node), noHeader) {
 
         override fun build() {
@@ -612,7 +616,7 @@ abstract class StructuredOutputBuilder(val to: StringBuilder,
         }
     }
 
-    inner class AllTypesNodeBuilder(val node: DocumentationNode)
+    open inner class AllTypesNodeBuilder(val node: DocumentationNode)
         : PageBuilder(listOf(node)) {
 
         override fun build() {
diff --git a/core/src/main/kotlin/Formats/YamlOutlineService.kt b/core/src/main/kotlin/Formats/YamlOutlineService.kt
index 7968824cd..39a5b9b3a 100644
--- a/core/src/main/kotlin/Formats/YamlOutlineService.kt
+++ b/core/src/main/kotlin/Formats/YamlOutlineService.kt
@@ -5,7 +5,7 @@ import java.io.File
 
 class YamlOutlineService @Inject constructor(val locationService: LocationService,
                          val languageService: LanguageService) : OutlineFormatService {
-    override fun getOutlineFileName(location: Location): File = File("${location.path}.yml")
+    override fun getOutlineFile(location: Location): File = File("${location.path}.yml")
 
     var outlineLevel = 0
     override fun appendOutlineHeader(location: Location, node: DocumentationNode, to: StringBuilder) {
@@ -21,4 +21,6 @@ class YamlOutlineService @Inject constructor(val locationService: LocationServic
         body()
         outlineLevel--
     }
+
+    override fun getOutlineFileName(): String = "index"
 }
diff --git a/core/src/main/kotlin/Generation/FileGenerator.kt b/core/src/main/kotlin/Generation/FileGenerator.kt
index e055c537d..f9948610b 100644
--- a/core/src/main/kotlin/Generation/FileGenerator.kt
+++ b/core/src/main/kotlin/Generation/FileGenerator.kt
@@ -6,12 +6,13 @@ import java.io.FileOutputStream
 import java.io.IOException
 import java.io.OutputStreamWriter
 
-class FileGenerator @Inject constructor(val locationService: FileLocationService) : Generator {
+open class FileGenerator @Inject constructor(val locationService: FileLocationService) : Generator {
 
     @set:Inject(optional = true) var outlineService: OutlineFormatService? = null
     @set:Inject(optional = true) lateinit var formatService: FormatService
     @set:Inject(optional = true) lateinit var options: DocumentationOptions
     @set:Inject(optional = true) var packageListService: PackageListService? = null
+    @set:Inject(optional = true) var extraOutlineServices: ExtraOutlineServices? = null
 
     override fun buildPages(nodes: Iterable<DocumentationNode>) {
         val specificLocationService = locationService.withExtension(formatService.extension)
@@ -34,8 +35,10 @@ class FileGenerator @Inject constructor(val locationService: FileLocationService
 
     override fun buildOutlines(nodes: Iterable<DocumentationNode>) {
         val outlineService = this.outlineService ?: return
-        for ((location, items) in nodes.groupBy { locationService.location(it) }) {
-            val file = outlineService.getOutlineFileName(location)
+        for ((location, items) in nodes.groupBy {
+            locationService.location(it, outlineService.getOutlineFileName())
+        }) {
+            val file = outlineService.getOutlineFile(location)
             file.parentFile?.mkdirsOrFail()
             FileOutputStream(file).use {
                 OutputStreamWriter(it, Charsets.UTF_8).use {
@@ -45,6 +48,21 @@ class FileGenerator @Inject constructor(val locationService: FileLocationService
         }
     }
 
+    override fun buildExtraOutlines(nodes: Iterable<DocumentationNode>) {
+        val extraOutlinesServices = this.extraOutlineServices ?: return
+        if (extraOutlinesServices.services.isEmpty()) return
+        val rootNode = nodes.first()
+        for (service in extraOutlinesServices.services) {
+            val file = service.getFile(locationService.location(rootNode, service.getFileName()))
+            file.parentFile?.mkdirsOrFail()
+            FileOutputStream(file).use {
+                OutputStreamWriter(it, Charsets.UTF_8).use {
+                    it.write(service.format(rootNode))
+                }
+            }
+        }
+    }
+
     override fun buildSupportFiles() {
         formatService.enumerateSupportFiles { resource, targetPath ->
             FileOutputStream(locationService.location(listOf(targetPath), false).file).use {
diff --git a/core/src/main/kotlin/Generation/Generator.kt b/core/src/main/kotlin/Generation/Generator.kt
index 76a5f3506..53745e47e 100644
--- a/core/src/main/kotlin/Generation/Generator.kt
+++ b/core/src/main/kotlin/Generation/Generator.kt
@@ -5,6 +5,7 @@ interface Generator {
     fun buildOutlines(nodes: Iterable<DocumentationNode>)
     fun buildSupportFiles()
     fun buildPackageList(nodes: Iterable<DocumentationNode>)
+    fun buildExtraOutlines(nodes: Iterable<DocumentationNode>)
 }
 
 fun Generator.buildAll(nodes: Iterable<DocumentationNode>) {
@@ -12,6 +13,7 @@ fun Generator.buildAll(nodes: Iterable<DocumentationNode>) {
     buildOutlines(nodes)
     buildSupportFiles()
     buildPackageList(nodes)
+    buildExtraOutlines(nodes)
 }
 
 fun Generator.buildPage(node: DocumentationNode): Unit = buildPages(listOf(node))
diff --git a/core/src/main/kotlin/Locations/FoldersLocationService.kt b/core/src/main/kotlin/Locations/FoldersLocationService.kt
index 83e1cf6ac..a2af03b1b 100644
--- a/core/src/main/kotlin/Locations/FoldersLocationService.kt
+++ b/core/src/main/kotlin/Locations/FoldersLocationService.kt
@@ -14,17 +14,18 @@ class FoldersLocationService @Inject constructor(@Named("outputDir") val rootFil
         return if (extension.isEmpty()) FoldersLocationService(rootFile, newExtension) else this
     }
 
-    override fun location(qualifiedName: List<String>, hasMembers: Boolean): FileLocation {
-        return FileLocation(File(rootFile, relativePathToNode(qualifiedName, hasMembers)).appendExtension(extension))
+    override fun location(qualifiedName: List<String>, hasMembers: Boolean, fileName: String): FileLocation {
+        return FileLocation(File(rootFile, relativePathToNode(qualifiedName, hasMembers, fileName))
+                .appendExtension(extension))
     }
 }
 
-fun relativePathToNode(qualifiedName: List<String>, hasMembers: Boolean): String {
+fun relativePathToNode(qualifiedName: List<String>, hasMembers: Boolean, fileName: String): String {
     val parts = qualifiedName.map { identifierToFilename(it) }.filterNot { it.isEmpty() }
     return if (!hasMembers) {
         // leaf node, use file in owner's folder
         parts.joinToString("/")
     } else {
-        parts.joinToString("/") + (if (parts.none()) "" else "/") + "index"
+        parts.joinToString("/") + (if (parts.none()) "" else "/") + fileName
     }
 }
diff --git a/core/src/main/kotlin/Locations/LocationService.kt b/core/src/main/kotlin/Locations/LocationService.kt
index 39f5942c7..e2e9f0a93 100644
--- a/core/src/main/kotlin/Locations/LocationService.kt
+++ b/core/src/main/kotlin/Locations/LocationService.kt
@@ -44,13 +44,15 @@ data class FileLocation(val file: File): Location {
 interface LocationService {
     fun withExtension(newExtension: String) = this
 
-    fun location(node: DocumentationNode): Location = location(node.path.map { it.name }, node.members.any())
+    fun location(node: DocumentationNode, fileName: String = "index"): Location =
+            location(node.path.map { it.name }, node.members.any(), fileName)
 
     /**
      * Calculates a location corresponding to the specified [qualifiedName].
      * @param hasMembers if true, the node for which the location is calculated has member nodes.
      */
-    fun location(qualifiedName: List<String>, hasMembers: Boolean): Location
+    fun location(qualifiedName: List<String>, hasMembers: Boolean,
+            fileName: String = "index"): Location
 
     val root: Location
 }
@@ -59,8 +61,9 @@ interface LocationService {
 interface FileLocationService: LocationService {
     override fun withExtension(newExtension: String): FileLocationService = this
 
-    override fun location(node: DocumentationNode): FileLocation = location(node.path.map { it.name }, node.members.any())
-    override fun location(qualifiedName: List<String>, hasMembers: Boolean): FileLocation
+    override fun location(node: DocumentationNode, fileName: String): FileLocation =
+            location(node.path.map { it.name }, node.members.any(), fileName)
+    override fun location(qualifiedName: List<String>, hasMembers: Boolean, fileName: String): FileLocation
 }
 
 
diff --git a/core/src/main/kotlin/Locations/SingleFolderLocationService.kt b/core/src/main/kotlin/Locations/SingleFolderLocationService.kt
index 1b4fdc286..456fd6ce6 100644
--- a/core/src/main/kotlin/Locations/SingleFolderLocationService.kt
+++ b/core/src/main/kotlin/Locations/SingleFolderLocationService.kt
@@ -10,7 +10,7 @@ class SingleFolderLocationService @Inject constructor(@Named("outputDir") val ro
     override fun withExtension(newExtension: String): FileLocationService =
         SingleFolderLocationService(rootFile, newExtension)
 
-    override fun location(qualifiedName: List<String>, hasMembers: Boolean): FileLocation {
+    override fun location(qualifiedName: List<String>, hasMembers: Boolean, fileName: String): FileLocation {
         val filename = qualifiedName.map { identifierToFilename(it) }.joinToString("-")
         return FileLocation(File(rootFile, filename).appendExtension(extension))
     }
diff --git a/core/src/main/kotlin/Utilities/DokkaModules.kt b/core/src/main/kotlin/Utilities/DokkaModules.kt
index 28c5dc45e..0d3ac582b 100644
--- a/core/src/main/kotlin/Utilities/DokkaModules.kt
+++ b/core/src/main/kotlin/Utilities/DokkaModules.kt
@@ -76,7 +76,9 @@ class DokkaOutputModule(val options: DocumentationOptions,
         descriptor.formatServiceClass?.let { clazz ->
             binder.bind(FormatService::class.java).to(clazz.java)
         }
-
+        descriptor.extraOutlineServices?.let { clazz ->
+            binder.bind(ExtraOutlineServices::class.java).to(clazz.java)
+        }
         binder.bind<Generator>().to(descriptor.generatorServiceClass.java)
 
         descriptor.packageListServiceClass?.let { binder.bind<PackageListService>().to(it.java) }
diff --git a/core/src/main/kotlin/javadoc/dokka-adapters.kt b/core/src/main/kotlin/javadoc/dokka-adapters.kt
index 9555aeb94..2de7b524a 100644
--- a/core/src/main/kotlin/javadoc/dokka-adapters.kt
+++ b/core/src/main/kotlin/javadoc/dokka-adapters.kt
@@ -26,6 +26,9 @@ class JavadocGenerator @Inject constructor(val options: DocumentationOptions, va
     override fun buildPackageList(nodes: Iterable<DocumentationNode>) {
         // handled by javadoc itself
     }
+
+    override fun buildExtraOutlines(nodes: Iterable<DocumentationNode>) {
+    }
 }
 
 class JavadocFormatDescriptor : FormatDescriptor {
@@ -36,4 +39,5 @@ class JavadocFormatDescriptor : FormatDescriptor {
     override val javaDocumentationBuilderClass = JavaPsiDocumentationBuilder::class
     override val sampleProcessingService = DefaultSampleProcessingService::class
     override val packageListServiceClass: KClass<out PackageListService>? = null
+    override val extraOutlineServices: KClass<out ExtraOutlineServices>? = null
 }
diff --git a/core/src/test/kotlin/TestAPI.kt b/core/src/test/kotlin/TestAPI.kt
index 4799cd935..d6b1a9037 100644
--- a/core/src/test/kotlin/TestAPI.kt
+++ b/core/src/test/kotlin/TestAPI.kt
@@ -253,8 +253,8 @@ class InMemoryLocation(override val path: String): Location {
 }
 
 object InMemoryLocationService: LocationService {
-    override fun location(qualifiedName: List<String>, hasMembers: Boolean) =
-            InMemoryLocation(relativePathToNode(qualifiedName, hasMembers))
+    override fun location(qualifiedName: List<String>, hasMembers: Boolean, fileName: String) =
+            InMemoryLocation(relativePathToNode(qualifiedName, hasMembers, fileName))
 
     override val root: Location
         get() = InMemoryLocation("")