dokka should provide gradle-idiomatic way to aggregate documentation

[triplem]

In gradle 6.8.x (and most probably before this already) gradle provides an "idiomatic" way to define aggregrations of reports without task-dependencies. This is mainly done using configurations, for an example see https://docs.gradle.org/release-nightly/samples/sample_structuring_software_projects.html.

Expected Behavior

The dokka Task should support this idiomatic way and should (best case) provide some detailed documentation on how to apply this pattern to an existing project.

Current Behavior

The current plugin implementation does not provide a nice and simple way to implement a report-aggregation, without any task-dependencies without a rootProject-build. The plugin does apply this already, but only to the root-project, so there is no real way to construct a project using the idiomatic structure.

[kamildoleglo]

@triplem can you point me to the specific part of the documentation and/or the example you linked that explains this "idiomatic way"? I can't find any example of report-aggregation there

[vlsi]

I wonder if this issue has been resolved with Dokka 1.4+, see #157 (comment)

[vlsi]

It turns out that Dokka uses is cross-project configuration which is a no-no:

dokka/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/AbstractDokkaParentTask.kt

Lines 15 to 17 in f2adc0a

	internal val childDokkaTasks: Set<AbstractDokkaTask>
	get() = childDokkaTaskPaths
	.mapNotNull { path -> project.tasks.findByPath(path) }

The suggested approach is as follows:

1. Every "child" project declares its outputs. For instance, it can share that "ok, I can expose dokka partial result if anyone asks"
2. Then, "aggregator" project declares dependencies, and basically consumes the outputs.

That avoids cross-project access, and it abstracts the dependencies.

---

The sample project should have something like "coverage aggregation".
Here's a sample:
a) "Declare a dependency" (==specify what we want to aggregate): https://github.com/jjohannes/idiomatic-gradle/blob/d8677b0242e360a1c5a0a349ada55efb078995ec/aggregation/package-server/build.gradle.kts#L7
b) "aggregation itself": https://github.com/jjohannes/idiomatic-gradle/blob/d8677b0242e360a1c5a0a349ada55efb078995ec/build-logic/packaging/src/main/kotlin/com.example.jacoco-aggregation.gradle.kts The notable part is that it uses packaging configuration to resolve both coverage data and source directories items
c) "exposing coverage data": https://github.com/jjohannes/idiomatic-gradle/blob/c7e5fb096eeed56e37fdd50ed0809af4d6e17b6d/build-logic/java-convention/src/main/kotlin/com.example.jacoco.gradle.kts#L23-L25

---

I used the same pattern in https://github.com/allure-framework/allure-gradle#aggregating-results-from-multiple-projects, and I think it is nice.

As a side-note, I split allure-gradle into several plugins, see https://github.com/allure-framework/allure-gradle#technical-details
That does help to separate concerns, and it allows the users to customize or override the behavior.

[rnett]

There's some aggregation stuff that looks like it's targeted for 7.4 as an incubator, see this sample and this one from the nightly docs.

[eskatos]

I second this feature request. This would make it possible to use dokka in existing projects. Without it dokka forces users to restructure their build. For some projects this is a no-go.

[aSemy]

Hi all 👋 I've been working on Dokkatoo, which is a completely new Gradle Plugin for running Dokka, and it's compatible with the Gradle API and correctly supports aggregation across subprojects.

I'm working with the Dokka team, and we plan to merge Dokkatoo into the Dokka core project eventually. Until then, Dokkatoo is available now on the Gradle Plugin Portal. There are still some TODOs and rough edges, so I'd appreciate feedback and help!