Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Simplify multi-module documentation #1387

Merged
merged 19 commits into from
Aug 31, 2020
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
19 commits
Select commit Hold shift + click to select a range
da22ee1
Implement ParseModuleAndPackageDocFragments API
sellmair Aug 21, 2020
208149d
Implement ModuleAndPackageDocumentationReader
sellmair Aug 25, 2020
afecd47
Implement ModuleAndPackageDocumentationTransformerTest.kt
sellmair Aug 26, 2020
a3f398c
Make testApi dokkaConfiguration available outside of AbstractCoreTest
sellmair Aug 26, 2020
63147f3
Implement tests for ModuleAndPackageDocumentationReader
sellmair Aug 26, 2020
c2a0167
Let `DRI.packageName` always be a real package name for root packages…
sellmair Aug 26, 2020
e140fb3
WIP
sellmair Aug 26, 2020
a650caa
Implement `root package is matched by empty string and the root keywo…
sellmair Aug 26, 2020
4fca6b4
Remove DRI.canonicalPackageName
sellmair Aug 26, 2020
1c73c5e
Let root package be represented as [root] to the user
sellmair Aug 26, 2020
01a36d3
Let module name be configurable withing `AbstractDokkaTask` and remov…
sellmair Aug 27, 2020
b459f8f
Re-use includes form child tasks for all modules page generation
sellmair Aug 28, 2020
0b93cfa
Minor readability improvement in ModuleAndPackageDocumentationTransfo…
sellmair Aug 28, 2020
7e86b02
Remove unnecessary trailing comma in defaultConfiguration.kt
sellmair Aug 28, 2020
bbf9bc1
Remove unnecessary blank lines
sellmair Aug 28, 2020
50962e9
Improve style of ModuleAndPackageDocumentationSource
sellmair Aug 28, 2020
3538bf6
CompositeSourceSetID: drop reduce in favour of `joinToString`
sellmair Aug 28, 2020
064b22b
Implement dPackage and dModule test APIs in favour of default params …
sellmair Aug 28, 2020
c2dd962
Remove old `defaultSourceSet` in favour of new package
sellmair Aug 31, 2020
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 1 addition & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -141,7 +141,6 @@ dokkaHtml {
cacheRoot.set(file("default"))
dokkaSourceSets {
configureEach { // Or source set name, for single-platform the default source sets are `main` and `test`
moduleDisplayName.set("data")

// Used when configuring source sets manually for declaring which source sets this one depends on
dependsOn("otherSourceSetName")
Expand Down Expand Up @@ -407,7 +406,7 @@ The available configuration options are shown below:
<skip>false</skip>

<!-- Default: ${project.artifactId} -->
<moduleDisplayName>data</moduleDisplayName>
<moduleName>data</moduleName>

<!-- Default: ${project.basedir}/target/dokka -->
<outputDir>some/out/dir</outputDir>
Expand Down Expand Up @@ -556,7 +555,6 @@ Dokka supports the following command line arguments:
* `-globalSrcLink` - source links added to all source sets
* `-sourceSet` - (repeatable) - configuration for a single source set. Following this argument, you can pass other arguments:
* `-moduleName` - (required) - module name used as a part of source set ID when declaring dependent source sets
* `-moduleDisplayName` - displayed module name
* `-sourceSetName` - source set name as a part of source set ID when declaring dependent source sets
* `-displayName` - source set name displayed in the generated documentation
* `-src` - list of source files or directories separated by `;`
Expand Down
2 changes: 1 addition & 1 deletion core/src/main/kotlin/DokkaException.kt
Original file line number Diff line number Diff line change
@@ -1,3 +1,3 @@
package org.jetbrains.dokka

class DokkaException(message: String) : RuntimeException(message)
open class DokkaException(message: String) : RuntimeException(message)
20 changes: 15 additions & 5 deletions core/src/main/kotlin/configuration.kt
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,7 @@ import java.io.Serializable
import java.net.URL

object DokkaDefaults {
val moduleName: String = "root"
val outputDir = File("./dokka")
const val format: String = "html"
val cacheRoot: File? = null
Expand Down Expand Up @@ -58,12 +59,21 @@ interface DokkaConfigurationBuilder<T : Any> {

fun <T : Any> Iterable<DokkaConfigurationBuilder<T>>.build(): List<T> = this.map { it.build() }


data class DokkaSourceSetID(
val moduleName: String,
/**
* Unique identifier of the scope that this source set is placed in.
* Each scope provide only unique source set names.
*
* E.g. One DokkaTask inside the Gradle plugin represents one source set scope, since there cannot be multiple
* source sets with the same name. However, a Gradle project will not be a proper scope, since there can be
* multple DokkaTasks that contain source sets with the same name (but different configuration)
*/
val scopeId: String,
val sourceSetName: String
) : Serializable {
override fun toString(): String {
return "$moduleName/$sourceSetName"
return "$scopeId/$sourceSetName"
}
}

Expand All @@ -72,6 +82,7 @@ fun DokkaConfigurationImpl(json: String): DokkaConfigurationImpl = parseJson(jso
fun DokkaConfiguration.toJsonString(): String = toJsonString(this)

interface DokkaConfiguration : Serializable {
val moduleName: String
val outputDir: File
val cacheRoot: File?
val offlineMode: Boolean
Expand All @@ -84,7 +95,6 @@ interface DokkaConfiguration : Serializable {
interface DokkaSourceSet : Serializable {
val sourceSetID: DokkaSourceSetID
val displayName: String
val moduleDisplayName: String
val classpath: List<File>
val sourceRoots: Set<File>
val dependentSourceSets: Set<DokkaSourceSetID>
Expand Down Expand Up @@ -114,8 +124,8 @@ interface DokkaConfiguration : Serializable {

interface DokkaModuleDescription : Serializable {
val name: String
val path: File
val docFile: File
val relativePathToOutputDirectory: File
val includes: Set<File>
}

interface PackageOptions : Serializable {
Expand Down
6 changes: 3 additions & 3 deletions core/src/main/kotlin/defaultConfiguration.kt
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,7 @@ import java.io.File
import java.net.URL

data class DokkaConfigurationImpl(
override val moduleName: String = DokkaDefaults.moduleName,
override val outputDir: File = DokkaDefaults.outputDir,
override val cacheRoot: File? = DokkaDefaults.cacheRoot,
override val offlineMode: Boolean = DokkaDefaults.offlineMode,
Expand All @@ -17,7 +18,6 @@ data class DokkaConfigurationImpl(


data class DokkaSourceSetImpl(
override val moduleDisplayName: String,
override val displayName: String = DokkaDefaults.sourceSetDisplayName,
override val sourceSetID: DokkaSourceSetID,
override val classpath: List<File> = emptyList(),
Expand All @@ -43,8 +43,8 @@ data class DokkaSourceSetImpl(

data class DokkaModuleDescriptionImpl(
override val name: String,
override val path: File,
override val docFile: File
override val relativePathToOutputDirectory: File,
override val includes: Set<File>
) : DokkaConfiguration.DokkaModuleDescription

data class SourceLinkDefinitionImpl(
Expand Down
2 changes: 0 additions & 2 deletions core/src/main/kotlin/links/DRI.kt
Original file line number Diff line number Diff line change
@@ -1,7 +1,5 @@
package org.jetbrains.dokka.links

import org.jetbrains.dokka.model.ClassKind

/**
* [DRI] stands for DokkaResourceIdentifier
*/
Expand Down
4 changes: 2 additions & 2 deletions core/src/main/kotlin/model/CompositeSourceSetID.kt
Original file line number Diff line number Diff line change
Expand Up @@ -14,8 +14,8 @@ data class CompositeSourceSetID(
}

val merged = DokkaSourceSetID(
moduleName = children.map { it.moduleName }.reduce { acc, s -> "$acc+$s" },
sourceSetName = children.map { it.sourceSetName }.reduce { acc, s -> "$acc+$s" }
scopeId = children.joinToString(separator = "+") { it.scopeId },
sourceSetName = children.joinToString(separator = "+") { it.sourceSetName }
)

val all: Set<DokkaSourceSetID> = setOf(merged, *children.toTypedArray())
Expand Down
15 changes: 12 additions & 3 deletions core/src/main/kotlin/model/Documentable.kt
Original file line number Diff line number Diff line change
Expand Up @@ -111,9 +111,18 @@ data class DPackage(
override val sourceSets: Set<DokkaSourceSet>,
override val extra: PropertyContainer<DPackage> = PropertyContainer.empty()
) : Documentable(), WithScope, WithExtraProperties<DPackage> {
override val name = dri.packageName.orEmpty()
override val children: List<Documentable>
get() = (properties + functions + classlikes + typealiases)

val packageName: String = dri.packageName.orEmpty()

/**
* !!! WARNING !!!
* This name is not guaranteed to be a be a canonical/real package name.
* e.g. this will return a human readable version for root packages.
* Use [packageName] or `dri.packageName` instead to obtain the real packageName
*/
override val name: String = if (packageName.isBlank()) "[root]" else packageName

override val children: List<Documentable> = properties + functions + classlikes + typealiases

override fun withNewExtras(newExtras: PropertyContainer<DPackage>) = copy(extra = newExtras)
}
Expand Down
Loading