update: DGPV2 migration guide #4025
Conversation
AlejandraPedroza
force-pushed
the
DGPV2-update-migration-guide
branch
from
f4b0526 to
fb10fbd
Compare
AlejandraPedroza
changed the title
AlejandraPedroza
force-pushed
the
DGPV2-update-migration-guide
branch
from
ed43b97 to
dd02f2e
Compare
AlejandraPedroza
force-pushed
the
DGPV2-update-migration-guide
branch
from
09d4e21 to
7a96118
Compare
adam-enko
added
the
documentation
docs/topics/dokka-migration.md
Outdated
|
|
||
| 2. In the project's `gradle.properties` file, set the following opt-in flag with helpers to activate the new plugin version: | ||
| > By default, DGP v2 generates HTML documentation. To generate Javadoc or both HTML and Javadoc formats, |
There was a problem hiding this comment.
Hmm 🤔
What do you think of this version?
I assume HTML plugin is already included if that's the default version:
By default, DGP v2 generates documentation in HTML format.
To generate Javadoc or both HTML and Javadoc, add the Javadoc plugin.
There was a problem hiding this comment.
I applied your suggestion in the first part of the sentence. However, I kept it as "appropriate plugins" because the HTML and the Javadoc are different ones.
docs/topics/dokka-migration.md
Outdated
| ``` | ||
| ### Enable migration helpers | ||
|
|
||
| In the project's `gradle.properties` file, set the following opt-in flag to activate the new plugin version with helpers: |
There was a problem hiding this comment.
I don't think we use flag in our docs (this might be an exception?) - would Gradle property work here?
docs/topics/dokka-migration.md
Outdated
| > | ||
| {style="tip"} | ||
|
|
||
| This flag activates the DGP v2 plugin with migration helpers, which prevent compilation errors when build scripts reference |
There was a problem hiding this comment.
| This flag activates the DGP v2 plugin with migration helpers, which prevent compilation errors when build scripts reference | |
| This property activates the DGP v2 plugin with migration helpers, which prevent compilation errors when build scripts reference |
There was a problem hiding this comment.
(Suggestion)
Could we break this into two sentences?
This property activates the DGP v2 plugin with migration helpers.
These helpers prevent compilation errors when build scripts reference tasks from...
| When DGP aggregates modules, each subproject has its own subdirectory within the aggregated docs. | ||
|
|
||
| In DGP v2, the aggregation mechanism has been updated to better align with Gradle conventions. | ||
| DGP v2 now preserves the full subproject directory to prevent conflicts when aggregating |
There was a problem hiding this comment.
| DGP v2 now preserves the full subproject directory to prevent conflicts when aggregating | |
| It preserves the full subproject directory to prevent conflicts when aggregating |
There was a problem hiding this comment.
As the last noun mentioned is "Gradle conventions" and "mechanism" is before that, I'll leave DGP v2 instead of "it" for better clarity.
docs/topics/dokka-migration.md
Outdated
|
|
||
| In DGP v1, aggregated documentation was placed in a collapsed directory structure. | ||
| For example, given a project with an aggregation in `:turbo-lib` and a nested subproject `:turbo-lib:maths`, | ||
| the generated documentation would be placed under: |
There was a problem hiding this comment.
| the generated documentation would be placed under: | |
| the generated documentation was placed under: |
docs/topics/dokka-migration.md
Outdated
| turbo-lib/build/dokka/html/maths/ | ||
| ``` | ||
|
|
||
| New aggregation directory: |
There was a problem hiding this comment.
like before and for all mentions - I think it would be more future-proof to say :
DGP v1 aggregation directory:
DGP v2 aggregation directory:
instead of old and new
docs/topics/dokka-migration.md
Outdated
| turbo-lib/build/dokka/html/turbo-lib/maths/ | ||
| ``` | ||
|
|
||
| This change prevents subprojects with the same name from clashing. However, because the directory has changed, external links |
There was a problem hiding this comment.
| This change prevents subprojects with the same name from clashing. However, because the directory has changed, external links | |
| This change prevents subprojects with the same name from clashing. However, since the directory structure has changed, external links |
docs/topics/dokka-migration.md
Outdated
| ``` | ||
|
|
||
| This change prevents subprojects with the same name from clashing. However, because the directory has changed, external links | ||
| may become outdated and cause `404` errors. |
There was a problem hiding this comment.
| may become outdated and cause `404` errors. | |
| may become outdated, potentially causing `404` errors. |
Co-authored-by: Oleg Yukhnevich <[email protected]>
Co-authored-by: Oleg Yukhnevich <[email protected]>
AlejandraPedroza
force-pushed
the
DGPV2-update-migration-guide
branch
from
ff57df6 to
fc203ca
Compare
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