From 7a875ee7d20b67725debd4c2c9e1f93e1889c302 Mon Sep 17 00:00:00 2001 From: Ignat Beresnev Date: Fri, 29 Jul 2022 14:32:24 +0200 Subject: Add member icons to navigation menu (#2578) --- .../renderers/html/NavigationDataProvider.kt | 90 ++++++++++++++++++++++ .../main/kotlin/renderers/html/NavigationPage.kt | 63 +++++++++++++-- .../kotlin/renderers/html/htmlPreprocessors.kt | 67 +++++----------- .../images/nav-icons/abstract-class-kotlin.svg | 22 ++++++ .../dokka/images/nav-icons/abstract-class.svg | 20 +++++ .../dokka/images/nav-icons/annotation-kotlin.svg | 9 +++ .../dokka/images/nav-icons/annotation.svg | 7 ++ .../dokka/images/nav-icons/class-kotlin.svg | 9 +++ .../resources/dokka/images/nav-icons/class.svg | 7 ++ .../dokka/images/nav-icons/enum-kotlin.svg | 9 +++ .../main/resources/dokka/images/nav-icons/enum.svg | 7 ++ .../dokka/images/nav-icons/exception-class.svg | 7 ++ .../dokka/images/nav-icons/field-value.svg | 6 ++ .../dokka/images/nav-icons/field-variable.svg | 6 ++ .../resources/dokka/images/nav-icons/function.svg | 7 ++ .../dokka/images/nav-icons/interface-kotlin.svg | 9 +++ .../resources/dokka/images/nav-icons/interface.svg | 7 ++ .../resources/dokka/images/nav-icons/object.svg | 9 +++ .../resources/dokka/scripts/navigation-loader.js | 5 +- .../base/src/main/resources/dokka/styles/style.css | 82 ++++++++++++++++++-- 20 files changed, 388 insertions(+), 60 deletions(-) create mode 100644 plugins/base/src/main/kotlin/renderers/html/NavigationDataProvider.kt create mode 100644 plugins/base/src/main/resources/dokka/images/nav-icons/abstract-class-kotlin.svg create mode 100644 plugins/base/src/main/resources/dokka/images/nav-icons/abstract-class.svg create mode 100644 plugins/base/src/main/resources/dokka/images/nav-icons/annotation-kotlin.svg create mode 100644 plugins/base/src/main/resources/dokka/images/nav-icons/annotation.svg create mode 100644 plugins/base/src/main/resources/dokka/images/nav-icons/class-kotlin.svg create mode 100644 plugins/base/src/main/resources/dokka/images/nav-icons/class.svg create mode 100644 plugins/base/src/main/resources/dokka/images/nav-icons/enum-kotlin.svg create mode 100644 plugins/base/src/main/resources/dokka/images/nav-icons/enum.svg create mode 100644 plugins/base/src/main/resources/dokka/images/nav-icons/exception-class.svg create mode 100644 plugins/base/src/main/resources/dokka/images/nav-icons/field-value.svg create mode 100644 plugins/base/src/main/resources/dokka/images/nav-icons/field-variable.svg create mode 100644 plugins/base/src/main/resources/dokka/images/nav-icons/function.svg create mode 100644 plugins/base/src/main/resources/dokka/images/nav-icons/interface-kotlin.svg create mode 100644 plugins/base/src/main/resources/dokka/images/nav-icons/interface.svg create mode 100644 plugins/base/src/main/resources/dokka/images/nav-icons/object.svg (limited to 'plugins/base/src/main') diff --git a/plugins/base/src/main/kotlin/renderers/html/NavigationDataProvider.kt b/plugins/base/src/main/kotlin/renderers/html/NavigationDataProvider.kt new file mode 100644 index 00000000..647ba687 --- /dev/null +++ b/plugins/base/src/main/kotlin/renderers/html/NavigationDataProvider.kt @@ -0,0 +1,90 @@ +package org.jetbrains.dokka.base.renderers.html + +import org.jetbrains.dokka.base.renderers.sourceSets +import org.jetbrains.dokka.base.transformers.documentables.isException +import org.jetbrains.dokka.base.translators.documentables.DocumentableLanguage +import org.jetbrains.dokka.base.translators.documentables.documentableLanguage +import org.jetbrains.dokka.model.* +import org.jetbrains.dokka.pages.* + +abstract class NavigationDataProvider { + open fun navigableChildren(input: RootPageNode): NavigationNode = input.withDescendants() + .first { it is ModulePage || it is MultimoduleRootPage }.let { visit(it as ContentPage) } + + open fun visit(page: ContentPage): NavigationNode = + NavigationNode( + name = page.displayableName(), + dri = page.dri.first(), + sourceSets = page.sourceSets(), + icon = chooseNavigationIcon(page), + children = page.navigableChildren() + ) + + /** + * Parenthesis is applied in 1 case: + * - page only contains functions (therefore documentable from this page is [DFunction]) + */ + private fun ContentPage.displayableName(): String = + if (this is WithDocumentables && documentables.all { it is DFunction }) { + "$name()" + } else { + name + } + + private fun chooseNavigationIcon(contentPage: ContentPage): NavigationNodeIcon? { + return if (contentPage is WithDocumentables) { + val documentable = contentPage.documentables.firstOrNull() + val isJava = documentable?.hasAnyJavaSources() ?: false + + when (documentable) { + is DClass -> when { + documentable.isException -> NavigationNodeIcon.EXCEPTION + documentable.isAbstract() -> { + if (isJava) NavigationNodeIcon.ABSTRACT_CLASS else NavigationNodeIcon.ABSTRACT_CLASS_KT + } + else -> if (isJava) NavigationNodeIcon.CLASS else NavigationNodeIcon.CLASS_KT + } + is DFunction -> NavigationNodeIcon.FUNCTION + is DProperty -> { + val isVar = documentable.extra[IsVar] != null + if (isVar) NavigationNodeIcon.VAR else NavigationNodeIcon.VAL + } + is DInterface -> if (isJava) NavigationNodeIcon.INTERFACE else NavigationNodeIcon.INTERFACE_KT + is DEnum, + is DEnumEntry -> if (isJava) NavigationNodeIcon.ENUM_CLASS else NavigationNodeIcon.ENUM_CLASS_KT + is DAnnotation -> { + if (isJava) NavigationNodeIcon.ANNOTATION_CLASS else NavigationNodeIcon.ANNOTATION_CLASS_KT + } + is DObject -> NavigationNodeIcon.OBJECT + else -> null + } + } else { + null + } + } + + private fun Documentable.hasAnyJavaSources(): Boolean { + val withSources = this as? WithSources ?: return false + return this.sourceSets.any { withSources.documentableLanguage(it) == DocumentableLanguage.JAVA } + } + + private fun DClass.isAbstract(): Boolean { + return modifier.values.all { it is KotlinModifier.Abstract || it is JavaModifier.Abstract } + } + + private fun ContentPage.navigableChildren(): List { + return if (this !is ClasslikePageNode) { + children + .filterIsInstance() + .map { visit(it) } + .sortedBy { it.name.toLowerCase() } + } else if (documentables.any { it is DEnum }) { + // no sorting for enum entries, should be the same as in source code + children + .filter { child -> child is WithDocumentables && child.documentables.any { it is DEnumEntry } } + .map { visit(it as ContentPage) } + } else { + emptyList() + } + } +} diff --git a/plugins/base/src/main/kotlin/renderers/html/NavigationPage.kt b/plugins/base/src/main/kotlin/renderers/html/NavigationPage.kt index e0b20f01..e5183699 100644 --- a/plugins/base/src/main/kotlin/renderers/html/NavigationPage.kt +++ b/plugins/base/src/main/kotlin/renderers/html/NavigationPage.kt @@ -7,13 +7,15 @@ import org.jetbrains.dokka.base.templating.AddToNavigationCommand import org.jetbrains.dokka.links.DRI import org.jetbrains.dokka.model.DisplaySourceSet import org.jetbrains.dokka.model.WithChildren -import org.jetbrains.dokka.pages.PageNode -import org.jetbrains.dokka.pages.RendererSpecificPage -import org.jetbrains.dokka.pages.RenderingStrategy +import org.jetbrains.dokka.pages.* import org.jetbrains.dokka.plugability.DokkaContext -class NavigationPage(val root: NavigationNode, val moduleName: String, val context: DokkaContext) : - RendererSpecificPage { +class NavigationPage( + val root: NavigationNode, + val moduleName: String, + val context: DokkaContext +) : RendererSpecificPage { + override val name = "navigation" override val children = emptyList() @@ -46,22 +48,69 @@ class NavigationPage(val root: NavigationNode, val moduleName: String, val conte span("navButtonContent") } } - buildLink(node.dri, node.sourceSets.toList()) { buildBreakableText(node.name) } + buildLink(node.dri, node.sourceSets.toList()) { + // special condition for Enums as it has children enum entries in navigation + val withIcon = node.icon != null && (node.children.isEmpty() || node.isEnum()) + if (withIcon) { + // in case link text is so long that it needs to have word breaks, + // and it stretches to two or more lines, make sure the icon + // is always on the left in the grid and is not wrapped with text + span("nav-link-grid") { + span("nav-link-child ${node.icon?.style()}") + span("nav-link-child") { + buildBreakableText(node.name) + } + } + } else { + buildBreakableText(node.name) + } + } } node.children.withIndex().forEach { (n, p) -> visit(p, "$navId-$n", renderer) } } } + + private fun NavigationNode.isEnum(): Boolean { + return icon == NavigationNodeIcon.ENUM_CLASS || icon == NavigationNodeIcon.ENUM_CLASS_KT + } } data class NavigationNode( val name: String, val dri: DRI, val sourceSets: Set, + val icon: NavigationNodeIcon?, override val children: List ) : WithChildren +/** + * [CLASS] represents a neutral (a.k.a Java-style) icon, + * whereas [CLASS_KT] should be Kotlin-styled + */ +enum class NavigationNodeIcon( + private val cssClass: String +) { + CLASS("class"), + CLASS_KT("class-kt"), + ABSTRACT_CLASS("abstract-class"), + ABSTRACT_CLASS_KT("abstract-class-kt"), + ENUM_CLASS("enum-class"), + ENUM_CLASS_KT("enum-class-kt"), + ANNOTATION_CLASS("annotation-class"), + ANNOTATION_CLASS_KT("annotation-class-kt"), + INTERFACE("interface"), + INTERFACE_KT("interface-kt"), + FUNCTION("function"), + EXCEPTION("exception-class"), + OBJECT("object"), + VAL("val"), + VAR("var"); + + internal fun style(): String = "nav-icon $cssClass" +} + fun NavigationPage.transform(block: (NavigationNode) -> NavigationNode) = NavigationPage(root.transform(block), moduleName, context) fun NavigationNode.transform(block: (NavigationNode) -> NavigationNode) = - run(block).let { NavigationNode(it.name, it.dri, it.sourceSets, it.children.map(block)) } + run(block).let { NavigationNode(it.name, it.dri, it.sourceSets, it.icon, it.children.map(block)) } diff --git a/plugins/base/src/main/kotlin/renderers/html/htmlPreprocessors.kt b/plugins/base/src/main/kotlin/renderers/html/htmlPreprocessors.kt index 4527baa7..2de6f2b7 100644 --- a/plugins/base/src/main/kotlin/renderers/html/htmlPreprocessors.kt +++ b/plugins/base/src/main/kotlin/renderers/html/htmlPreprocessors.kt @@ -2,60 +2,16 @@ package org.jetbrains.dokka.base.renderers.html import org.jetbrains.dokka.base.DokkaBase import org.jetbrains.dokka.base.DokkaBaseConfiguration -import org.jetbrains.dokka.base.renderers.sourceSets import org.jetbrains.dokka.base.templating.AddToSourcesetDependencies import org.jetbrains.dokka.base.templating.toJsonString -import org.jetbrains.dokka.model.DEnum -import org.jetbrains.dokka.model.DEnumEntry -import org.jetbrains.dokka.model.DFunction -import org.jetbrains.dokka.model.withDescendants -import org.jetbrains.dokka.pages.* +import org.jetbrains.dokka.pages.RendererSpecificResourcePage +import org.jetbrains.dokka.pages.RenderingStrategy +import org.jetbrains.dokka.pages.RootPageNode import org.jetbrains.dokka.plugability.DokkaContext import org.jetbrains.dokka.plugability.configuration import org.jetbrains.dokka.transformers.pages.PageTransformer -abstract class NavigationDataProvider { - open fun navigableChildren(input: RootPageNode): NavigationNode = input.withDescendants() - .first { it is ModulePage || it is MultimoduleRootPage }.let { visit(it as ContentPage) } - - open fun visit(page: ContentPage): NavigationNode = - NavigationNode( - name = page.displayableName, - dri = page.dri.first(), - sourceSets = page.sourceSets(), - children = page.navigableChildren() - ) - - private fun ContentPage.navigableChildren(): List { - return if (this !is ClasslikePageNode) { - children - .filterIsInstance() - .map { visit(it) } - .sortedBy { it.name.toLowerCase() } - } else if (documentables.any { it is DEnum }) { - // no sorting for enum entries, should be the same as in source code - children - .filter { child -> child is WithDocumentables && child.documentables.any { it is DEnumEntry } } - .map { visit(it as ContentPage) } - } else { - emptyList() - } - } - - /** - * Parenthesis is applied in 1 case: - * - page only contains functions (therefore documentable from this page is [DFunction]) - */ - private val ContentPage.displayableName: String - get() = if (this is WithDocumentables && documentables.all { it is DFunction }) { - "$name()" - } else { - name - } -} - open class NavigationPageInstaller(val context: DokkaContext) : NavigationDataProvider(), PageTransformer { - override fun invoke(input: RootPageNode): RootPageNode = input.modified( children = input.children + NavigationPage( @@ -138,6 +94,23 @@ object AssetsInstaller : PageTransformer { "images/copy-icon.svg", "images/copy-successful-icon.svg", "images/theme-toggle.svg", + + // navigation icons + "images/nav-icons/abstract-class.svg", + "images/nav-icons/abstract-class-kotlin.svg", + "images/nav-icons/annotation.svg", + "images/nav-icons/annotation-kotlin.svg", + "images/nav-icons/class.svg", + "images/nav-icons/class-kotlin.svg", + "images/nav-icons/enum.svg", + "images/nav-icons/enum-kotlin.svg", + "images/nav-icons/exception-class.svg", + "images/nav-icons/field-value.svg", + "images/nav-icons/field-variable.svg", + "images/nav-icons/function.svg", + "images/nav-icons/interface.svg", + "images/nav-icons/interface-kotlin.svg", + "images/nav-icons/object.svg", ) override fun invoke(input: RootPageNode) = input.modified( diff --git a/plugins/base/src/main/resources/dokka/images/nav-icons/abstract-class-kotlin.svg b/plugins/base/src/main/resources/dokka/images/nav-icons/abstract-class-kotlin.svg new file mode 100644 index 00000000..a2069b8f --- /dev/null +++ b/plugins/base/src/main/resources/dokka/images/nav-icons/abstract-class-kotlin.svg @@ -0,0 +1,22 @@ + + + + + + + + + + + + + + + + + + + + + + diff --git a/plugins/base/src/main/resources/dokka/images/nav-icons/abstract-class.svg b/plugins/base/src/main/resources/dokka/images/nav-icons/abstract-class.svg new file mode 100644 index 00000000..60182030 --- /dev/null +++ b/plugins/base/src/main/resources/dokka/images/nav-icons/abstract-class.svg @@ -0,0 +1,20 @@ + + + + + + + + + + + + + + + + + + + + diff --git a/plugins/base/src/main/resources/dokka/images/nav-icons/annotation-kotlin.svg b/plugins/base/src/main/resources/dokka/images/nav-icons/annotation-kotlin.svg new file mode 100644 index 00000000..932f1d3d --- /dev/null +++ b/plugins/base/src/main/resources/dokka/images/nav-icons/annotation-kotlin.svg @@ -0,0 +1,9 @@ + + + + + + + + + diff --git a/plugins/base/src/main/resources/dokka/images/nav-icons/annotation.svg b/plugins/base/src/main/resources/dokka/images/nav-icons/annotation.svg new file mode 100644 index 00000000..b80c54b4 --- /dev/null +++ b/plugins/base/src/main/resources/dokka/images/nav-icons/annotation.svg @@ -0,0 +1,7 @@ + + + + + + + diff --git a/plugins/base/src/main/resources/dokka/images/nav-icons/class-kotlin.svg b/plugins/base/src/main/resources/dokka/images/nav-icons/class-kotlin.svg new file mode 100644 index 00000000..46a21f65 --- /dev/null +++ b/plugins/base/src/main/resources/dokka/images/nav-icons/class-kotlin.svg @@ -0,0 +1,9 @@ + + + + + + + + + diff --git a/plugins/base/src/main/resources/dokka/images/nav-icons/class.svg b/plugins/base/src/main/resources/dokka/images/nav-icons/class.svg new file mode 100644 index 00000000..3f1ad167 --- /dev/null +++ b/plugins/base/src/main/resources/dokka/images/nav-icons/class.svg @@ -0,0 +1,7 @@ + + + + + + + diff --git a/plugins/base/src/main/resources/dokka/images/nav-icons/enum-kotlin.svg b/plugins/base/src/main/resources/dokka/images/nav-icons/enum-kotlin.svg new file mode 100644 index 00000000..4a854596 --- /dev/null +++ b/plugins/base/src/main/resources/dokka/images/nav-icons/enum-kotlin.svg @@ -0,0 +1,9 @@ + + + + + + + + + diff --git a/plugins/base/src/main/resources/dokka/images/nav-icons/enum.svg b/plugins/base/src/main/resources/dokka/images/nav-icons/enum.svg new file mode 100644 index 00000000..fa7f2476 --- /dev/null +++ b/plugins/base/src/main/resources/dokka/images/nav-icons/enum.svg @@ -0,0 +1,7 @@ + + + + + + + diff --git a/plugins/base/src/main/resources/dokka/images/nav-icons/exception-class.svg b/plugins/base/src/main/resources/dokka/images/nav-icons/exception-class.svg new file mode 100644 index 00000000..c0b2bdeb --- /dev/null +++ b/plugins/base/src/main/resources/dokka/images/nav-icons/exception-class.svg @@ -0,0 +1,7 @@ + + + + + + + diff --git a/plugins/base/src/main/resources/dokka/images/nav-icons/field-value.svg b/plugins/base/src/main/resources/dokka/images/nav-icons/field-value.svg new file mode 100644 index 00000000..20449c94 --- /dev/null +++ b/plugins/base/src/main/resources/dokka/images/nav-icons/field-value.svg @@ -0,0 +1,6 @@ + + + + + + diff --git a/plugins/base/src/main/resources/dokka/images/nav-icons/field-variable.svg b/plugins/base/src/main/resources/dokka/images/nav-icons/field-variable.svg new file mode 100644 index 00000000..3b074500 --- /dev/null +++ b/plugins/base/src/main/resources/dokka/images/nav-icons/field-variable.svg @@ -0,0 +1,6 @@ + + + + + + diff --git a/plugins/base/src/main/resources/dokka/images/nav-icons/function.svg b/plugins/base/src/main/resources/dokka/images/nav-icons/function.svg new file mode 100644 index 00000000..f0da64a0 --- /dev/null +++ b/plugins/base/src/main/resources/dokka/images/nav-icons/function.svg @@ -0,0 +1,7 @@ + + + + + + + diff --git a/plugins/base/src/main/resources/dokka/images/nav-icons/interface-kotlin.svg b/plugins/base/src/main/resources/dokka/images/nav-icons/interface-kotlin.svg new file mode 100644 index 00000000..bf07a148 --- /dev/null +++ b/plugins/base/src/main/resources/dokka/images/nav-icons/interface-kotlin.svg @@ -0,0 +1,9 @@ + + + + + + + + + diff --git a/plugins/base/src/main/resources/dokka/images/nav-icons/interface.svg b/plugins/base/src/main/resources/dokka/images/nav-icons/interface.svg new file mode 100644 index 00000000..32063ba2 --- /dev/null +++ b/plugins/base/src/main/resources/dokka/images/nav-icons/interface.svg @@ -0,0 +1,7 @@ + + + + + + + diff --git a/plugins/base/src/main/resources/dokka/images/nav-icons/object.svg b/plugins/base/src/main/resources/dokka/images/nav-icons/object.svg new file mode 100644 index 00000000..9f427de4 --- /dev/null +++ b/plugins/base/src/main/resources/dokka/images/nav-icons/object.svg @@ -0,0 +1,9 @@ + + + + + + + + + diff --git a/plugins/base/src/main/resources/dokka/scripts/navigation-loader.js b/plugins/base/src/main/resources/dokka/scripts/navigation-loader.js index 9c824b91..92464911 100644 --- a/plugins/base/src/main/resources/dokka/scripts/navigation-loader.js +++ b/plugins/base/src/main/resources/dokka/scripts/navigation-loader.js @@ -59,7 +59,10 @@ scrollNavigationToSelectedElement = () => { return } - let isPackageElement = selectedElement.children.length > 1 + let hasIcon = selectedElement.querySelectorAll(":scope > div.overview span.nav-icon").length > 0 + + // for instance enums also have children and are expandable, but are not package/module elements + let isPackageElement = selectedElement.children.length > 1 && !hasIcon if (isPackageElement) { // if package is selected or linked, it makes sense to align it to top // so that you can see all the members it contains diff --git a/plugins/base/src/main/resources/dokka/styles/style.css b/plugins/base/src/main/resources/dokka/styles/style.css index e32ec063..6a9d2a87 100644 --- a/plugins/base/src/main/resources/dokka/styles/style.css +++ b/plugins/base/src/main/resources/dokka/styles/style.css @@ -271,13 +271,13 @@ p.paragraph:first-child, #main { width: 100%; - max-width: calc(100% - 280px); + max-width: calc(100% - 300px); display: flex; flex-direction: column; } #leftColumn { - width: 280px; + width: 300px; border-right: 1px solid var(--border-color); display: flex; flex-direction: column; @@ -448,7 +448,7 @@ code.paragraph { box-sizing: border-box; content: ''; top: 0; - width: 280px; + width: 300px; right: 0; bottom: 0; position: absolute; @@ -502,6 +502,78 @@ code.paragraph { display: none; } +.overview .nav-link-grid { + display: grid; + grid-template-columns: 16px auto; /* first is the icon, then name */ + grid-gap: 6px; + align-items: center; +} + +.nav-icon { + width: 16px; + height: 16px; +} + +.nav-icon.class::before { + content: url("../images/nav-icons/class.svg"); +} + +.nav-icon.class-kt::before { + content: url("../images/nav-icons/class-kotlin.svg"); +} + +.nav-icon.function::before { + content: url("../images/nav-icons/function.svg"); +} + +.nav-icon.enum-class::before { + content: url("../images/nav-icons/enum.svg"); +} + +.nav-icon.enum-class-kt::before { + content: url("../images/nav-icons/enum-kotlin.svg"); +} + +.nav-icon.annotation-class::before { + content: url("../images/nav-icons/annotation.svg"); +} + +.nav-icon.annotation-class-kt::before { + content: url("../images/nav-icons/annotation-kotlin.svg"); +} + +.nav-icon.abstract-class::before { + content: url("../images/nav-icons/abstract-class.svg"); +} + +.nav-icon.abstract-class-kt::before { + content: url("../images/nav-icons/abstract-class-kotlin.svg"); +} + +.nav-icon.exception-class::before { + content: url("../images/nav-icons/exception-class.svg"); +} + +.nav-icon.interface::before { + content: url("../images/nav-icons/interface.svg"); +} + +.nav-icon.interface-kt::before { + content: url("../images/nav-icons/interface-kotlin.svg"); +} + +.nav-icon.object::before { + content: url("../images/nav-icons/object.svg"); +} + +.nav-icon.val::before { + content: url("../images/nav-icons/field-value.svg"); +} + +.nav-icon.var::before { + content: url("../images/nav-icons/field-variable.svg"); +} + .filtered > a, .filtered > .navButton { display: none; } @@ -1118,7 +1190,7 @@ div.runnablesample { #leftColumn { position: fixed; - margin-left: -280px; + margin-left: -300px; transition: margin .2s ease-out; z-index: 4; background: white; @@ -1147,7 +1219,7 @@ div.runnablesample { } #leftColumn.open ~ #main #leftToggler { - margin-left: 280px; + margin-left: 300px; } .icon-toggler::before { -- cgit