Prepare for Asciidoctor Gradle Plugin 2.0 by looking for gradle-projectdir and using projectdir as a fallback

[SimonScholz]

While trying to generate docs with asciidoc I ran into the issue that the "projectdir attribute was not found".

For some reason this code tries to get it from the documents attributes, which does not have such an attribute.
Default attributes can be found here: https://github.com/asciidoctor/asciidoctor/wiki/Catalog-of-Document-Attributes

Here is the code, which fails:

spring-restdocs/spring-restdocs-asciidoctor/src/main/java/org/springframework/restdocs/asciidoctor/SnippetsDirectoryResolver.java

Line 60 in 9deae49

return new File(getRequiredAttribute(attributes, "projectdir"),

Here is what I´ve done to fix this: https://github.com/vogellacompany/codeexamples-javaweb/blob/5497ff9040cb9ca603c74588252fb3039d51f47a/com.vogella.springboot2.todo/build.gradle#L63

Maybe your gradle plugin should add this attribute, like I´ve done in my gradle build file.

[wilkinsona]

The attribute should be set by Asciidoctor’s Gradle plugin. Unfortunately, the version that you are using contains a breaking change to the attribute name. This has been reverted in this commit but not yet released. I would recommend using 1.5.3 of the Asciidoctor Gradle Plugin, as all REST Docs’ samples do, for now.

[wilkinsona]

This is the PR that fixed the attribute names.

[SimonScholz]

Thanks for your response.
I just made use of the latest 1.5.9. version, because I had issues with the encoding of the path to jruby, which I now fixed by specifying -Dfile.encoding=UTF-8 as jvm arg for my gradle build in my gradle.properties file.
Looking forward to use the latest asciidoctor version soon, once the regression fix has been released.

[ysb33r]

Asciidoctor-gradle-plugin 1.5.9.2 has been released. Hopefully this will resolve the problem.

[wilkinsona]

Thanks very much, @ysb33r.

[SimonScholz]

Thanks @ysb33r
When I run my build with 1.5.9.2 now it works, but I also get this output.
> Task :asciidoctor Implicit attributes projectdir and rootdir are deprecated and will no longer be set in 2.0. Please migrate your documents to use gradle-projectdir and gradle-rootdir instead.

So I think the spring-restdocs team should update their plugin, right?

[wilkinsona]

1.5.9.2 always logs that warning. See asciidoctor/asciidoctor-gradle-plugin#270. A change has been made such that 1.5.9.3 or 1.5.9.10 will only log the warning if that attribute is used in a source document. It won't detect its usage in SnippetsDirectoryResolver so the warning will not be generated.

That said, we can use this issue to prepare for Asciidoctor Gradle Plugin 2.0 by looking for gradle-projectdir and falling back to projectdir if it's not there.

[ysb33r]

1.5.9.2 always logs that warning. See asciidoctor/asciidoctor-gradle-plugin#270. A change has been made such that 1.5.9.3 or 1.5.9.10 will only log the warning if that attribute is used in a source document. It won't detect its usage in SnippetsDirectoryResolver so the warning will not be generated.

Correct. The 1.5.9.3 implementation in the Gradle plugin will simply scan the asciidoc source directory for potential uses, so it will not detect is the this context.

Please feel free to raise questions in the Asciidoctor Gradle plugin Github project, especially if you think the changes we are making in 2.0 will break yuor way of working rather than improve it.