From 280dc29f14d0aa66f4c799d15d478a6d9920841e Mon Sep 17 00:00:00 2001 From: Ilya Ryzhenkov Date: Tue, 14 Oct 2014 16:08:10 +0400 Subject: Use module.md to get package descriptors, filter sections with names of members, fix markdown for kotlin website, propagate content from parent to child with the name of section. --- src/Formats/KotlinWebsiteFormatService.kt | 4 ---- src/Formats/MarkdownFormatService.kt | 4 +++- src/Formats/StructuredFormatService.kt | 14 ++++++++------ src/Formats/TextFormatService.kt | 4 ++-- src/Generation/ConsoleGenerator.kt | 2 +- src/Kotlin/DocumentationBuilder.kt | 2 +- src/Locations/LocationService.kt | 2 +- src/Model/Content.kt | 4 +++- src/Model/DocumentationModule.kt | 2 +- src/Model/DocumentationNode.kt | 12 +++++++++++- src/main.kt | 28 ++++++++++++++++++++++------ 11 files changed, 53 insertions(+), 25 deletions(-) (limited to 'src') diff --git a/src/Formats/KotlinWebsiteFormatService.kt b/src/Formats/KotlinWebsiteFormatService.kt index 9fee14ff..ea54c97a 100644 --- a/src/Formats/KotlinWebsiteFormatService.kt +++ b/src/Formats/KotlinWebsiteFormatService.kt @@ -27,10 +27,6 @@ public class KotlinWebsiteFormatService(locationService: LocationService, return "${text}" } - override fun appendText(to: StringBuilder, text: String) { - to.appendln("

${text}

") - } - override fun appendTable(to: StringBuilder, body: () -> Unit) { to.appendln("") body() diff --git a/src/Formats/MarkdownFormatService.kt b/src/Formats/MarkdownFormatService.kt index 54298e2a..8f9699c2 100644 --- a/src/Formats/MarkdownFormatService.kt +++ b/src/Formats/MarkdownFormatService.kt @@ -55,7 +55,9 @@ public open class MarkdownFormatService(locationService: LocationService, } override public fun appendText(to: StringBuilder, text: String) { - to.append(text) + to.appendln() + to.appendln(text) + to.appendln() } override public fun appendHeader(to: StringBuilder, text: String, level: Int) { diff --git a/src/Formats/StructuredFormatService.kt b/src/Formats/StructuredFormatService.kt index 5287e688..280aa6b5 100644 --- a/src/Formats/StructuredFormatService.kt +++ b/src/Formats/StructuredFormatService.kt @@ -73,7 +73,7 @@ public abstract class StructuredFormatService(val locationService: LocationServi } fun appendDescription(location: Location, to: StringBuilder, nodes: Iterable) { - val described = nodes.filter { !it.doc.isEmpty } + val described = nodes.filter { !it.content.isEmpty } if (described.any()) { val single = described.size == 1 appendHeader(to, "Description", 3) @@ -81,11 +81,13 @@ public abstract class StructuredFormatService(val locationService: LocationServi if (!single) { appendBlockCode(to, formatText(location, languageService.render(node))) } - appendLine(to, formatText(location,node.doc.description)) + appendLine(to, formatText(location,node.content.description)) appendLine(to) - for ((label, section) in node.doc.sections) { + for ((label, section) in node.content.sections) { if (label.startsWith("$")) continue + if (node.members.any { it.name == label }) + continue appendLine(to, formatStrong(formatText(label))) appendLine(to, formatText(location, section)) } @@ -95,14 +97,14 @@ public abstract class StructuredFormatService(val locationService: LocationServi fun appendSummary(location: Location, to: StringBuilder, nodes: Iterable) { val breakdownBySummary = nodes.groupByTo(LinkedHashMap()) { node -> - node.doc.summary + formatText(location, node.summary) } for ((summary, items) in breakdownBySummary) { items.forEach { appendBlockCode(to, formatText(location, languageService.render(it))) } - appendLine(to, formatText(location, summary)) + appendLine(to, summary) appendLine(to) } } @@ -131,7 +133,7 @@ public abstract class StructuredFormatService(val locationService: LocationServi appendText(to, formatLink(memberLocation)) } appendTableCell(to) { - val breakdownBySummary = members.groupBy { formatText(location, it.doc.summary) } + val breakdownBySummary = members.groupBy { formatText(location, it.summary) } for ((summary, items) in breakdownBySummary) { for (signature in items) { appendBlockCode(to, formatText(location, languageService.render(signature))) diff --git a/src/Formats/TextFormatService.kt b/src/Formats/TextFormatService.kt index 63d2ce42..4e43cbcc 100644 --- a/src/Formats/TextFormatService.kt +++ b/src/Formats/TextFormatService.kt @@ -7,9 +7,9 @@ public class TextFormatService(val signatureGenerator: LanguageService) : Format with (to) { appendln(signatureGenerator.render(node)) appendln() - appendln(node.doc.summary) + appendln(node.content.summary) - for ((label, section) in node.doc.sections) { + for ((label, section) in node.content.sections) { appendln(label) } } diff --git a/src/Generation/ConsoleGenerator.kt b/src/Generation/ConsoleGenerator.kt index 78164bb9..f52c6f4b 100644 --- a/src/Generation/ConsoleGenerator.kt +++ b/src/Generation/ConsoleGenerator.kt @@ -13,7 +13,7 @@ public class ConsoleGenerator(val signatureGenerator: LanguageService, val locat public fun generateHeader(node: DocumentationNode, indent: String = "") { println(indent + signatureGenerator.render(node)) - val docString = node.doc.toString() + val docString = node.content.toString() if (!docString.isEmpty()) println("$indent\"${docString.replace("\n", "\n$indent")}\"") println() diff --git a/src/Kotlin/DocumentationBuilder.kt b/src/Kotlin/DocumentationBuilder.kt index cee374d9..f91c922c 100644 --- a/src/Kotlin/DocumentationBuilder.kt +++ b/src/Kotlin/DocumentationBuilder.kt @@ -284,7 +284,7 @@ class DocumentationBuilder(val session: ResolveSession, val options: Documentati } } - resolveContentLinks(node, node.doc) + resolveContentLinks(node, node.content) for (child in node.members) { resolveReferences(child) diff --git a/src/Locations/LocationService.kt b/src/Locations/LocationService.kt index f89fedd0..3c3ed3e1 100644 --- a/src/Locations/LocationService.kt +++ b/src/Locations/LocationService.kt @@ -12,7 +12,7 @@ public trait LocationService { } -public fun escapeUri(path: String): String = path.replace('<', '_').replace('>', '_') +public fun escapeUri(path: String): String = path.replace('<', '-').replace('>', '-') fun LocationService.relativeLocation(owner: DocumentationNode, node: DocumentationNode, extension: String): Location { return relativeLocation(location(owner), node, extension) diff --git a/src/Model/Content.kt b/src/Model/Content.kt index 3ec3d341..794faf50 100644 --- a/src/Model/Content.kt +++ b/src/Model/Content.kt @@ -84,7 +84,9 @@ public class Content() : ContentNode() { map } - public val summary: ContentNode get() = sections["\$summary"] ?: ContentNode.empty + public val summary: ContentNode get() { + return sections["\$summary"] ?: ContentNode.empty + } public val description: ContentNode get() = sections["\$description"] ?: ContentNode.empty override fun equals(other: Any?): Boolean { diff --git a/src/Model/DocumentationModule.kt b/src/Model/DocumentationModule.kt index 6084ea5e..e74c544b 100644 --- a/src/Model/DocumentationModule.kt +++ b/src/Model/DocumentationModule.kt @@ -1,6 +1,6 @@ package org.jetbrains.dokka -public class DocumentationModule(name: String) : DocumentationNode(name, Content.Empty, DocumentationNode.Kind.Module) { +public class DocumentationModule(name: String, content: Content = Content.Empty) : DocumentationNode(name, content, DocumentationNode.Kind.Module) { fun merge(other: DocumentationModule): DocumentationModule { val model = DocumentationModule(name) model.addAllReferencesFrom(other) diff --git a/src/Model/DocumentationNode.kt b/src/Model/DocumentationNode.kt index 18efaa9b..2be5bf15 100644 --- a/src/Model/DocumentationNode.kt +++ b/src/Model/DocumentationNode.kt @@ -3,11 +3,21 @@ package org.jetbrains.dokka import java.util.LinkedHashSet public open class DocumentationNode(val name: String, - val doc: Content, + val content: Content, val kind: DocumentationNode.Kind) { private val references = LinkedHashSet() + public val summary: ContentNode get() { + val contentSection = content.sections["\$summary"] + if (contentSection != null) + return contentSection + val ownerSection = owner?.content?.sections?.get(name) + if (ownerSection != null) + return ownerSection + return ContentNode.empty + } + public val owner: DocumentationNode? get() = references(DocumentationReference.Kind.Owner).singleOrNull()?.to public val details: List diff --git a/src/main.kt b/src/main.kt index 287664a3..6f5cf796 100644 --- a/src/main.kt +++ b/src/main.kt @@ -7,12 +7,18 @@ import org.jetbrains.jet.cli.common.arguments.* import org.jetbrains.jet.utils.PathUtil import java.io.File import org.jetbrains.jet.lang.descriptors.DeclarationDescriptor +import org.jetbrains.jet.lang.resolve.name.FqName +import java.lang.reflect.Constructor class DokkaArguments { Argument(value = "src", description = "Source file or directory (allows many paths separated by the system path separator)") ValueDescription("") public var src: String = "" + Argument(value = "include", description = "Markdown files to load (allows many paths separated by the system path separator)") + ValueDescription("") + public var include: String = "" + Argument(value = "samples", description = "Source root for samples") ValueDescription("") public var samples: String = "" @@ -32,11 +38,11 @@ class DokkaArguments { } public fun main(args: Array) { - val arguments = DokkaArguments() val freeArgs: List = Args.parse(arguments, args) ?: listOf() val sources = if (arguments.src.isNotEmpty()) arguments.src.split(File.pathSeparatorChar).toList() + freeArgs else freeArgs val samples = if (arguments.samples.isNotEmpty()) arguments.samples.split(File.pathSeparatorChar).toList() else listOf() + val includes = if (arguments.include.isNotEmpty()) arguments.include.split(File.pathSeparatorChar).toList() else listOf() val environment = AnalysisEnvironment(MessageCollectorPlainTextToStream.PLAIN_TEXT_TO_SYSTEM_ERR) { addClasspath(PathUtil.getJdkClassesRoots()) @@ -59,6 +65,7 @@ public fun main(args: Array) { println("Analysing sources and libraries... ") val startAnalyse = System.currentTimeMillis() + val documentation = environment.withContext { environment, session -> val fragmentFiles = environment.getSourceFiles().filter { val sourceFile = File(it.getVirtualFile()!!.getPath()) @@ -69,11 +76,21 @@ public fun main(args: Array) { } } val fragments = fragmentFiles.map { session.getPackageFragment(it.getPackageFqName()) }.filterNotNull().distinct() - val documentationModule = DocumentationModule(arguments.moduleName) val options = DocumentationOptions() val documentationBuilder = DocumentationBuilder(session, options) with(documentationBuilder) { + + val moduleContent = Content() + for (include in includes) { + val text = File(include).readText() + val tree = MarkdownProcessor.parse(text) + val content = buildContent(tree, session.getPackageFragment(FqName.ROOT)) + moduleContent.children.addAll(content.children) + } + + val documentationModule = DocumentationModule(arguments.moduleName, moduleContent) + val descriptors = hashMapOf>() for ((name, parts) in fragments.groupBy { it.fqName }) { descriptors.put(name.asString(), parts.flatMap { it.getMemberScope().getAllDescriptors() }) @@ -84,10 +101,9 @@ public fun main(args: Array) { packageNode.appendChildren(declarations, DocumentationReference.Kind.Member) documentationModule.append(packageNode, DocumentationReference.Kind.Member) } + documentationBuilder.resolveReferences(documentationModule) + documentationModule } - - documentationBuilder.resolveReferences(documentationModule) - documentationModule } val timeAnalyse = System.currentTimeMillis() - startAnalyse @@ -98,7 +114,7 @@ public fun main(args: Array) { val locationService = FoldersLocationService(arguments.outputDir) val templateService = HtmlTemplateService.default("/dokka/styles/style.css") - //val formatter = HtmlFormatService(locationService, signatureGenerator, templateService) +// val formatter = HtmlFormatService(locationService, signatureGenerator, templateService) val formatter = KotlinWebsiteFormatService(locationService, signatureGenerator) val generator = FileGenerator(signatureGenerator, locationService, formatter) print("Generating pages... ") -- cgit