Build the AsciiDoc files again if a template changed

[ggrossetie]

I'm not sure if I need to configure something explicitly (or not) but I've noticed that Gradle won't process AsciiDoc files again if a template changed.

I'm using the following configuration:

asciidoctor {
  asciidoctorj {
    options template_dirs: ["${project.projectDir}/resources/templates"]
  }
}

First run with a clean copy

$ git st
On branch master
Your branch is up to date with 'origin/master'.

nothing to commit, working tree clean

$ ./gradlew asciidoctor                                          

Deprecated Gradle features were used in this build, making it incompatible with Gradle 7.0.
Use '--warning-mode all' to show the individual deprecation warnings.
See https://docs.gradle.org/6.0.1/userguide/command_line_interface.html#sec:command_line_warnings

BUILD SUCCESSFUL in 4s
1 actionable task: 1 executed

Edit a template file

$ git st
On branch master
Your branch is up to date with 'origin/master'.

Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git restore <file>..." to discard changes in working directory)
    modified:   resources/templates/document.html.erb

no changes added to commit (use "git add" and/or "git commit -a")

Run again

$ ./gradlew asciidoctor              

Deprecated Gradle features were used in this build, making it incompatible with Gradle 7.0.
Use '--warning-mode all' to show the individual deprecation warnings.
See https://docs.gradle.org/6.0.1/userguide/command_line_interface.html#sec:command_line_warnings

BUILD SUCCESSFUL in 408ms
1 actionable task: 1 up-to-date

As you can see it took only 408ms because Gradle didn't process the AsciiDoc files.

[ysb33r]

Now it won't. We should really have a nice templates feature on Asciidoctor instead of resorting to using options.

Anyhow, you can workaround it by doing

asciidoctor {
  inputs.file "${project.projectDir}/resources/templates"
}

[ggrossetie]

Thanks for the workaround, I will give it a try. I guess I should do the same for include files, docinfo and embed images right? input.file takes a list of paths or can I call it multiple times?

asciidoctor {
  inputs.file "${project.projectDir}/resources/templates"
  inputs.file "${project.projectDir}/docs/**.html" // docinfo files
  inputs.file "${project.projectDir}/resources/images/**" // embed images
}

[ysb33r]

inputs.files is what you would need in that case OR you can call inputs.file multiple times. Docinfo files should automatically be checked for changes.

[ysb33r]

And now I woke up. So docinfo files are already (and correctly) covered if you use the html or docbook backends. This is done via the default setup for secondarySources (items partaking in the document generation, but does not end up in the destination fodler). See https://github.com/asciidoctor/asciidoctor-gradle-plugin/blob/a4507c00eb50d2e807f89105acab788ebf97a002/asciidoctor-gradle-jvm/src/main/groovy/org/asciidoctor/gradle/jvm/AsciidoctorTask.groovy#L115 for the gory details.

Images are normally setup via

asciidoctor {
   resources {
      from 'resources'
      include 'images/**'
   }
}

If you did something like that changes in images should be automatically detected. If they are not, then it is a bug.

You can also pass your templates to secondarySources instead of using inputs, but if you are and intermediate working directory, it will be referencing the incorrect location. Probably not a big deal in your czse as everything will still work.

[ggrossetie]

So docinfo files are already (and correctly) covered if you use the html or docbook backends.

I'm using docinfo with the reveal.js backend. I think that's the reason why it's not working. Should I open a pull request to implement the same logic in the reveal.js module ?

Now it won't. We should really have a nice templates feature on Asciidoctor instead of resorting to using options.

Can I open a pull request to introduce a dedicated attribute "templates"? Should we automatically add templates to the input.files?

[ysb33r]

I'm using docinfo with the reveal.js backend. I think that's the reason why it's not working. Should I open a pull request to implement the same logic in the reveal.js module ?

That makes sense as the Reveal task does not extend the AsciidoctorTask. I think if you want to do a PR to add the functionality to AsciidoctorJRevealJSTask, then that would be great.

[ysb33r]

Can I open a pull request to introduce a dedicated attribute "templates"? Should we automatically add templates to the input.files?

I think you should rather just work around it for now, but also raise an isue for this functionality to be added. I want to give a bit of thought on how to implement it in a more gradlesque way (maybe similar to what was done for PDF themes).

[wilkinsona]

@ysb33r I've just been caught out by included files not automatically being part of the task's inputs. This breaks up-to-date checks and, upon a clean build, results in a cache hit when it should have missed. Included files are mentioned above but the title suggest's the issue is focused on templates. Is this issue tracking addressing this or is a separate issue warranted?

[wilkinsona]

I've been trying to figure out what's going on with the above. As far as I can tell, the secondary source file tree should cover the included files. That is indeed what happens in a standalone reproduction attempt, but not in my actual build.

@ysb33r Sorry for the noise. Please ignore this for now until I manage to reproduce it with a minimal project.