Alternative to testMavenRepo for examples

[EdricChan03]

Currently, the examples expect a testMavenRepo property to be defined, which is automatically generated by the updateDokkatooExamplesGradleProperties task in a gradle.properties file. However, this file doesn't appear to be generated when adding the examples as includedBuilds and running the Tests workflow - see this build step's logs:

Error resolving plugin [id: 'org.jetbrains.kotlin.jvm', version: '1.8.10']
> Cannot query the value of this provider because it has no value available.

Additionally, some examples might want to add custom properties of their own, or the plugins/code used (for e.g. Kotlin Multiplatform) expects a property (in this case, kotlin.mpp.androidSourceSetLayoutVersion=2/kotlin.mpp.androidSourceSetLayoutVersion1.nowarn=true to be set) to use a specific feature.

I'm not sure as to a better approach of doing this - maybe it could be defined as a custom property in a custom .properties file, which can then be loaded in via java.util.Properties, or maybe as an environment variable?

[aSemy]

Thanks for raising this.

Currently the gradle.properties file will only be automatically generated for projects defined in examples/build.gradle.kts, which at the moment is only Dokka example projects.

dokkatoo/examples/build.gradle.kts

Lines 6 to 20 in 98a1c0b

	tasks.setupDokkaTemplateProjects {
	destinationToSources.set(
	mapOf(
	//@formatter:off
	"custom-format-example/dokka" to listOf("examples/gradle/dokka-customFormat-example"),
	"gradle-example/dokka" to listOf("examples/gradle/dokka-gradle-example"),
	"kotlin-as-java-example/dokka" to listOf("examples/gradle/dokka-kotlinAsJava-example"),
	"library-publishing-example/dokka" to listOf("examples/gradle/dokka-library-publishing-example"),
	"multimodule-example/dokka" to listOf("examples/gradle/dokka-multimodule-example"),
	"multiplatform-example/dokka" to listOf("examples/gradle/dokka-multiplatform-example"),
	"versioning-multimodule-example/dokka" to listOf("examples/gradle/dokka-versioning-multimodule-example"),
	//@formatter:on
	).mapKeys { (dest, _) -> projectDir.resolve(dest) }
	)
	}

If you want to generate the gradle.properties for a new project, one that's not from the Dokka examples, then you can try and copy, pate, and adapt the current task.

dokkatoo/buildSrc/src/main/kotlin/buildsrc/conventions/dokkatoo-example-projects.gradle.kts

Lines 40 to 77 in 98a1c0b

	val updateDokkatooExamplesGradleProperties by tasks.registering {
	group = TASK_GROUP
	mustRunAfter(tasks.withType<SetupDokkaProjects>())
	val gradlePropertiesFiles =
	layout.projectDirectory.asFileTree
	.matching {
	include(
	"**/*dokkatoo*/settings.gradle.kts",
	"**/*dokkatoo*/settings.gradle",
	)
	}.elements.map { settingsFiles ->
	settingsFiles.map {
	it.asFile.resolveSibling("gradle.properties")
	}
	}
	outputs.files(gradlePropertiesFiles)
	val testMavenRepoPath = mavenPublishTestExtension.testMavenRepo.map {
	it.asFile.invariantSeparatorsPath
	}
	inputs.property("testMavenRepoPath", testMavenRepoPath)
	doLast task@{
	gradlePropertiesFiles.get().forEach {
	it.writeText(
	"""
	|# DO NOT EDIT - Generated by ${this@task.path}
	|
	|testMavenRepo=${testMavenRepoPath.get()}
	|
	""".trimMargin()
	)
	}
	}
	}

If custom properties are needed then they can be hardcoded into the task for now. So long as you get something working, then it can be made prettier later!

I had a lot of trouble trying to set up composite builds with Gradle, it's just too buggy gradle/gradle#23939, so Dokkatoo doesn't use it.

[aSemy]

Additionally, some examples might want to add custom properties of their own, or the plugins/code used (for e.g. Kotlin Multiplatform) expects a property (in this case, kotlin.mpp.androidSourceSetLayoutVersion=2/kotlin.mpp.androidSourceSetLayoutVersion1.nowarn=true to be set) to use a specific feature.

I've cooked up a nice DSL for amending the gradle.properties of Dokkatoo test projects :)

dokkatoo/modules/dokkatoo-plugin-integration-tests/build.gradle.kts

Lines 161 to 171 in 3cd790c

	dokkatooExampleProjects {
	gradleProperties {
	projectsItAndroid0Dokkatoo {
	content.set(
	"""
	android.useAndroidX=true
	""".trimIndent()
	)
	}
	}
	}

It's in a branch at the moment, and will be available when #76 is merged.