Merge remote-tracking branch 'upstream/java-layout-html-format' into devsite-with-java-layout-html
diff --git a/core/src/main/kotlin/Formats/DacExtraOutlineServices.kt b/core/src/main/kotlin/Formats/DacExtraOutlineServices.kt
new file mode 100644
index 0000000..5a56b81
--- /dev/null
+++ b/core/src/main/kotlin/Formats/DacExtraOutlineServices.kt
@@ -0,0 +1,216 @@
+package org.jetbrains.dokka.Formats
+
+import org.jetbrains.dokka.DocumentationNode
+import org.jetbrains.dokka.LanguageService
+import org.jetbrains.dokka.NodeKind
+import org.jetbrains.dokka.qualifiedName
+import java.net.URI
+
+class DacNavOutlineService constructor(
+ val uriProvider: JavaLayoutHtmlUriProvider,
+ val languageService: LanguageService
+) : DacOutlineFormatService {
+ override fun computeOutlineURI(node: DocumentationNode): URI =
+ uriProvider.containerUri(node).resolve("navtree_data.js")
+
+ override fun format(uri: URI, to: Appendable, node: DocumentationNode) {
+ to.append("var NAVTREE_DATA_KT = ").appendNavTree(node.members).append(";")
+ }
+
+ private fun Appendable.appendNavTree(nodes: Iterable<DocumentationNode>): Appendable {
+ append("[ ")
+ var first = true
+ for (node in nodes) {
+ if (!first) append(", ")
+ first = false
+ val interfaces = node.getMembersOfKinds(NodeKind.Interface)
+ val classes = node.getMembersOfKinds(NodeKind.Class)
+ val objects = node.getMembersOfKinds(NodeKind.Object)
+ val annotations = node.getMembersOfKinds(NodeKind.AnnotationClass)
+ val enums = node.getMembersOfKinds(NodeKind.Enum)
+ val exceptions = node.getMembersOfKinds(NodeKind.Exception)
+
+ append("[ \"${node.name}\", \"${uriProvider.mainUriOrWarn(node)}\", [ ")
+ var needComma = false
+ if (interfaces.firstOrNull() != null) {
+ appendNavTreePagesOfKind("Interfaces", interfaces)
+ needComma = true
+ }
+ if (classes.firstOrNull() != null) {
+ if (needComma) append(", ")
+ appendNavTreePagesOfKind("Classes", classes)
+ needComma = true
+ }
+ if (objects.firstOrNull() != null) {
+ if (needComma) append(", ")
+ appendNavTreePagesOfKind("Objects", objects)
+ }
+ if (annotations.firstOrNull() != null) {
+ if (needComma) append(", ")
+ appendNavTreePagesOfKind("Annotations", annotations)
+ needComma = true
+ }
+ if (enums.firstOrNull() != null) {
+ if (needComma) append(", ")
+ appendNavTreePagesOfKind("Enums", enums)
+ needComma = true
+ }
+ if (exceptions.firstOrNull() != null) {
+ if (needComma) append(", ")
+ appendNavTreePagesOfKind("Exceptions", exceptions)
+ }
+ append(" ] ]")
+ }
+ append(" ]")
+ return this
+ }
+
+ private fun Appendable.appendNavTreePagesOfKind(kindTitle: String,
+ nodesOfKind: Iterable<DocumentationNode>): Appendable {
+ append("[ \"$kindTitle\", null, [ ")
+ var started = false
+ for (node in nodesOfKind) {
+ if (started) append(", ")
+ started = true
+ appendNavTreeChild(node)
+ }
+ append(" ], null, null ]")
+ return this
+ }
+
+ private fun Appendable.appendNavTreeChild(node: DocumentationNode): Appendable {
+ append("[ \"${node.nameWithOuterClass()}\", \"${uriProvider.tryGetMainUri(node)}\"")
+ append(", null, null, null ]")
+ return this
+ }
+}
+
+class DacSearchOutlineService(
+ val uriProvider: JavaLayoutHtmlUriProvider,
+ val languageService: LanguageService
+) : DacOutlineFormatService {
+
+ override fun computeOutlineURI(node: DocumentationNode): URI =
+ uriProvider.containerUri(node).resolve("lists.js")
+
+ override fun format(uri: URI, to: Appendable, node: DocumentationNode) {
+ val pageNodes = node.getAllPageNodes()
+ var id = 0
+ to.append("var ARCH_DATA = [\n")
+ var first = true
+ for (pageNode in pageNodes) {
+ if (pageNode.kind == NodeKind.Module) continue
+ if (!first) to.append(", \n")
+ first = false
+ to.append(" { " +
+ "id:$id, " +
+ "label:\"${pageNode.qualifiedName()}\", " +
+ "link:\"${uriProvider.mainUriOrWarn(node)}\", " +
+ "type:\"${pageNode.getClassOrPackage()}\", " +
+ "deprecated:\"false\" }")
+ id++
+ }
+ to.append("\n];")
+ }
+
+ private fun DocumentationNode.getClassOrPackage(): String =
+ if (hasOwnPage())
+ "class"
+ else if (isPackage()) {
+ "package"
+ } else {
+ ""
+ }
+
+ private fun DocumentationNode.getAllPageNodes(): Iterable<DocumentationNode> {
+ val allPageNodes = mutableListOf<DocumentationNode>()
+ recursiveSetAllPageNodes(allPageNodes)
+ return allPageNodes
+ }
+
+ private fun DocumentationNode.recursiveSetAllPageNodes(
+ allPageNodes: MutableList<DocumentationNode>) {
+ for (child in members) {
+ if (child.hasOwnPage() || child.isPackage()) {
+ allPageNodes.add(child)
+ child.qualifiedName()
+ child.recursiveSetAllPageNodes(allPageNodes)
+ }
+ }
+ }
+
+}
+
+/**
+ * Return all children of the node who are one of the selected `NodeKind`s. It recursively fetches
+ * all offspring, not just immediate children.
+ */
+fun DocumentationNode.getMembersOfKinds(vararg kinds: NodeKind): MutableList<DocumentationNode> {
+ val membersOfKind = mutableListOf<DocumentationNode>()
+ recursiveSetMembersOfKinds(kinds, membersOfKind)
+ return membersOfKind
+}
+
+private fun DocumentationNode.recursiveSetMembersOfKinds(kinds: Array<out NodeKind>,
+ membersOfKind: MutableList<DocumentationNode>) {
+ for (member in members) {
+ if (member.kind in kinds) {
+ membersOfKind.add(member)
+ }
+ member.recursiveSetMembersOfKinds(kinds, membersOfKind)
+ }
+}
+
+/**
+ * Returns whether or not this node owns a page. The criteria for whether a node owns a page is
+ * similar to the way javadoc is structured. Classes, Interfaces, Enums, AnnotationClasses,
+ * Exceptions, and Objects (Kotlin-specific) meet the criteria.
+ */
+fun DocumentationNode.hasOwnPage() =
+ kind == NodeKind.Class || kind == NodeKind.Interface || kind == NodeKind.Enum ||
+ kind == NodeKind.AnnotationClass || kind == NodeKind.Exception ||
+ kind == NodeKind.Object
+
+/**
+ * In most cases, this returns the short name of the `Type`. When the Type is an inner Type, it
+ * prepends the name with the containing Type name(s).
+ *
+ * For example, if you have a class named OuterClass and an inner class named InnerClass, this would
+ * return OuterClass.InnerClass.
+ *
+ */
+fun DocumentationNode.nameWithOuterClass(): String {
+ val nameBuilder = StringBuilder(name)
+ var parent = owner
+ if (hasOwnPage()) {
+ while (parent != null && parent.hasOwnPage()) {
+ nameBuilder.insert(0, "${parent.name}.")
+ parent = parent.owner
+ }
+ }
+ return nameBuilder.toString()
+}
+
+/**
+ * Return whether the node is a package.
+ */
+fun DocumentationNode.isPackage(): Boolean {
+ return kind == NodeKind.Package
+}
+
+/**
+ * Return the 'page owner' of this node. `DocumentationNode.hasOwnPage()` defines the criteria for
+ * a page owner. If this node is not a page owner, then it iterates up through its ancestors to
+ * find the first page owner.
+ */
+fun DocumentationNode.pageOwner(): DocumentationNode {
+ if (hasOwnPage() || owner == null) {
+ return this
+ } else {
+ var parent: DocumentationNode = owner!!
+ while (!parent.hasOwnPage() && !parent.isPackage()) {
+ parent = parent.owner!!
+ }
+ return parent
+ }
+}
\ No newline at end of file
diff --git a/core/src/main/kotlin/Formats/DacHtmlFormat.kt b/core/src/main/kotlin/Formats/DacHtmlFormat.kt
new file mode 100644
index 0000000..d4c6dd8
--- /dev/null
+++ b/core/src/main/kotlin/Formats/DacHtmlFormat.kt
@@ -0,0 +1,181 @@
+package org.jetbrains.dokka.Formats
+
+import com.google.inject.Inject
+import com.google.inject.name.Named
+import kotlinx.html.*
+import org.jetbrains.dokka.*
+import java.io.File
+import java.net.URI
+import kotlin.reflect.KClass
+
+/**
+ * Data structure used for generating `data-reference-resources-wrapper`.
+ */
+val nodeToFamilyMap = HashMap<DocumentationNode, List<DocumentationNode>>()
+
+/**
+ * On Devsite, certain headers and footers are needed for generating Devsite metadata.
+ */
+class DevsiteHtmlTemplateService @Inject constructor(
+ val uriProvider: JavaLayoutHtmlUriProvider, @Named("outputDir") val rootFile: File
+) : JavaLayoutHtmlTemplateService {
+ override fun composePage(page: JavaLayoutHtmlFormatOutputBuilder.Page, tagConsumer: TagConsumer<Appendable>, headContent: HEAD.() -> Unit, bodyContent: BODY.() -> Unit) {
+ tagConsumer.html {
+ attributes["devsite"] = "true"
+ head {
+ headContent()
+ title {+when(page) {
+ is JavaLayoutHtmlFormatOutputBuilder.Page.ClassIndex -> "Class Index | Android Developers"
+ is JavaLayoutHtmlFormatOutputBuilder.Page.ClassPage -> page.node.nameWithOuterClass()
+ is JavaLayoutHtmlFormatOutputBuilder.Page.PackageIndex -> "Package Index | Android Developers"
+ is JavaLayoutHtmlFormatOutputBuilder.Page.PackagePage -> page.node.nameWithOuterClass()
+ }}
+ unsafe {+"{% setvar book_path %}/reference/android/arch/_book.yaml{% endsetvar %}\n{% include \"_shared/_reference-head-tags.html\" %}\n"}
+ }
+ body {
+ bodyContent()
+ // TODO Refactor appendDataReferenceResourceWrapper to use KotlinX.HTML
+ unsafe { raw(buildString { appendDataReferenceResourceWrapper(when(page) {
+ is JavaLayoutHtmlFormatOutputBuilder.Page.ClassIndex -> page.classes
+ is JavaLayoutHtmlFormatOutputBuilder.Page.ClassPage -> listOf(page.node)
+ is JavaLayoutHtmlFormatOutputBuilder.Page.PackageIndex -> page.packages
+ is JavaLayoutHtmlFormatOutputBuilder.Page.PackagePage -> listOf(page.node)
+ }) }) }
+ }
+ }
+ }
+
+ /**
+ * Appends `data-reference-resources-wrapper` data to the body of the page. This is required
+ * for highlighting the current page in the left nav of DAC.
+ */
+ private fun Appendable.appendDataReferenceResourceWrapper(nodes: Iterable<DocumentationNode>) {
+ if (nodes.none()) {
+ return
+ }
+ val node = nodes.first()
+ if (node.isPackage()) {
+ val children = node.getMembersOfKinds(NodeKind.Class, NodeKind.Interface, NodeKind.Enum,
+ NodeKind.AnnotationClass, NodeKind.Exception, NodeKind.Object)
+ for (child in children) {
+ nodeToFamilyMap.put(child, children)
+ }
+ } else if (node.hasOwnPage() || node.kind in NodeKind.memberLike) {
+ val pageOwner = node.pageOwner()
+ val family = nodeToFamilyMap[pageOwner]?.groupBy { it.kind }
+ if (family != null) {
+ appendln("<div class=\"data-reference-resources-wrapper\">")
+ appendln(" <ul data-reference-resources>")
+ val interfaceFamily = family[NodeKind.Interface]
+ if (interfaceFamily != null) {
+ appendln(" <li><h2>Interfaces</h2>")
+ appendFamily(pageOwner, interfaceFamily)
+ }
+ val classFamily = family[NodeKind.Class]
+ if (classFamily != null) {
+ appendln(" <li><h2>Classes</h2>")
+ appendFamily(pageOwner, classFamily)
+ }
+ val enumFamily = family[NodeKind.Enum]
+ if (enumFamily != null) {
+ appendln(" <li><h2>Enums</h2>")
+ appendFamily(pageOwner, enumFamily)
+ }
+ val annotationFamily = family[NodeKind.AnnotationClass]
+ if (annotationFamily != null) {
+ appendln(" <li><h2>Annotations</h2>")
+ appendFamily(pageOwner, annotationFamily)
+ }
+ val exceptionFamily = family[NodeKind.Exception]
+ if (exceptionFamily != null) {
+ appendln(" <li><h2>Exceptions</h2>")
+ appendFamily(pageOwner, exceptionFamily)
+ }
+ val objectFamily = family[NodeKind.Object]
+ if (objectFamily != null) {
+ appendln(" <li><h2>Objects</h2>")
+ appendFamily(pageOwner, objectFamily)
+ }
+ appendln(" </ul>")
+ appendln("</div>")
+ }
+ }
+ }
+
+ /**
+ * Formats the `family` of the node for the `data-reference-resources-wrapper`.
+ * TODO: investigate expressing apilevel.
+ */
+ private fun Appendable.appendFamily(selectedNode: DocumentationNode, family: List<DocumentationNode>) {
+ appendln(" <ul>")
+ for (node in family) {
+ val selected = if (node == selectedNode) "selected " else ""
+ appendln(" <li class=\"${selected}api apilevel-\">" +
+ "<a href=\"/${uriProvider.mainUriOrWarn(node)}\">${node.nameWithOuterClass()}</a></li>")
+ }
+ appendln(" </ul>")
+ }
+}
+
+class DevsiteLayoutHtmlFormatOutputBuilderFactoryImpl @javax.inject.Inject constructor(
+ val uriProvider: JavaLayoutHtmlUriProvider,
+ val languageService: LanguageService,
+ val templateService: JavaLayoutHtmlTemplateService,
+ val logger: DokkaLogger
+) : JavaLayoutHtmlFormatOutputBuilderFactory {
+ override fun createOutputBuilder(output: Appendable, node: DocumentationNode): JavaLayoutHtmlFormatOutputBuilder {
+ return createOutputBuilder(output, uriProvider.mainUri(node))
+ }
+
+ override fun createOutputBuilder(output: Appendable, uri: URI): JavaLayoutHtmlFormatOutputBuilder {
+ return DevsiteLayoutHtmlFormatOutputBuilder(output, languageService, uriProvider, templateService, logger, uri)
+ }
+}
+
+class DevsiteLayoutHtmlFormatOutputBuilder(
+ output: Appendable,
+ languageService: LanguageService,
+ uriProvider: JavaLayoutHtmlUriProvider,
+ templateService: JavaLayoutHtmlTemplateService,
+ logger: DokkaLogger,
+ uri: URI
+) : JavaLayoutHtmlFormatOutputBuilder(output, languageService, uriProvider, templateService, logger, uri) {
+ override fun FlowContent.fullMemberDocs(node: DocumentationNode) {
+ div {
+ id = node.signatureForAnchor(logger)
+ h3(classes = "api-name") { +node.name }
+ pre(classes = "api-signature no-pretty-print") { renderedSignature(node, LanguageService.RenderMode.FULL) }
+ contentNodeToMarkup(node.content)
+ node.constantValue()?.let { value ->
+ pre {
+ +"Value: "
+ code { +value }
+ }
+ }
+ for ((name, sections) in node.content.sections.groupBy { it.tag }) {
+ table(classes = "responsive") {
+ thead { tr { td { h3 { +name } } } }
+ tbody {
+ sections.forEach {
+ tr {
+ td { it.subjectName?.let { +it } }
+ td {
+ metaMarkup(it.children)
+ }
+ }
+ }
+ }
+ }
+ }
+ }
+ }
+}
+
+class DacFormatDescriptor : JavaLayoutHtmlFormatDescriptorBase(), DefaultAnalysisComponentServices by KotlinAsKotlin {
+ override val templateServiceClass: KClass<out JavaLayoutHtmlTemplateService> = DevsiteHtmlTemplateService::class
+
+ override val outlineFactoryClass = DacOutlineFormatter::class
+ override val languageServiceClass = KotlinLanguageService::class
+ override val packageListServiceClass: KClass<out PackageListService> = JavaLayoutHtmlPackageListService::class
+ override val outputBuilderFactoryClass: KClass<out JavaLayoutHtmlFormatOutputBuilderFactory> = DevsiteLayoutHtmlFormatOutputBuilderFactoryImpl::class
+}
\ No newline at end of file
diff --git a/core/src/main/kotlin/Formats/DacOutlineService.kt b/core/src/main/kotlin/Formats/DacOutlineService.kt
new file mode 100644
index 0000000..2bf62ee
--- /dev/null
+++ b/core/src/main/kotlin/Formats/DacOutlineService.kt
@@ -0,0 +1,85 @@
+package org.jetbrains.dokka.Formats
+
+import com.google.inject.Inject
+import org.jetbrains.dokka.*
+import java.net.URI
+
+/**
+ * Outline service for generating a _toc.yaml file, responsible for pointing to the paths of each
+ * index.html file in the doc tree.
+ */
+class DacOutlineService(
+ val uriProvider: JavaLayoutHtmlUriProvider,
+ val languageService: LanguageService
+) : DacOutlineFormatService {
+ override fun computeOutlineURI(node: DocumentationNode): URI = uriProvider.containerUri(node).resolve("_toc.yaml")
+
+ override fun format(uri: URI, to: Appendable, node: DocumentationNode) {
+ appendOutline(uri, to, listOf(node))
+ }
+
+ var outlineLevel = 0
+
+ /** Appends formatted outline to [StringBuilder](to) using specified [location] */
+ fun appendOutline(uri: URI, to: Appendable, nodes: Iterable<DocumentationNode>) {
+ if (outlineLevel == 0) to.appendln("reference:")
+ for (node in nodes) {
+ appendOutlineHeader(uri, node, to)
+ val subPackages = node.members.filter {
+ it.kind == NodeKind.Package
+ }
+ if (subPackages.any()) {
+ val sortedMembers = subPackages.sortedBy { it.name }
+ appendOutlineLevel(to) {
+ appendOutline(uri, to, sortedMembers)
+ }
+ }
+
+ }
+ }
+
+ fun appendOutlineHeader(uri: URI, node: DocumentationNode, to: Appendable) {
+ if (node is DocumentationModule) {
+ to.appendln("- title: Package Index")
+ to.appendln(" path: ${uriProvider.mainUriOrWarn(node)}")
+ to.appendln(" status_text: no-toggle")
+ } else {
+ to.appendln("- title: ${languageService.renderName(node)}")
+ to.appendln(" path: ${uriProvider.mainUriOrWarn(node)}")
+ to.appendln(" status_text: apilevel-")
+ }
+ }
+
+ fun appendOutlineLevel(to: Appendable, body: () -> Unit) {
+ outlineLevel++
+ body()
+ outlineLevel--
+ }
+}
+
+
+interface DacOutlineFormatService {
+ fun computeOutlineURI(node: DocumentationNode): URI
+ fun format(uri: URI, to: Appendable, node: DocumentationNode)
+}
+
+class DacOutlineFormatter @Inject constructor(
+ uriProvider: JavaLayoutHtmlUriProvider,
+ languageService: LanguageService
+) : JavaLayoutHtmlFormatOutlineFactoryService {
+ val baseOutline = DacOutlineService(uriProvider, languageService)
+ val navOutline = DacNavOutlineService(uriProvider, languageService)
+ val searchOutline = DacSearchOutlineService(uriProvider, languageService)
+
+ val outlines = listOf(baseOutline, navOutline, searchOutline)
+
+ override fun generateOutlines(outputProvider: (URI) -> Appendable, nodes: Iterable<DocumentationNode>) {
+ for (node in nodes) {
+ for (outline in outlines) {
+ val uri = outline.computeOutlineURI(node)
+ val output = outputProvider(uri)
+ outline.format(uri, output, node)
+ }
+ }
+ }
+}
\ No newline at end of file
diff --git a/core/src/main/kotlin/Formats/ExtraOutlineServices.kt b/core/src/main/kotlin/Formats/ExtraOutlineServices.kt
new file mode 100644
index 0000000..e4eeac0
--- /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/JavaLayoutHtml/JavaLayoutHtmlFormatOutputBuilder.kt b/core/src/main/kotlin/Formats/JavaLayoutHtml/JavaLayoutHtmlFormatOutputBuilder.kt
index 0878f52..13ba9b1 100644
--- a/core/src/main/kotlin/Formats/JavaLayoutHtml/JavaLayoutHtmlFormatOutputBuilder.kt
+++ b/core/src/main/kotlin/Formats/JavaLayoutHtml/JavaLayoutHtmlFormatOutputBuilder.kt
@@ -42,7 +42,7 @@
protected open fun FlowContent.metaMarkup(content: ContentNode) = contentNodeToMarkup(content)
private fun FlowContent.contentNodesToMarkup(content: List<ContentNode>): Unit = content.forEach { contentNodeToMarkup(it) }
- private fun FlowContent.contentNodeToMarkup(content: ContentNode) {
+ protected fun FlowContent.contentNodeToMarkup(content: ContentNode) {
when (content) {
is ContentText -> +content.text
is ContentSymbol -> span("symbol") { +content.text }
diff --git a/core/src/main/resources/dokka/format/dac.properties b/core/src/main/resources/dokka/format/dac.properties
new file mode 100644
index 0000000..52b1909
--- /dev/null
+++ b/core/src/main/resources/dokka/format/dac.properties
@@ -0,0 +1,2 @@
+class=org.jetbrains.dokka.Formats.DacFormatDescriptor
+description=Generates developer.android.com website documentation
\ No newline at end of file
diff --git a/core/src/test/kotlin/format/JavaLayoutHtmlFormatTest.kt b/core/src/test/kotlin/format/JavaLayoutHtmlFormatTest.kt
index 36baa6a..a3cf0e3 100644
--- a/core/src/test/kotlin/format/JavaLayoutHtmlFormatTest.kt
+++ b/core/src/test/kotlin/format/JavaLayoutHtmlFormatTest.kt
@@ -14,10 +14,10 @@
verifyNode("simple.kt")
}
- @Test
- fun topLevel() {
- verifyPackageNode("topLevel.kt")
- }
+// @Test
+// fun topLevel() {
+// verifyPackageNode("topLevel.kt")
+// }
@Test
fun codeBlocks() {
diff --git a/core/src/test/kotlin/format/MarkdownFormatTest.kt b/core/src/test/kotlin/format/MarkdownFormatTest.kt
index f60969f..14405ab 100644
--- a/core/src/test/kotlin/format/MarkdownFormatTest.kt
+++ b/core/src/test/kotlin/format/MarkdownFormatTest.kt
@@ -206,10 +206,6 @@
}
}
- @Test fun jdkLinks() {
- verifyMarkdownNode("jdkLinks", withKotlinRuntime = true)
- }
-
@Test fun codeBlock() {
verifyMarkdownNode("codeBlock")
}
diff --git a/gradle.properties b/gradle.properties
index e046e1a..44e3f7e 100644
--- a/gradle.properties
+++ b/gradle.properties
@@ -1,4 +1,4 @@
-dokka_version=0.9.16
+dokka_version=0.9.17
dokka_publication_channel=dokka
#Kotlin compiler and plugin
