-
Notifications
You must be signed in to change notification settings - Fork 409
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
how to generate documentation for a multi module gradle build #157
Comments
First approach requires a lot of work with linking, so the second one is preferred. task dokka (type: org.jetbrains.dokka.gradle.DokkaTask, overwrite: true) {
moduleName = "$rootProject.name"
outputDirectory = "$buildDir/ddoc"
outputFormat = "html"
processConfigurations = []
sourceDirs = files(subprojects.collect {
p ->
def path = new File(p.projectDir, "/src/main/kotlin")
def relativePath = rootDir.toPath().relativize(path.toPath()).toString()
linkMapping {
dir = path
url = "https://....../blob/master/$relativePath"
suffix = "#L"
}
return path
})
} |
Oh sorry, was not precise enough about the cross-reference. The link mappings are fine and refer to the correct repository sources, but the documentation shows a lot of Thought that I have to configure the Would it be possible to use a different string format to refer to a subproject and the corresponding configuration, which gets evaluated at runtime? e.g. |
Since each of my modules use Dokka for Javadoc generation, but I also wanted an interlinked Markdown version (for GitHub pages), I made a separate module that depended on all other modules (probably not necessary for just Dokka but I use it for other things as well): dependencies {
// Kotlin
compile project.kotlinStdLib
// Modules
compile project(':module1')
compile project(':module2')
compile project(':moduleN')
...
}
apply plugin: 'org.jetbrains.dokka-android'
dokka {
includes = ['Module.md']
moduleName = 'dokka'
outputFormat = 'gfm'
outputDirectory = 'docs'
}
project.afterEvaluate {
def mainDokkaTask = project.getTasksByName('dokka', false).first()
rootProject.getTasksByName('dokka', true).forEach { libDokkaTask ->
mainDokkaTask.sourceDirs = libDokkaTask.project.isAndroid ?
libDokkaTask.project.android.sourceSets.main.java.srcDirs :
libDokkaTask.project.sourceSets.main.allSource
libDokkaTask.dependsOn 'assemble'
mainDokkaTask.linkMapping {
dir = "$rootDir/${libDokkaTask.project.name}/src/main/java"
url = "https://github.com/user/project/tree/master/${libDokkaTask.project.name}/src/main/java"
suffix = "#L"
}
if (libDokkaTask != mainDokkaTask) {
mainDokkaTask.dependsOn libDokkaTask
}
}
mainDokkaTask.dependsOn clearDokkaTask
mainDokkaTask.dokkaFatJar project.dokkaFatJar
} Having said all that, it would be nice if this was more officially supported so we could have proper bread crumbs that went from "Project > Module > Normal > Dokka > Path" etc. |
Thank you for the example. I followed your suggestion and added the subprojects as module dependency to a custom configuration named
Had to set the repositories closure on the parent project for the dependency resolution, but all Maybe you can add some options to the plugin to simplify this process. Thanks everyone! |
* adds a dependency configuration for all sub-modules to create a classpath for dokka NOTE * see Kotlin/dokka#157
* adds a dependency configuration for all sub-modules to create a classpath for dokka * uses javadoc format for artifacts NOTE * see Kotlin/dokka#157
To have cross module references, you can also specify:
+1 for native support! |
I believe I have succeeded in creating a roll-up documentation with a mixture of what is described by @alex2069 and @semoro. That being, I have created a standalone module for the purposes of documentation that is purely for depending on all other subprojects and bringing in their source directories. It was my original goal to do this without a unique documentation module, and I could get most of this working in the root project build.gradle. However, any Android types were showing up as Does anyone know what's needed to get this to work in the root project or is it best to do as a submodule if I need to reference Android? Here's the block I was using in my root project build.gradle:
|
Here is a complete 'gradle-native' solution that worked for me based on @sdeleuze answer (fixed a little to define In modules that require documentation to be generated (just to mark them relevantly): apply plugin: 'org.jetbrains.dokka' In top-most /**
* Finds sub-projects that need dokka generation
* Place `apply plugin: 'org.jetbrains.dokka'` there
* @return A set of projects that have dokka task
*/
Set<Project> findDokkaProjects() {
subprojects.findAll {
!it.tasks.findAll { "dokka" == it.getName() }.isEmpty()
}
}
task dokka (type: org.jetbrains.dokka.gradle.DokkaTask, overwrite: true) {
outputDirectory = docDir
outputFormat = "gfm"
dependsOn {
findDokkaProjects().collect {
it.tasks.getByName("dokka")
}
}
doFirst {
def dokkaProjects = findDokkaProjects()
classpath = dokkaProjects.collect { project -> project.jar.outputs.files.getFiles() }.flatten()
classpath += files(dokkaProjects.collect { project -> project.sourceSets.main.compileClasspath })
sourceDirs = files(dokkaProjects.collect { project -> "${project.projectDir}/src/main/kotlin" })
}
} |
Hi there, I've made a basic example of a multiproject generation. I think it might help you 🙂 Kotlin/kotlin-examples#103 |
To build off of @fwpascual, this is what I am using in an Android SDK that contains multiple modules:
apply plugin: 'com.android.library'
apply plugin: 'kotlin-android'
android {
compileSdkVersion 28
defaultConfig {
minSdkVersion 21
targetSdkVersion 28
versionCode 1
versionName "1.0"
}
sourceSets {
main.java.srcDirs += '../moduleA/src/main/java'
main.java.srcDirs += '../moduleB/src/main/java'
}
}
apply from: rootProject.file('dokka.gradle')
apply plugin: 'org.jetbrains.dokka-android'
/**
* See https://github.com/Kotlin/dokka
*/
dokka {
moduleName = "$rootProject.name"
outputFormat = 'html'
outputDirectory = "$buildDir/javadoc"
// Do not output deprecated members
skipDeprecated = true
// Emit warnings about not documented members.
reportUndocumented = true
// Do not create index pages for empty packages
skipEmptyPackages = true
}
|
Could not set unknown property 'moduleName' for task ':dokka' of type org.jetbrains.dokka.gradle.DokkaTask. |
@Armaxis |
I'm closing this issue as it was a discussion for old dokka. New dokka (starting from 1.4.0-rc) is a complete rewrite and I encourage you to switch to it. It comes with multimodule tasks predefined:
|
Came across this since the multimodule example doesn't add |
@rescribet JFYI it does so in settings.gradle.kts pluginManagement {
plugins {
kotlin("jvm") version "1.6.10"
id("org.jetbrains.dokka") version ("1.6.10")
}
} Perhaps this needs to be pointed out |
@IgnatBeresnev Ah, thanks. I'm don't have a JVM background, so I did not figure to check that file. |
Hello,
just wanted to ask if you know a working configuration that either
Tried something for the latter and came up with:
which works if the
processConfigurations
property is empty, but wont show any cross-reference in the generated html files then.Any idea how to configure the classpath of related subprojects?
Thank you very much!
The text was updated successfully, but these errors were encountered: