From 9bf00a6ca589f842d46719b0ce6784e0d81b081d Mon Sep 17 00:00:00 2001 From: Jeremy Jeanne Date: Fri, 23 Jan 2026 16:25:34 +0100 Subject: [PATCH 1/3] Key changes: - 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 Signed-off-by: Jeremy Jeanne --- build.gradle | 78 ++++++++++++++++++++++++++--------------------- gradle.properties | 7 ++--- 2 files changed, 46 insertions(+), 39 deletions(-) diff --git a/build.gradle b/build.gradle index 729ad205..de4be04c 100644 --- a/build.gradle +++ b/build.gradle @@ -8,7 +8,7 @@ buildscript { } plugins { - id 'io.github.jyjeanne.dita-ot-gradle' version '2.3.2' + id 'io.github.jyjeanne.dita-ot-gradle' version '2.8.1' // Removed: 'com.github.eerohele.saxon-gradle' - not Configuration Cache compatible // Replaced with: inline XsltTransformTask class below } @@ -96,6 +96,8 @@ abstract class XsltTransformTask extends DefaultTask { } import com.github.jyjeanne.DitaOtTask +import com.github.jyjeanne.DitaOtValidateTask +import com.github.jyjeanne.DitaLinkCheckTask def getPropertyOrDefault(String name, def defaultValue) { providers.gradleProperty(name).getOrElse(defaultValue) @@ -187,14 +189,12 @@ task autoGenerate(dependsOn: [messages, params, extensionPoints, generatePlatfor task pdf(type: DitaOtTask, dependsOn: autoGenerate) { group = 'documentation' description = 'Build PDF documentation.' - // Set DITA-OT directory: pass as parameter -PditaHome or fall back to parent when run in core repo. ditaOt file(findProperty('ditaHome') ?: ditaHome) input "${projectDirPath}/userguide-book.ditamap" output outputDir transtype 'pdf' filter "${projectDirPath}/resources/pdf.ditaval" - // Use ditaProperties MapProperty directly for v2.3.0 compatibility ditaProperties.put('args.chapter.layout', 'BASIC') ditaProperties.put('args.gen.task.lbl', 'YES') ditaProperties.put('include.rellinks', '#default external') @@ -205,14 +205,12 @@ task pdf(type: DitaOtTask, dependsOn: autoGenerate) { task html(type: DitaOtTask, dependsOn: autoGenerate) { group = 'documentation' description = 'Build HTML5 documentation.' - // Set DITA-OT directory: pass as parameter -PditaHome or fall back to parent when run in core repo. ditaOt file(findProperty('ditaHome') ?: ditaHome) input "${projectDirPath}/userguide.ditamap" output outputDir transtype 'html5' filter "${projectDirPath}/resources/html.ditaval" - // Use ditaProperties MapProperty directly for v2.3.0 compatibility ditaProperties.put('args.copycss', 'yes') ditaProperties.put('args.css', 'dita-ot-doc.css') ditaProperties.put('args.csspath', 'css') @@ -227,45 +225,26 @@ task html(type: DitaOtTask, dependsOn: autoGenerate) { task htmlhelp(type: DitaOtTask, dependsOn: autoGenerate) { group = 'documentation' description = 'Build HTML Help (.chm) documentation.' - // Set DITA-OT directory: pass as parameter -PditaHome or fall back to parent when run in core repo. ditaOt file(findProperty('ditaHome') ?: ditaHome) input "${projectDirPath}/userguide.ditamap" output outputDir transtype 'htmlhelp' filter ditavalFile - // Use ditaProperties MapProperty directly for v2.3.0 compatibility ditaProperties.put('args.copycss', 'yes') ditaProperties.put('args.css', 'dita-ot-doc.css') ditaProperties.put('args.csspath', 'css') ditaProperties.put('args.cssroot', "${projectDirPath}/resources/") ditaProperties.put('args.gen.task.lbl', 'YES') - - 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 - } - } } -task cleanOutput { +task cleanOutput(type: Delete) { group = 'build' description = 'Delete the output directory.' - doLast { - delete outputDir - } + delete file(outputDir) } // Get git commit hash using Gradle 9 compatible Provider API -// Uses providers.exec() instead of deprecated project.exec() def gitCommitHash = providers.exec { commandLine 'git', 'rev-parse', 'HEAD' ignoreExitValue = true @@ -274,13 +253,10 @@ def gitCommitHash = providers.exec { task gitMetadata { group = 'build' description = 'Log git commit metadata.' - // This task just logs the git commit for reference doLast { logger.lifecycle("Git commit: ${gitCommitHash}") } - - // Mark outputs to help with up-to-date checking - outputs.upToDateWhen { false } // Always run since git commit changes frequently + outputs.upToDateWhen { false } } task site(type: DitaOtTask) { @@ -288,26 +264,60 @@ task site(type: DitaOtTask) { description = 'Build website documentation.' dependsOn 'messages', 'params', 'extensionPoints', 'gitMetadata' - // Set DITA-OT directory: pass as parameter -PditaHome or fall back to parent when run in core repo. ditaOt file(findProperty('ditaHome') ?: ditaHome) input file("${projectDirPath}/site.ditamap") output getPropertyOrDefault('outputDir', layout.buildDirectory.dir("site").get().asFile.path) filter "${projectDirPath}/resources/site.ditaval" - transtype 'org.dita-ot.html' // Evaluate the noCommitMeta flag at configuration time def includeCommitMeta = !providers.gradleProperty('noCommitMeta').map { Boolean.parseBoolean(it) }.getOrElse(false) - // Use ditaProperties MapProperty directly for v2.3.0 compatibility ditaProperties.put('args.gen.task.lbl', 'YES') ditaProperties.put('args.rellinks', 'noparent') if (includeCommitMeta) { - // Use the git commit hash obtained at configuration time ditaProperties.put('commit', gitCommitHash) } } +// ============================================================================= +// Verification Tasks (v2.8.1 features) +// ============================================================================= + +task validateDita(type: DitaOtValidateTask) { + group = 'verification' + description = 'Validate DITA content without full transformation.' + ditaOtDir = file(findProperty('ditaHome') ?: ditaHome) + inputFiles = files( + "${projectDirPath}/userguide.ditamap", + "${projectDirPath}/userguide-book.ditamap", + "${projectDirPath}/site.ditamap" + ) + strictMode = false + failOnError = true +} + +task checkLinks(type: DitaLinkCheckTask) { + group = 'verification' + description = 'Check for broken internal and external links.' + inputFiles = files( + "${projectDirPath}/userguide.ditamap", + "${projectDirPath}/userguide-book.ditamap" + ) + checkExternal = false // Set to true to also check external URLs + failOnBroken = true + recursive = true +} + +task verify(dependsOn: [validateDita, checkLinks]) { + group = 'verification' + description = 'Run all verification tasks (validate DITA and check links).' +} + +// ============================================================================= +// Aggregate Tasks +// ============================================================================= + task all(dependsOn: [pdf, html, htmlhelp]) { group = 'documentation' description = 'Build all documentation formats (PDF, HTML, HTMLHelp).' diff --git a/gradle.properties b/gradle.properties index f8f1fc68..f4ad7c61 100644 --- a/gradle.properties +++ b/gradle.properties @@ -1,10 +1,7 @@ # Fix Java memory errors with Gradle 5.2 org.gradle.jvmargs = -Xmx1024m -# Gradle 8 features for better performance and caching -# ↓ Not supported by eerohele/dita-ot-gradle ↓ -# org.gradle.configuration-cache=true -# org.gradle.configuration-cache.problems=warn -# ↑ Not supported by eerohele/dita-ot-gradle ↑ +# Gradle 9 features for better performance and caching +org.gradle.configuration-cache=true org.gradle.parallel=true org.gradle.caching=true From 68964181aab0dc6b0f578c4859892bea19090879 Mon Sep 17 00:00:00 2001 From: Jeremy Jeanne Date: Mon, 26 Jan 2026 12:10:29 +0100 Subject: [PATCH 2/3] Restore doLast block for htmlhelp task Fix accidental removal during refactoring. This block moves .chm files from htmlhelp/ subdirectory to output root and cleans up." Co-authored-by: Jeremy Jeanne Signed-off-by: Jeremy Jeanne --- build.gradle | 16 +++++++++++++++- 1 file changed, 15 insertions(+), 1 deletion(-) diff --git a/build.gradle b/build.gradle index de4be04c..a2c82e86 100644 --- a/build.gradle +++ b/build.gradle @@ -8,7 +8,7 @@ buildscript { } plugins { - id 'io.github.jyjeanne.dita-ot-gradle' version '2.8.1' + id 'io.github.jyjeanne.dita-ot-gradle' version '2.8.2' // Removed: 'com.github.eerohele.saxon-gradle' - not Configuration Cache compatible // Replaced with: inline XsltTransformTask class below } @@ -236,6 +236,20 @@ task htmlhelp(type: DitaOtTask, dependsOn: autoGenerate) { ditaProperties.put('args.csspath', 'css') ditaProperties.put('args.cssroot', "${projectDirPath}/resources/") ditaProperties.put('args.gen.task.lbl', 'YES') + + 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 + } + } } task cleanOutput(type: Delete) { From eba1fb7cb843094c3f693544459150829e98943b Mon Sep 17 00:00:00 2001 From: Jeremy Jeanne Date: Tue, 27 Jan 2026 10:11:57 +0100 Subject: [PATCH 3/3] Remove verification tasks (validateDita, checkLinks) - DitaOtValidateTask has false positive issues on generated files - Use native 'dita validate' subcommand for validation instead Co-authored-by: Jeremy Jeanne Signed-off-by: Jeremy Jeanne --- build.gradle | 32 -------------------------------- 1 file changed, 32 deletions(-) diff --git a/build.gradle b/build.gradle index a2c82e86..8bffbffa 100644 --- a/build.gradle +++ b/build.gradle @@ -96,8 +96,6 @@ abstract class XsltTransformTask extends DefaultTask { } import com.github.jyjeanne.DitaOtTask -import com.github.jyjeanne.DitaOtValidateTask -import com.github.jyjeanne.DitaLinkCheckTask def getPropertyOrDefault(String name, def defaultValue) { providers.gradleProperty(name).getOrElse(defaultValue) @@ -298,36 +296,6 @@ task site(type: DitaOtTask) { // Verification Tasks (v2.8.1 features) // ============================================================================= -task validateDita(type: DitaOtValidateTask) { - group = 'verification' - description = 'Validate DITA content without full transformation.' - ditaOtDir = file(findProperty('ditaHome') ?: ditaHome) - inputFiles = files( - "${projectDirPath}/userguide.ditamap", - "${projectDirPath}/userguide-book.ditamap", - "${projectDirPath}/site.ditamap" - ) - strictMode = false - failOnError = true -} - -task checkLinks(type: DitaLinkCheckTask) { - group = 'verification' - description = 'Check for broken internal and external links.' - inputFiles = files( - "${projectDirPath}/userguide.ditamap", - "${projectDirPath}/userguide-book.ditamap" - ) - checkExternal = false // Set to true to also check external URLs - failOnBroken = true - recursive = true -} - -task verify(dependsOn: [validateDita, checkLinks]) { - group = 'verification' - description = 'Run all verification tasks (validate DITA and check links).' -} - // ============================================================================= // Aggregate Tasks // =============================================================================