1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
|
package org.jetbrains.dokka
import com.sampullara.cli.*
import com.intellij.openapi.util.*
import org.jetbrains.kotlin.cli.common.messages.*
import org.jetbrains.kotlin.cli.common.arguments.*
import org.jetbrains.kotlin.utils.PathUtil
import java.io.File
import org.jetbrains.kotlin.name.FqName
class DokkaArguments {
Argument(value = "src", description = "Source file or directory (allows many paths separated by the system path separator)")
ValueDescription("<path>")
public var src: String = ""
Argument(value = "srcLink", description = "Mapping between a source directory and a Web site for browsing the code")
ValueDescription("<path>=<url>[#lineSuffix]")
public var srcLink: String = ""
Argument(value = "include", description = "Markdown files to load (allows many paths separated by the system path separator)")
ValueDescription("<path>")
public var include: String = ""
Argument(value = "samples", description = "Source root for samples")
ValueDescription("<path>")
public var samples: String = ""
Argument(value = "output", description = "Output directory path")
ValueDescription("<path>")
public var outputDir: String = "out/doc/"
Argument(value = "format", description = "Output format (text, html, markdown, jekyll, kotlin-website)")
ValueDescription("<name>")
public var outputFormat: String = "html"
Argument(value = "module", description = "Name of the documentation module")
ValueDescription("<name>")
public var moduleName: String = ""
Argument(value = "classpath", description = "Classpath for symbol resolution")
ValueDescription("<path>")
public var classpath: String = ""
}
class SourceLinkDefinition(val path: String, val url: String, val lineSuffix: String?)
private fun parseSourceLinkDefinition(srcLink: String): SourceLinkDefinition {
val (path, urlAndLine) = srcLink.split('=')
return SourceLinkDefinition(File(path).getAbsolutePath(),
urlAndLine.substringBefore("#"),
urlAndLine.substringAfter("#", "").let { if (it.isEmpty()) null else "#" + it })
}
public fun main(args: Array<String>) {
val arguments = DokkaArguments()
val freeArgs: List<String> = 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 sourceLinks = if (arguments.srcLink.isNotEmpty() && arguments.srcLink.contains("="))
listOf(parseSourceLinkDefinition(arguments.srcLink))
else {
if (arguments.srcLink.isNotEmpty()) {
println("Warning: Invalid -srcLink syntax. Expected: <path>=<url>[#lineSuffix]. No source links will be generated.")
}
listOf()
}
val environment = AnalysisEnvironment(MessageCollectorPlainTextToStream.PLAIN_TEXT_TO_SYSTEM_ERR) {
addClasspath(PathUtil.getJdkClassesRoots())
// addClasspath(PathUtil.getKotlinPathsForCompiler().getRuntimePath())
for (element in arguments.classpath.split(File.pathSeparatorChar)) {
addClasspath(File(element))
}
addSources(sources)
addSources(samples)
}
println("Module: ${arguments.moduleName}")
println("Output: ${arguments.outputDir}")
println("Sources: ${environment.sources.join()}")
println("Classpath: ${environment.classpath.joinToString()}")
println()
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())
samples.none { sample ->
val canonicalSample = File(sample).canonicalPath
val canonicalSource = sourceFile.canonicalPath
canonicalSource.startsWith(canonicalSample)
}
}
val fragments = fragmentFiles.map { session.getPackageFragment(it.getPackageFqName()) }.filterNotNull().distinct()
val options = DocumentationOptions(false, sourceLinks)
val documentationBuilder = DocumentationBuilder(session, options)
with(documentationBuilder) {
val moduleContent = Content()
for (include in includes) {
val file = File(include)
if (file.exists()) {
val text = file.readText()
val tree = parseMarkdown(text)
val content = buildContent(tree, session.getPackageFragment(FqName.ROOT))
moduleContent.children.addAll(content.children)
} else {
println("WARN: Include file $file was not found.")
}
}
val documentationModule = DocumentationModule(arguments.moduleName, moduleContent)
documentationModule.appendFragments(fragments)
documentationBuilder.resolveReferences(documentationModule)
documentationModule
}
}
val timeAnalyse = System.currentTimeMillis() - startAnalyse
println("done in ${timeAnalyse / 1000} secs")
val startBuild = System.currentTimeMillis()
val signatureGenerator = KotlinLanguageService()
val locationService = FoldersLocationService(arguments.outputDir)
val templateService = HtmlTemplateService.default("/dokka/styles/style.css")
val formatter = when (arguments.outputFormat) {
"text" -> TextFormatService(signatureGenerator)
"html" -> HtmlFormatService(locationService, signatureGenerator, templateService)
"markdown" -> MarkdownFormatService(locationService, signatureGenerator)
"jekyll" -> JekyllFormatService(locationService, signatureGenerator)
"kotlin-website" -> KotlinWebsiteFormatService(locationService, signatureGenerator)
else -> {
print("Unrecognized output format ${arguments.outputFormat}")
return
}
}
val generator = FileGenerator(signatureGenerator, locationService, formatter)
print("Generating pages... ")
generator.buildPage(documentation)
generator.buildOutline(documentation)
val timeBuild = System.currentTimeMillis() - startBuild
println("done in ${timeBuild / 1000} secs")
println()
println("Done.")
Disposer.dispose(environment)
}
|
