From 0952e5f974bd2329037851ef90a9b126a754c796 Mon Sep 17 00:00:00 2001 From: Berchris Requiao Date: Mon, 23 Aug 2021 21:04:41 +0100 Subject: [PATCH 1/2] Document how to use org.asciidoctor.jvm.convert Gradle plugin See gh-744 --- docs/src/docs/asciidoc/getting-started.adoc | 28 +++++++++++++-------- 1 file changed, 17 insertions(+), 11 deletions(-) diff --git a/docs/src/docs/asciidoc/getting-started.adoc b/docs/src/docs/asciidoc/getting-started.adoc index 53af31fb..deef47db 100644 --- a/docs/src/docs/asciidoc/getting-started.adoc +++ b/docs/src/docs/asciidoc/getting-started.adoc @@ -146,11 +146,15 @@ macro. .Gradle ---- plugins { <1> - id "org.asciidoctor.convert" version "1.5.9.2" + id "org.asciidoctor.jvm.convert" version "3.3.2" + } + + configurations { + asciidoctorExt } dependencies { - asciidoctor 'org.springframework.restdocs:spring-restdocs-asciidoctor:{project-version}' <2> + asciidoctorExt 'org.springframework.restdocs:spring-restdocs-asciidoctor:{project-version}' <2> testImplementation 'org.springframework.restdocs:spring-restdocs-mockmvc:{project-version}' <3> } @@ -163,25 +167,27 @@ macro. } asciidoctor { <6> - inputs.dir snippetsDir <7> - dependsOn test <8> + inputs.dir snippetsDir <7> + configurations 'asciidoctorExt' <8> + dependsOn test <9> } ---- <1> Apply the Asciidoctor plugin. -<2> Add a dependency on `spring-restdocs-asciidoctor` in the `asciidoctor` configuration. -This will automatically configure the `snippets` attribute for use in your `.adoc` files -to point to `build/generated-snippets`. It will also allow you to use the `operation` -block macro. +<2> Add a dependency on `spring-restdocs-asciidoctor` in the `asciidoctorExt` +configuration. This will automatically configure the `snippets` attribute for use in your +`.adoc` files to point to `build/generated-snippets`. It will also allow you to use the +`operation` block macro. <3> Add a dependency on `spring-restdocs-mockmvc` in the `testImplementation` configuration. If you want to use `WebTestClient` or REST Assured rather than MockMvc, add a dependency on `spring-restdocs-webtestclient` or `spring-restdocs-restassured` respectively instead. <4> Configure a property to define the output location for generated snippets. <5> Configure the `test` task to add the snippets directory as an output. -<6> Configure the `asciidoctor` task +<6> Configure the `asciidoctor` task. <7> Configure the snippets directory as an input. -<8> Make the task depend on the test task so that the tests are run before the - documentation is created. +<8> Add the configuration for the Asciidoctor external library extensions. +<9> Make the task depend on the test task so that the tests are run before the +documentation is created. ==== [[getting-started-build-configuration-packaging-the-documentation]] From acd60c7068c47441a5f307db654fca3db45f8f1b Mon Sep 17 00:00:00 2001 From: Andy Wilkinson Date: Mon, 10 Jan 2022 11:12:40 +0000 Subject: [PATCH 2/2] Polish "Document how to use org.asciidoctor.jvm.convert Gradle plugin" See gh-744 --- docs/src/docs/asciidoc/getting-started.adoc | 35 +++++++++++---------- 1 file changed, 18 insertions(+), 17 deletions(-) diff --git a/docs/src/docs/asciidoc/getting-started.adoc b/docs/src/docs/asciidoc/getting-started.adoc index deef47db..164cc56f 100644 --- a/docs/src/docs/asciidoc/getting-started.adoc +++ b/docs/src/docs/asciidoc/getting-started.adoc @@ -150,43 +150,44 @@ macro. } configurations { - asciidoctorExt + asciidoctorExt <2> } dependencies { - asciidoctorExt 'org.springframework.restdocs:spring-restdocs-asciidoctor:{project-version}' <2> - testImplementation 'org.springframework.restdocs:spring-restdocs-mockmvc:{project-version}' <3> + asciidoctorExt 'org.springframework.restdocs:spring-restdocs-asciidoctor:{project-version}' <3> + testImplementation 'org.springframework.restdocs:spring-restdocs-mockmvc:{project-version}' <4> } - ext { <4> + ext { <5> snippetsDir = file('build/generated-snippets') } - test { <5> + test { <6> outputs.dir snippetsDir } - asciidoctor { <6> - inputs.dir snippetsDir <7> - configurations 'asciidoctorExt' <8> - dependsOn test <9> + asciidoctor { <7> + inputs.dir snippetsDir <8> + configurations 'asciidoctorExt' <9> + dependsOn test <10> } ---- <1> Apply the Asciidoctor plugin. -<2> Add a dependency on `spring-restdocs-asciidoctor` in the `asciidoctorExt` +<2> Declare the `asciidoctorExt` configuration for dependencies that extend Asciidoctor. +<3> Add a dependency on `spring-restdocs-asciidoctor` in the `asciidoctorExt` configuration. This will automatically configure the `snippets` attribute for use in your `.adoc` files to point to `build/generated-snippets`. It will also allow you to use the `operation` block macro. -<3> Add a dependency on `spring-restdocs-mockmvc` in the `testImplementation` +<4> Add a dependency on `spring-restdocs-mockmvc` in the `testImplementation` configuration. If you want to use `WebTestClient` or REST Assured rather than MockMvc, add a dependency on `spring-restdocs-webtestclient` or `spring-restdocs-restassured` respectively instead. -<4> Configure a property to define the output location for generated snippets. -<5> Configure the `test` task to add the snippets directory as an output. -<6> Configure the `asciidoctor` task. -<7> Configure the snippets directory as an input. -<8> Add the configuration for the Asciidoctor external library extensions. -<9> Make the task depend on the test task so that the tests are run before the +<5> Configure a property to define the output location for generated snippets. +<6> Configure the `test` task to add the snippets directory as an output. +<7> Configure the `asciidoctor` task. +<8> Configure the snippets directory as an input. +<9> Configure the use of the `asciidoctorExt` configuration for extensions. +<10> Make the task depend on the test task so that the tests are run before the documentation is created. ====