Build unified Javadoc for all Java subprojects

My project contains about two dozen subprojects. Most of those subprojects use the java-libraries plugin to produce a main jar (from the main source set), along with corresponding HTML-rendered Javadoc. Some subprojects also use the java-test-fixtures plugin to produce a test-fixtures jar (from the testFixtures source set), again with corresponding HTML-rendered Javadoc.

We would like to augment the per-jar documentation with HTML-rendered Javadoc that includes all Java sources from all jar archives built in all subprojects.

My current approach adds the following code to our top-level build.gradle:

tasks.register('aggregatedJavadocs', Javadoc) { aggregated ->
	destinationDir = file("$buildDir/docs/javadoc")

	subprojects.each { proj ->
		proj.tasks.withType(Javadoc) { javadocTask ->
			aggregated.source += javadocTask.source
			aggregated.classpath += javadocTask.classpath
			aggregated.excludes += javadocTask.excludes
			aggregated.includes += javadocTask.includes

Although the aggregated Javadoc looks reasonable, numerous warnings like the following suggest that this is not a good strategy:

Resolution of the configuration :[...]:compileClasspath was attempted from a context different than the project context. Have a look at the documentation to understand why this is a problem and how it can be resolved. This behaviour has been deprecated and is scheduled to be removed in Gradle 8.0. See for more details.

What’s the right way to do this?