Replace Ant build with Gradle build

[eerohele]

Signed-off-by: Eero Helenius eero.helenius@kapsi.fi

[infotexture]

👍 I compared the output generated by the dist target in this build file with that produced by the Ant build and found it to be identical, with one exception.

💥 The new build not only generates the platform filter file, but also applies it to each target, so no content with @platform="windows" is included when building on macOS or Linux.

This was certainly the original intent, but it appears the Ant build never actually applied the generated filter file (presumably to ensure distribution builds include all content, regardless of the platform on which they are run).

So the new build is working as intended, but exposes errors in the logic elsewhere.

For example on macOS, an empty table is produced for http://www.dita-ot.org/dev/user-guide/increasing-the-jvm.html. That table uses <chrow platform="unix">, which according to the subject scheme is either osx or linux.

<subjectdef keys="unix">
  <subjectdef keys="osx"/>
  <subjectdef keys="linux"/>
</subjectdef>

But the filtering routine seems to ignore this definition and exclude the row, since the current platform is not literally unix.

If the source file is changed to <chrow platform="linux osx"> the content is included as expected.

❓@jelovirt: Should the filtering process be respecting the subjectScheme? If this is a bug, I'll file a separate issue in the core repo, but I'm not sure if it's an error in the docs source files.

Disable filters in distribution builds

I think the solution here is to simply remove the filter lines from the pdf and html tasks in build.gradle to ensure CI builds include all content.

I'd be inclined to leave the filter active in the htmlhelp task, since it doesn't make much sense to include info on UNIX in a Windows-only help format.

[infotexture]

@jelovirt Merging this will require changes to the distribution build task in the core repo, so we may want to coordinate the timing of the merge to minimize errors.

[eerohele]

I can remove the filters for the PDF and HTML builds. I'll do it when I get the chance.

I also need to modify publish.sh to use build.gradle instead of site.gradle.

[infotexture]

@eerohele:

I can remove the filters for the PDF and HTML builds. I'll do it when I get the chance.

Sure, feel free to update the branch if you have time. If not, I can do that right after we merge this.

I also need to modify publish.sh to use build.gradle instead of site.gradle.

Good point, hadn't thought of that yet.

[infotexture]

Also confirmed this new build file works with Markdown input. 👍

[eerohele]

Should we just remove the generatePlatformFilter task (which auto-generates the DITAVAL file based on the platform)? Would it be better to just have a static windows.ditaval file for the HTML Help output?

[eerohele]

Also, in publish.sh, there's this:

-PditaHomeSrc=$DITA_OT_DEV

And in the current site.gradle version, there's this:

def ditaHomeSrc = project.hasProperty("ditaHomeSrc") ? file("${ditaHomeSrc}") : file("${ditaHome}")
def configDir = "$ditaHomeSrc/config"

But my PR (inadvertently) removes the ditaHomeSrc variable.

I don't quite understand its purpose. Could you enlighten me on that so that I can put it back (in some form or another)?

[infotexture]

Should we just remove the generatePlatformFilter task?

I'd be inclined to keep it, as this approach may serve as a useful example to others with similar requirements. I'd just remove the filters for the PDF and HTML builds.

As for the purpose of the ditaHomeSrc variable, we use the stable (last released) version of the toolkit to run the conversion, but also download the latest development version of the toolkit to get the plugin configuration for generated topics from there.

So we use a stable toolkit to run the build, but generate topics from the bleeding edge source files.

[eerohele]

I'd be inclined to keep it, as this approach may serve as a useful example to others with similar requirements. I'd just remove the filters for the PDF and HTML builds.

Sure thing. One thing to note, though, is that if you generate HTML Help output on a non-Windows platform, the resulting output will have non-Windows content, too.

As for the purpose of the ditaHomeSrc variable, we use the stable (last released) version of the toolkit to run the conversion, but also download the latest development version of the toolkit to get the plugin configuration for generated topics from there.

So we use a stable toolkit to run the build, but generate topics from the bleeding edge source files.

OK, I see — thanks for the explanation. I'll modify build.gradle accordingly.

[infotexture]

if you generate HTML Help output on a non-Windows platform, the resulting output will have non-Windows content

Theoretically yes, but the risk is low, since the HTML Help Workshop required to compile the CHM is Windows-only software. (Not sure how many would generate output on Linux/macOS for subsequent compilation on Windows, but the result would be extra content rather than data loss, so little danger.)

[eerohele]

I pushed the changes and cleaned up a few things. If you have the time, please give it another go. If you can, you could also test using ditaHomeSrcto make sure that bit still works OK. I gave it a quick try and it seems to work fine, as far as I can tell.

The CI build seems to be passing, now, too.

Note that when you invoke Gradle after these changes, you have to use gradle -PditaHome=... instead of gradle -Ddita.home=.... Since Ant is no longer involved, there's no reason to use Java system properties — we can use Gradle command-line parameters instead.

[infotexture]

I get a new message that I haven't seen before, but the build seems to complete successfully:

[ant:loadproperties] Unable to find resource application.properties

There are issues with missing conrefs in the PDF output (empty bullets on page 12, for example), but this is apparently related to upstream changes in the conref processing, as the same issues appear when building with Ant using dita-ot/dita-ot@19abe1998.

The content appears as expected when building with the master branch of the dita-ot repo, so I'll file a separate issue there for this.

@jelovirt Can you update the distribution builds to use this new Gradle build for docs instead of Ant?

[eerohele]

[ant:loadproperties] Unable to find resource application.properties

DITA-OT itself tries to load that property file, so I think it must be unrelated to this change.

Not sure why that popped up for you all of a sudden, though. Also not sure why that file is missing.

[infotexture]

👍 This has the added benefit of significantly faster distribution builds for docs (~42s).

We plan to merge this in for 3.0.1.

[eerohele]

I pushed one last change that updates the DITA-OT Gradle Plugin to version 0.4.3. That should fix the problems with --continuous.

[infotexture]

Pull request inadvertently closed when the release/3.0 branch was deleted.

Reopened and based on develop for 3.0.1

[jelovirt]

This and others assume the current repository is the docs repo or docsrc inside DITA-OT. This should be configurable with a paragraph, so that we can run Gradle from any random directory.

[eerohele]

I guess you mean that you should be able to do something like gradle -b ~/Git/docs/build.gradle -PditaHome=$DITA_HOME site, too, which you currently can't?

If so, I agree, and I pushed the changes.

[infotexture]

Tested a6da39d, verified the following:

• --continuous builds now work as expected: only actual changes re-trigger builds. 👍
• runs from any folder if paths to the build file, ditaHome, outputDir are passed as parameters 👍

✅ This should be suitable for use in DITA-OT distribution builds.

[jelovirt]

Could this be something like

String ditaHome = getPropertyOrDefault('ditaHome', buildscript.sourceFile.getParentFile().getParentFile().getAbsolutePath())

This way the default we would not need to define the ditaHome property.

[eerohele]

Done.