Document how to use REST Docs with the new org.asciidoctor.jvm.convert Gradle plugin

[pplmx]

spring-restdocs-asciidoctor seems that it doesn't support the latest asciidoctor plugin.

Here is my config.

/*id 'org.asciidoctor.jvm.convert' version '3.2.0'*/
id 'org.asciidoctor.convert' version '2.4.0'

/* for rest docs */
ext {
    set('snippetsDir', file('build/generated-snippets'))
    set('spring-restdocs.version', '2.0.4.RELEASE')
}

/* for rest docs */
testImplementation "org.springframework.restdocs:spring-restdocs-webtestclient:${project.ext['spring-restdocs.version']}"
asciidoctor "org.springframework.restdocs:spring-restdocs-asciidoctor:${project.ext['spring-restdocs.version']}"

test {
    outputs.dir snippetsDir
    useJUnitPlatform()
}

asciidoctor {
    attributes 'snippets': snippetsDir
    inputs.dir snippetsDir
    dependsOn test
}

bootJar {
    dependsOn asciidoctor
    from("${asciidoctor.outputDir}/html5") {
        into 'static/docs'
    }
}

gradle clean

13:01:39: Executing task 'clean'...

Configuration on demand is an incubating feature.

> Configure project :
You are using one or more deprecated Asciidoctor Gradle plugin features.
These will be removed in 3.0 of these plugins.
To help you migrate we have compiled some tips for you based upon your current usage.
- org.asciidoctor.convert:
  - 'org.asciidoctor.convert' is deprecated. When you have time please switch over to 'org.asciidoctor.jvm.convert'.
  - jcenter() is no longer added by default. If you relied on this behaviour in the past, please add jcenter() to the repositories block.



> Task :clean

BUILD SUCCESSFUL in 1s
1 actionable task: 1 executed
13:01:41: Task execution finished 'clean'.

gradle build

13:06:44: Executing task 'build'...

Configuration on demand is an incubating feature.

> Configure project :
You are using one or more deprecated Asciidoctor Gradle plugin features.
These will be removed in 3.0 of these plugins.
To help you migrate we have compiled some tips for you based upon your current usage.
- org.asciidoctor.convert:
  - 'org.asciidoctor.convert' is deprecated. When you have time please switch over to 'org.asciidoctor.jvm.convert'.
  - jcenter() is no longer added by default. If you relied on this behaviour in the past, please add jcenter() to the repositories block.



> Task :compileJava FROM-CACHE
> Task :processResources
> Task :classes
> Task :compileTestJava FROM-CACHE
> Task :processTestResources NO-SOURCE
> Task :testClasses UP-TO-DATE
> Task :test FROM-CACHE

> Task :asciidoctor
Property 'logDocuments' is annotated with @Optional that is not allowed for @Console properties. This behaviour has been deprecated and is scheduled to be removed in Gradle 7.0. See https://docs.gradle.org/6.3/userguide/more_about_tasks.html#sec:up_to_date_checks for more details.
WARNING: An illegal reflective access operation has occurred
WARNING: Illegal reflective access by org.codehaus.groovy.reflection.CachedClass (file:/C:/Users/purpl/.gradle/wrapper/dists/gradle-6.3-all/b4awcolw9l59x95tu1obfh9i8/gradle-6.3/lib/groovy-all-1.3-2.5.10.jar) to method java.lang.Object.finalize()
WARNING: Please consider reporting this to the maintainers of org.codehaus.groovy.reflection.CachedClass
WARNING: Use --illegal-access=warn to enable warnings of further illegal reflective access operations
WARNING: All illegal access operations will be denied in a future release

> Task :bootJar
> Task :jar SKIPPED
> Task :assemble
> Task :check UP-TO-DATE
> Task :build

BUILD SUCCESSFUL in 13s
6 actionable tasks: 3 executed, 3 from cache
13:06:58: Task execution finished 'build'.

[wilkinsona]

Have you tried using org.asciidoctor.jvm.convert? REST Docs cares about the underlying version of AsciidoctorJ that's being used rather than the Gradle plugin itself. If you see a failure with org.asciidoctor.jvm.convert can you please provide some details?

[pplmx]

If I use

id 'org.asciidoctor.jvm.convert' version '3.2.0'

gradle clean will throw

A problem occurred evaluating root project 'backend'.
> Could not find method asciidoctor() for arguments [org.springframework.restdocs:spring-restdocs-asciidoctor:2.0.4.RELEASE] on object of type org.gradle.api.internal.artifacts.dsl.dependencies.DefaultDependencyHandler.

[wilkinsona]

Thanks. That's a problem in your build.gradle rather than with REST Docs. As noted in the Asciidoctor Gradle plugin's documentation, the asciidoctor configuration is not created by default if you use the org.asciidoctor.jvm.convert plugin. You need to define a configuration and then configure the asciidoctor task to use it:

configurations {
    asciidoctorExt
}

dependencies {
    asciidoctorExt 'org.springframework.restdocs:spring-restdocs-asciidoctor'
    // …
}

asciidoctor {
    configurations 'asciidoctorExt'
    // …
}

We can use this issue to track making some updates to REST Docs' documentation to show how the newer Asciidoctor Gradle plugin should be configured.

[pplmx]

Thanks for your help.

[pplmx]

If include not found, you can follow this asciidoctor/asciidoctor-gradle-plugin#549

[brneto]

@wilkinsona I faced the same issue and your comment solved it. I can document this for you if you don't mind. Just point it out where I should update this that I'll do.

Would it be here:
https://asciidoctor.github.io/asciidoctor-gradle-plugin/development-3.x/user-guide/
https://github.com/asciidoctor/asciidoctor-gradle-plugin/blob/master/docs/src/docs/asciidoc/parts/quick-start.adoc

[wilkinsona]

Closing in favor of #744.