fix: api docs build failure

- problem: script `/scripts/generate_documentation_snippets.sh`
fails with:
```
In plugin 'org.asciidoctor.convert' type 'org.asciidoctor.gradle.AsciidoctorTask' property 'logDocuments' is annotated with @optional but that is not allowed for 'Console' properties.
```

- It looks like our asciidoctor lib is out of date and not compatible
with the new gradle. Hence, taking advice from
asciidoctor/asciidoctor-gradle-plugin#600,
migrate to a supported lib instead (`org.asciidoctor.jvm.convert`);
and use the latest version of that.

- The changes in this commit follows this sample app: https://github.com/spring-projects/spring-restdocs-samples/blob/c98c705ad9043aa19db96ce29160e0fbdfeaf8bc/restful-notes-spring-hateoas/build.gradle

- note: The directory changes in `credhub/backends/credhub/src/docs/asciidoc/index.adoc`
is required as part of this migration/upgrade; without these changes,
the rendered doc html will not correctly import those "snippets". The
new lib also seems to output the resulting html to a different dir,
so update tasks and readme to reflect that.

[#187494474]

README.md

@@ -61,7 +61,7 @@ The CredHub API can generate API documentation by running its test suite (via Sp
 ./scripts/generate_documentation_snippets.sh
 ```
 
-CredHub API documentation will be built as an html file in the CredHub backend gradle subproject build directory: `backends/credhub/build/asciidoc/html5`.
+CredHub API documentation will be built as an html file in the CredHub backend gradle subproject build directory: `backends/credhub/build/docs/asciidoc/index.html`.
 
 ### Development Configuration
 

backends/credhub/build.gradle

@@ -6,7 +6,7 @@ buildscript {
     }
     dependencies {
         classpath("org.springframework.boot:spring-boot-gradle-plugin:$springBootVersion")
-        classpath("org.asciidoctor.convert:org.asciidoctor.convert.gradle.plugin:${asciiDoctorConvertPluginVersion}")
+        classpath("org.asciidoctor.jvm.convert:org.asciidoctor.jvm.convert.gradle.plugin:${asciiDoctorConvertPluginVersion}")
         classpath("com.google.protobuf:protobuf-gradle-plugin:0.9.4")
     }
 }
@@ -16,7 +16,7 @@ apply plugin: "idea"
 apply plugin: 'kotlin'
 apply plugin: 'kotlin-spring'
 apply plugin: 'io.spring.dependency-management'
-apply plugin: 'org.asciidoctor.convert'
+apply plugin: 'org.asciidoctor.jvm.convert'
 apply from: "${rootDir.toPath()}/spring-rest-docs-config.gradle"
 apply from: "${rootDir.toPath()}/kotlin.gradle"
 apply from: "${rootDir.toPath()}/ktlint.gradle"
@@ -29,6 +29,10 @@ repositories {
     maven { url("https://plugins.gradle.org/m2/") }
 }
 
+configurations {
+    asciidoctorExtensions
+}
+
 dependencies {
     implementation project(":backends:shared-backend-configuration")
     implementation project(":backends:remote")
@@ -78,7 +82,7 @@ dependencies {
     implementation("com.jayway.jsonpath:json-path:${jsonPathVersion}")
 
     testImplementation("org.springframework.restdocs:spring-restdocs-mockmvc:$springRestDocsVersion")
-    asciidoctor("org.springframework.restdocs:spring-restdocs-asciidoctor:$springRestDocsVersion")
+    asciidoctorExtensions("org.springframework.restdocs:spring-restdocs-asciidoctor:$springRestDocsVersion")
 }
 
 dependencyManagement {
@@ -118,7 +122,7 @@ test {
 task buildAndCopyRestDocsIntoSpringStaticAssetLocation(type: Copy) {
     dependsOn asciidoctor
 
-    from file("build/asciidoc/html5/index.html")
+    from file("build/docs/asciidoc/index.html")
     into project(":applications:credhub-api").file("src/main/resources/static/docs/")
 }
 asciidoctor.finalizedBy(buildAndCopyRestDocsIntoSpringStaticAssetLocation)

backends/credhub/src/docs/asciidoc/index.adoc

@@ -7,53 +7,52 @@
 :docinfo:
 
 = CredHub API
-
-include::snippets/introduction.adoc[]
+include::src/docs/asciidoc/snippets/introduction.adoc[]
 
 ---
 
-include::snippets/authentication.adoc[]
+include::src/docs/asciidoc/snippets/authentication.adoc[]
 
 ---
 
-include::snippets/credentials-v1.adoc[]
+include::src/docs/asciidoc/snippets/credentials-v1.adoc[]
 
 ---
 
-include::snippets/certificates-v1.adoc[]
+include::src/docs/asciidoc/snippets/certificates-v1.adoc[]
 
 ---
 
-include::snippets/permissions-v2.adoc[]
+include::src/docs/asciidoc/snippets/permissions-v2.adoc[]
 
 ---
 
-include::snippets/permissions-v1.adoc[]
+include::src/docs/asciidoc/snippets/permissions-v1.adoc[]
 
 ---
 
-include::snippets/regenerate-v1.adoc[]
+include::src/docs/asciidoc/snippets/regenerate-v1.adoc[]
 
 ---
 
-include::snippets/interpolate-v1.adoc[]
+include::src/docs/asciidoc/snippets/interpolate-v1.adoc[]
 
 ---
 
-include::snippets/encryption-key-usage-v1.adoc[]
+include::src/docs/asciidoc/snippets/encryption-key-usage-v1.adoc[]
 
 ---
 
-include::snippets/management-v1.adoc[]
+include::src/docs/asciidoc/snippets/management-v1.adoc[]
 
 ---
 
-include::snippets/info-v1.adoc[]
+include::src/docs/asciidoc/snippets/info-v1.adoc[]
 
 ---
 
-include::snippets/version-v1.adoc[]
+include::src/docs/asciidoc/snippets/version-v1.adoc[]
 
 ---
 
-include::snippets/health-v1.adoc[]
+include::src/docs/asciidoc/snippets/health-v1.adoc[]

build.gradle

@@ -5,7 +5,7 @@ buildscript {
         apacheCommonsLang3Version = '3.14.0'
         apacheCommonsIoVersion = '2.16.1'
         apacheHttpClientVersion = '4.5.14'
-        asciiDoctorConvertPluginVersion = '2.4.0'
+        asciiDoctorConvertPluginVersion = '4.0.2'
         bcpkixFipsVersion = '1.0.7'
         bcFipsVersion = '1.0.2.5'
         commonsCodecVersion = '1.17.0' // remove this after deleting (now deprecated) spring-security-oauth2

spring-rest-docs-config.gradle

@@ -7,6 +7,7 @@ test {
 }
 
 asciidoctor {
+    configurations "asciidoctorExtensions"
     inputs.dir snippetsDir
     dependsOn test
 }