Warn against the use of org.asciidoctor.convert 1.5.6

[sdavids]

plugins {
  id 'org.asciidoctor.convert' version '1.5.6'
}

testCompile('org.springframework.restdocs:spring-restdocs-core:1.2.2.RELEASE')

The combination above will not replace

operation::my-example[snippets='httpie-request,http-request']

with the generated snippets.

Version 1.5.3 works.

[wilkinsona]

Given that this works with 1.5.3 and does not work with 1.5.6, it sounds like it may be a regression in Asciidoctor. Have you spoken with the Asciidoctor team?

/cc @mojavelinux

[mojavelinux]

I would start with thinking this is an issue with the Gradle plugin. But to be sure, can you change the plugin version back to 1.5.3 and set the version of AsciidoctorJ using:

asciidoctorj {
  version = '1.5.6'
}

Then we'll know if was a change to the plugin or to AsciidoctorJ that is causing the difference.

[wilkinsona]

I've spent some time trying to reproduce the behaviour described above and have been unable to do so. REST Docs' own samples work fine with both 1.5.3 and 1.5.6.

This doesn't explain why you observed it working with 1.5.3 and not with 1.5.6 but, on closer inspection, one possible problem is that you've made no mention of the org.springframework.restdocs:spring-restdocs-asciidoctor:1.2.2.RELEASE dependency that needs to be added to the asciidoctor configuration. The operation macro will not work without that dependency.

@sdavids If you'd like us to spend some more time investigating this please provide a small sample that reproduces the problem and we can re-open this issue.

[jlstrater]

I've seen this issue too. :(

When it happens, this line appears in the output asciidoctor: WARNING: dropping line containing reference to missing attribute: snippets and all includes fail too so it seems to be part of a bigger issue.

Here is a reference to a commit: https://github.com/jlstrater/groovy-spring-boot-restdocs-example/tree/410f31194759173e89f75dc4fd7b8d44d863a4a2

[mojavelinux]

Is it an intermittent issue or does it happen consistently for a certain configuration? It seems clear to me that the snippets attribute is not being passed to the processor.

[wilkinsona]

@jlstrater Thanks. I've built that commit locally and everything appears to work. I didn't see any warnings being logged and the resulting HTML contains the output of the snippets that are imported by the operation macro. Do you know what I might need to do to get it to fail?

[jlstrater]

Ok. It seems to be a Gradle issue. It works the first time the gradle daemon is used(https://scans.gradle.com/s/2xny6ilzzdquk/console-log) but fails on subsequent builds(https://scans.gradle.com/s/iftdikx6czzzw/console-log, https://scans.gradle.com/s/ynqeun4juvtio/console-log). Also, when following @mojavelinux 's instructions to downgrade the gradle plugin version and change the asciidoctorj version everything works again.

[wilkinsona]

Thanks again, @jlstrater. I can reproduce the problem now.

When it fails, it's behaving like spring-restdocs-asciidoctor isn't there. The Preprocessor that sets the snippets attribute doesn't appear to be called, and the operation block macro doesn't appear to have been registered. These problems lead to output in the generated HTML like the following:

Unresolved directive in index.adoc - include::{snippets}/error-example/response-fields.adoc[]

…

operation::error-example[snippets='curl-request,http-request,http-response']

[wilkinsona]

Dropping back to 1.5.3 of the Asciidoctor Gradle plugin does indeed make the problem go away as @sdavids originally reported. The problem also doesn't occur with 1.5.3 of the Gradle plugin and Asciidoctor 1.5.6.

In summary, it appears that a change in 1.5.6 of the Asciidoctor Gradle plugin interacts with something in Gradle's daemon and triggers the problem.

[mojavelinux]

Is this problem being pursued upstream? I'm sure we can get the bottom of it if we get the right people involved ;)

[mduesterhoeft]

I also ran into this issue today. Would it make sense to reopen it? Also would it make sense to update the samples and documentation to use 1.5.3 of the Asciidoctor Gradle plugin. Currently I can reproduce the issue also with the samples - it works the first time you run the asciidoctor task for the project but if you change something and try again the issue appears.

[wilkinsona]

I've finally had some time to track this down. It's a regression in the Asciidoctor Gradle plugin caused by asciidoctor/asciidoctor-gradle-plugin#213. There's an existing issue that is tracking the regression: asciidoctor/asciidoctor-gradle-plugin#222. In addition to the problem occurring when using the daemon, it will also occur when using --continuous.