update: DGPV2 migration guide #4025
Conversation
AlejandraPedroza
force-pushed
the
DGPV2-update-migration-guide
branch
from
f4b0526 to
fb10fbd
Compare
AlejandraPedroza
changed the title
docs/topics/dokka-migration.md
Outdated
| ``` | ||
| ```kotlin | ||
| plugins { | ||
| kotlin("jvm") version "1.9.25" |
There was a problem hiding this comment.
Maybe we could use here the latest stable Kotlin version (2.1.10)?
docs/topics/dokka-migration.md
Outdated
|
|
||
| ```kotlin | ||
| dokka { | ||
| this: DokkaExtension |
There was a problem hiding this comment.
It looks like something is broken in the snippet. The old one was:
tasks.dokkaHtml {
dokkaSourceSets {
configureEach {
externalDocumentationLink {
url = URL("https://example.com/docs/")
packageListUrl = File("/path/to/package-list").toURI().toURL()
}
}
}
}
docs/topics/dokka-migration.md
Outdated
| // build.gradle.kts | ||
|
|
||
| plugins { | ||
| id("org.jetbrains.dokka") version "2.0.0-Beta" |
There was a problem hiding this comment.
We could drop Beta from version
| } | ||
| ``` | ||
|
|
||
| ### Configure custom Dokka plugins |
There was a problem hiding this comment.
Why do we promote the feature in the migration guide? I expect the minimal required amount of material to move projects from DGP v1 to DGP v2.
There was a problem hiding this comment.
This is part of the feedback we got to update the migration guide. You can see in the feedback issue the comment addressed by @adam-enko as pointed here.
There was a problem hiding this comment.
May be it makes more sense to only add a link to an example configuration which will be introduced in #3871 (and so possibly copy part of the text there to readme) instead of this big section here, as we don’t really want to promote using custom Dokka plugins :)
docs/topics/dokka-migration.md
Outdated
| @OptIn(DokkaInternalApi::class) | ||
| abstract class DokkaScriptsPluginParameters @Inject constructor( | ||
| name: String | ||
| ) : DokkaPluginParametersBaseSpec(name, "ca.solostudios.dokkascript.plugin.DokkaScriptsPlugin") { |
There was a problem hiding this comment.
Who is ca.solostudios? I think we should avoid mentioning external namespaces.
docs/topics/dokka-migration.md
Outdated
| includes.from("README.md") | ||
| sourceLink { | ||
| localDirectory.set(file("src/main/kotlin")) | ||
| remoteUrl("https://github.com/your-repo") |
There was a problem hiding this comment.
For consistency (set in all properties), maybe we could use remoteUrl.set(URI("https://github.com/your-repo")).
| dokka { | ||
| dokkaPublications.html { | ||
| outputDirectory.set(layout.buildDirectory.dir("dokkaDir")) | ||
| The ability to set an output directory and include additional files, such as `README.md`, is still supported in |
There was a problem hiding this comment.
I believe that the initial concern of user for this feedback (https://youtrack.jetbrains.com/issue/KT-72053/Dokka-DGP-v2-migration-guide-feedback#focus=Comments-27-10821114.0-0) was that previously Dokka configuration was split between dokkaHtml task and dokkaHtmlMultiModule task but with DGPv2 we do have single place (dokka extension) to configure both type of projects.
So I think that may be it would make sense to rephrase this to point to this moment instead of still supported wording.
|
|
||
| New configuration: | ||
|
|
||
| DGP v2 replaces the JSON-based configuration with a type-safe DSL that is compatible with incremental builds. |
There was a problem hiding this comment.
minor: we could additionally place a link to a versioning example here—https://github.com/Kotlin/dokka/tree/master/examples/gradle-v2/versioning-multimodule-example
| } | ||
| ``` | ||
|
|
||
| ### Configure custom Dokka plugins |
There was a problem hiding this comment.
May be it makes more sense to only add a link to an example configuration which will be introduced in #3871 (and so possibly copy part of the text there to readme) instead of this big section here, as we don’t really want to promote using custom Dokka plugins :)
This PR contains updates for the DGP V2 Migration guide.
The additions to the Migration guide are:
externalDocumentationLinkshas changed API and it's missing in migration guideOutputdirectory for additional filessourceLinkAdditionally, there are some fixes in the code format and indentation. Plus, the content within "Adjust configuration options" is now broken into single subsections instead of bullet points.
KT-72053 [Dokka] DGP v2 migration guide feedback