Migrate to dita-ot-gradle plugin v2.8.1 #660
Conversation
- Update dita-ot-gradle plugin from v2.3.2 to v2.8.1 to benefits major improvment - Enable Configuration Cache for faster incremental builds - Add new verification tasks: validateDita and checkLinks Co-authored-by: Jeremy Jeanne <jeremy.jeanne@4dconcept.fr> Signed-off-by: Jeremy Jeanne <jeremy.jeanne@4dconcept.fr>
There was a problem hiding this comment.
@jyjeanne 🙏 Thanks for submitting this. Interesting ideas here.
Makes sense to strip the comments from our earlier work on the build file.
Certainly much cleaner without them. 👍
I ran the docs build with these changes, and output was generated as expected, so it still works with these changes.
The additional progress indicators look useful:
Starting DITA-OT transformation
[==> ] 10% - Preprocessing
[====================> ] 70% - Transforming (45 files)
[=======================> ] 80% - Generating content (77 files)
The PDF transformation is much noisier now, as it logs all sorts of FOP warnings:
[WARN] The contents of fo:region-body on page 1 exceed its viewport by 48187 millipoints. (See position 1:1663)
[WARN] Property ID "unique_348" (found on "fo:wrapper") previously used; ID values must be unique within a document! Any reference to it will be considered a reference to the first occurrence in the document. (See position 12569:685)
[WARN] table-layout="fixed" and column-width unspecified => falling back to proportional-column-width(1) (See position 12605:5143)
[WARN] The following feature isn't implemented by Apache FOP, yet: table-layout="auto" (on fo:table) (See position 12966:2236)
While this level of detail is useful in debugging scenarios, I would expect it to be configurable, and not shown by default.
Note
See additional code comments in context below ↓
P.S. For future reference: it would be better to submit PRs from dedicated feature branches, rather than from the develop branch in your fork. This helps to isolate the proposed changes from any other changes that may land on the upstream develop branch in the meantime.)
|
|
||
| doLast { | ||
| // Move .chm files using modern Gradle file operations | ||
| def htmlhelpDir = file("${outputDir}/htmlhelp") | ||
| if (htmlhelpDir.exists()) { | ||
| copy { | ||
| from htmlhelpDir | ||
| into outputDir | ||
| include '*.chm' | ||
| } | ||
| // Clean up the htmlhelp directory | ||
| delete htmlhelpDir | ||
| } | ||
| } |
There was a problem hiding this comment.
@jyjeanne Was this intended to only delete the comment? 🤔
I don't see any related changes that would move the .chm file, so this deletion seems to remove existing functionality from the build.
(We may decide to remove the htmlhelp task entirely as this format is no longer widely used, but we'll treat that as a separate issue to avoid conflicts.)
| // Verification Tasks (v2.8.1 features) | ||
| // ============================================================================= | ||
|
|
||
| task validateDita(type: DitaOtValidateTask) { |
There was a problem hiding this comment.
Interesting that you've built this feature in to the latest version of your Gradle plug-in. 🤔
DITA-OT already provides a validate subcommand. When I run that on the docs userguide.ditamap it passes, but the validateDita task here fails, revealing these apparently contradictory settings:
Strict mode: false
Processing mode: strict
Among other things, it reports a series of DOTJ031I errors, but these shouldn't be treated as errors:
This informational message is intended to help you catch filter conditions that may have been specified improperly; if the value is correct, no action is needed.
Apart from those unexpected errors, why validate via the Gradle plug-in vs. the built-in validate subcommand?
| failOnError = true | ||
| } | ||
|
|
||
| task checkLinks(type: DitaLinkCheckTask) { |
There was a problem hiding this comment.
@jyjeanne Broken links between topics and maps would normally be reported by the dita command as well, but it seems the plug-in handles this differently, as it doesn't seem to understand peer links.
The API docs link on Line 21 is reported as broken, although it is explicitly defined as a peer link to indicate that it is not accessible at build time:
<topicref href="api/index.html" format="html" scope="peer">═══════════════════════════════════════════════════════
Link Check Results
═══════════════════════════════════════════════════════
Files scanned: 290
Total links found: 2348
───────────────────────────────────────────────────────
Internal links: 490
✓ Valid: 489
✗ Broken: 1
───────────────────────────────────────────────────────
External links: 379
○ Skipped: 379
───────────────────────────────────────────────────────
Broken Links:
✗ userguide.ditamap -> api/index.html
Reason: File not found: /…/docs/api/index.html
2 participants
@infotexture ## Key Changes
dita-ot-gradleplugin from v2.3.2 to v2.8.1 to benefits new improvmentsvalidateDitaandcheckLinksMotivation and Context
Gradle 9.0 removes several deprecated APIs and makes Configuration Cache the recommended execution mode.
This PR ensures the documentation build works with Gradle 8.x, 9.x, and future versions, while enabling up to 77% faster incremental builds via Configuration Cache.
How Has This Been Tested?
./gradlew help --warning-mode all./gradlew --configuration-cache./gradlew dist -PditaHome=..../gradlew cleanOutput distFull Build Tested with DITA-OT 4.3.5
Type of Changes
Documentation and Compatibility
Documentation Changes
Backwards Compatibility
New Features
validateDita./gradlew validateDitacheckLinks./gradlew checkLinksverify./gradlew verifyChecklist
--warning-mode all