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
159
160
161
162
163
164
165
166
|
## Changes between 0.10.x and 1.4-M3
There are two main changes between dokka 0.10.x and 1.4-M3
The first is the introduction of plugability - new documentation creating process is divided into several steps and each step provides extension points to be used. To learn more about new dokka pipeline and possible plugins, please read Developer's guide.
Second difference comes with the change with the subject of dokka pass. Previously, separate dokka passes where set for every targeted platform, now every source set has its own pass and the name itself changed to `sourceSet`.
### Gradle
With changing the approach from platform-based to source-set-based, we replace both `configuration` and `multiplatform` blocks with `dokkaSourceSets`. It's still a collection of dokka passes configuration, so the structure stays as it was.
Format selection is now done using plugins with dokka providing preconfigured tasks for different formats: `dokkaHtml`, `dokkaJavadoc`, `dokkaGfm` and `dokkaJekyll`.
* `moduleName` has changed to `moduleDisplayName`
* `targets` has been dropped. Declaration merging is now done by the source set mechanism. Name customization can be done using `displayName` property
* `outputFormat` has been dropped. Format can be selected with appropriate plugins, please refer to the README
#### Groovy
##### Old
```groovy
dokka {
outputFormat = 'html'
outputDirectory = "$buildDir/dokka"
multiplatform {
js {
includes = ["src/jsMain/resources/doc.md"]
samples = ["src/jsMain/resources/Samples.kt"]
sourceLink {
path = "src/jsMain/kotlin"
url = "https:/dokka.documentation.com/jsMain/kotlin"
lineSuffix = "#L"
}
}
jvm {
includes = ["src/jvmMain/resources/doc.md"]
samples = ["src/jsMain/resources/Samples.kt"]
sourceLink {
path = "src/jvmMain/kotlin"
url = "https:/dokka.documentation.com/jvmMain/kotlin"
lineSuffix = "#L"
}
}
}
}
```
##### New
```groovy
dokkaHtml { // or dokkaGfm, dokkaJekyll, ...
outputDirectory = "$buildDir/dokka"
dokkaSourceSets {
commonMain {}
jsMain {
includes = ["src/jsMain/resources/doc.md"]
samples = ["src/jsMain/resources/Samples.kt"]
sourceLink {
path = "src/jsMain/kotlin"
url = "https:/dokka.documentation.com/jsMain/kotlin"
lineSuffix = "#L"
}
}
jvmMain {
includes = ["src/jvmMain/resources/doc.md"]
samples = ["src/jsMain/resources/Samples.kt"]
sourceLink {
path = "src/jvmMain/kotlin"
url = "https:/dokka.documentation.com/jvmMain/kotlin"
lineSuffix = "#L"
}
}
}
}
```
#### Kotlin
##### Old
```kotlin
kotlin { // Kotlin Multiplatform plugin configuration
jvm()
js("customName")
}
val dokka by getting(DokkaTask::class) {
outputDirectory = "$buildDir/dokka"
outputFormat = "html"
multiplatform {
val customName by creating { // The same name as in Kotlin Multiplatform plugin, so the sources are fetched automatically
includes = listOf("packages.md", "extra.md")
samples = listOf("samples/basic.kt", "samples/advanced.kt")
}
register("differentName") { // Different name, so source roots must be passed explicitly
targets = listOf("JVM")
platform = "jvm"
sourceRoot {
path = kotlin.sourceSets.getByName("jvmMain").kotlin.srcDirs.first().toString()
}
sourceRoot {
path = kotlin.sourceSets.getByName("commonMain").kotlin.srcDirs.first().toString()
}
}
}
}
```
##### New
```kotlin
kotlin { // Kotlin Multiplatform plugin configuration
jvm()
js("customName")
}
dokkaHtml { // or dokkaGfm, dokkaJekyll, ...
outputDirectory = "$buildDir/dokka"
dokkaSourceSets {
val customNameMain by creating { // The same source set name as in Kotlin Multiplatform plugin, so the sources are fetched automatically
includes = listOf("packages.md", "extra.md")
samples = listOf("samples/basic.kt", "samples/advanced.kt")
}
val commonMain by creating {} // Document commonj source set
create("differentName") { // Different name, so source roots must be passed explicitly
sourceSetName = listOf("JVM")
platform = "jvm"
sourceRoot {
path = kotlin.sourceSets.getByName("jvmMain").kotlin.srcDirs.first().toString()
}
dependsOn(commonMain) // The jvm source set depends on the common source set
}
}
}
```
#### Multimodule page
There is a new task, `dokkaMultimodule`, that creates an index page for all documented subprojects. It is available only for top-level project.
```groovy
dokkaMultimodule {
// File to be used as an excerpt for each subprojects
documentationFileName = "README.md"
// output format for rendering multimodule page (accepts the same values as regular dokka task)
outputFormat = "html"
// output directory for page
outputDirectory = "$buildDir/dokka"
}
```
### Maven
There are no changes in maven configuration API for dokka, all previous configurations should work without issues.
The default platform label is "JVM", `sourceSetName` can be used to change it.
### Ant
Support for the Ant plugin has been dropped, dokka should be used with CLI in Ant instead.
### Command Line
Dokka fajtar has been dropped, thus the command line interface has changed slightly.
Most importantly, all plugins and their dependencies have to be provided in the `-pluginsClasspath` argument (paths are seperated with ';').
A build tool like Gradle or Maven is recommended to resolve and download all required artifacts.
Instead of creating a long configuration command, dokka can be configured with a JSON file. Please refer to the README.
|
