Use Gradle to download & cache package lists

[aSemy]

Proposal

Adjust Dokkatoo so that it downloads any package list files using Gradle based mechanisms (e.g. TextResource).

Benefits

• Improve runtime speed by removing a remote network call during Dokka Generator
• Improve reproducibility (less dynamic behaviour during runtime)
• Consolidate network proxy mechanisms, so proxy settings only have to be set for Gradle configurations

Detail

It's possible to pass a package list URL to Dokka Generator, which will then download the file ad-hoc using java.net.URL.

https://github.com/Kotlin/dokka/blob/d680b14ee033da5b7edf2406c35a93583a8f8eed/plugins/base/src/main/kotlin/resolvers/shared/PackageList.kt#L26-L34

Instead of passing a network address, a file address can be passed instead.

/**
* Specifies the exact location of a `package-list` instead of relying on Dokka
* automatically resolving it. Can also be a locally cached file to avoid network calls.
*
* Example:
*
* ```kotlin
* rootProject.projectDir.resolve("serialization.package.list").toURL()
* ```
*/
@Optional
@Input
val packageListUrl: Property<URL> = project.objects.property()

Related

• Support downloading package list behind a proxy Kotlin/dokka#3026

[aSemy]

This would be easier if TextResourceFactory was injectable, but unfortunately it's not gradle/gradle#16134. I don't want to implement a custom workaround, which would be complicated, hard to test, and increase maintenance.

[aSemy]

I can try and use an Ant task instead https://stackoverflow.com/a/69823963/4161471