From 2342f5f48a264212d650cc6e22930556395184aa Mon Sep 17 00:00:00 2001 From: Sam Brannen Date: Fri, 18 Sep 2020 17:58:25 +0200 Subject: [PATCH 1/3] Remove unnecessary folders and files from PDF reference documentation Prior to this commit, the asciidoctor Gradle task was configured to generate both the HTML5 and PDF backends. Unfortunately, this resulted in resources such as HTML, JavaScript, CSS, and images being published alongside the generated PDF documents. This commit addresses this issue by introducing the use of a dedicated asciidoctorPdf Gradle task. The existing asciidoctor Gradle task has been modified to only generate HTML5 output. Both of these tasks now share common configuration supplied by the updated asciidoctorj Gradle task. In addition, the asciidoctor task now depends on the asciidoctorPdf task. Thus, invoking `./gradlew asciidoctor` will still generate both the HTML5 and PDF outputs; whereas, `./gradlew asciidoctorPdf` will generate only the PDF outputs. We may later decide to rework the tasks to introduce a dedicated asciidoctorHtml task so that we can generate the HTML outputs without having to generate the PDF outputs (which are more time consuming). See gh-25783 --- build.gradle | 1 + gradle/docs.gradle | 56 ++++++++++++++++++++++++++++------------------ 2 files changed, 35 insertions(+), 22 deletions(-) diff --git a/build.gradle b/build.gradle index 10b45e5fbfc..5e8494b41d8 100644 --- a/build.gradle +++ b/build.gradle @@ -5,6 +5,7 @@ plugins { id 'org.jetbrains.kotlin.jvm' version '1.3.72' apply false id 'org.jetbrains.dokka' version '0.10.1' apply false id 'org.asciidoctor.jvm.convert' version '2.4.0' + id 'org.asciidoctor.jvm.pdf' version '2.4.0' id 'de.undercouch.download' version '4.1.1' id "io.freefair.aspectj" version '4.1.6' apply false id 'com.gradle.build-scan' version '3.2' diff --git a/gradle/docs.gradle b/gradle/docs.gradle index 43e7e02959d..e64d5af08a4 100644 --- a/gradle/docs.gradle +++ b/gradle/docs.gradle @@ -130,45 +130,57 @@ asciidoctorj { } } fatalWarnings ".*" + options doctype: 'book', eruby: 'erubis' + attributes([ + icons: 'font', + idprefix: '', + idseparator: '-', + docinfo: 'shared', + revnumber: project.version, + sectanchors: '', + sectnums: '', + 'source-highlighter': 'highlight.js', + highlightjsdir: 'js/highlight', + 'highlightjs-theme': 'github', // 'googlecode', + stylesdir: 'css/', + stylesheet: 'stylesheet.css', + 'spring-version': project.version + ]) } /** - * Produce the Spring Framework Reference documentation - * from "src/docs/asciidoc" into "build/asciidoc/html5" + * Generate the Spring Framework Reference documentation from "src/docs/asciidoc" + * in "build/docs/ref-docs/html5". */ asciidoctor { + dependsOn asciidoctorPdf baseDirFollowsSourceDir() configurations 'asciidoctorExt' sources { include '*.adoc' } - outputDir "$buildDir/docs/ref-docs/" + outputDir "$buildDir/docs/ref-docs/html5" + logDocuments = true resources { from(sourceDir) { include 'images/*', 'css/**', 'js/**' } from extractDocResources } - logDocuments = true - outputOptions { - backends = ["html5", "pdf"] +} + +/** + * Generate the Spring Framework Reference documentation from "src/docs/asciidoc" + * in "build/docs/ref-docs/pdf". + */ +asciidoctorPdf { + baseDirFollowsSourceDir() + configurations 'asciidoctorExt' + sources { + include '*.adoc' } - options doctype: 'book', eruby: 'erubis' - attributes([ - icons: 'font', - idprefix: '', - idseparator: '-', - docinfo: 'shared', - revnumber: project.version, - sectanchors: '', - sectnums: '', - 'source-highlighter': 'highlight.js', - highlightjsdir: 'js/highlight', - 'highlightjs-theme': 'github', // 'googlecode', - stylesdir: 'css/', - stylesheet: 'stylesheet.css', - 'spring-version': project.version - ]) + outputDir "$buildDir/docs/ref-docs/pdf" + logDocuments = true } /** From a5a4960859d0d15bfe677be86291cd1e59047436 Mon Sep 17 00:00:00 2001 From: Sam Brannen Date: Sat, 19 Sep 2020 14:54:27 +0200 Subject: [PATCH 2/3] Do not generate reference docs for include-files Prior to this commit, the Asciidoctor Gradle tasks generated top-level HTML and PDF documents for AsciiDoc files that are included in other top-level documents. This causes slower builds and results in each include-file being published twice: 1) inline in the including document (as intended) 2) as a top-level document but missing surrounding context (unintended) The reason these include-files are generated as top-level documents is that the asciidoctor and asciidoctorPdf Gradle tasks are configured to use '*.adoc' as the input source files. This commit addresses this issue by moving the following include-files to new subdirectories. Locating the include-files in the subdirectories causes them to be ignored in the '*.adoc' pattern used to identify input source files. - data-access-appendix.adoc -> data-access/data-access-appendix.adoc - integration-appendix.adoc -> integration/integration-appendix.adoc - testing-webtestclient.adoc -> testing/testing-webtestclient.adoc Closes gh-25783 --- src/docs/asciidoc/data-access.adoc | 2 +- src/docs/asciidoc/{ => data-access}/data-access-appendix.adoc | 0 src/docs/asciidoc/integration.adoc | 2 +- src/docs/asciidoc/{ => integration}/integration-appendix.adoc | 0 src/docs/asciidoc/testing.adoc | 2 +- src/docs/asciidoc/{ => testing}/testing-webtestclient.adoc | 0 6 files changed, 3 insertions(+), 3 deletions(-) rename src/docs/asciidoc/{ => data-access}/data-access-appendix.adoc (100%) rename src/docs/asciidoc/{ => integration}/integration-appendix.adoc (100%) rename src/docs/asciidoc/{ => testing}/testing-webtestclient.adoc (100%) diff --git a/src/docs/asciidoc/data-access.adoc b/src/docs/asciidoc/data-access.adoc index 62e41acb32d..056f5e813f7 100644 --- a/src/docs/asciidoc/data-access.adoc +++ b/src/docs/asciidoc/data-access.adoc @@ -8378,4 +8378,4 @@ within Web services. -include::data-access-appendix.adoc[leveloffset=+1] +include::data-access/data-access-appendix.adoc[leveloffset=+1] diff --git a/src/docs/asciidoc/data-access-appendix.adoc b/src/docs/asciidoc/data-access/data-access-appendix.adoc similarity index 100% rename from src/docs/asciidoc/data-access-appendix.adoc rename to src/docs/asciidoc/data-access/data-access-appendix.adoc diff --git a/src/docs/asciidoc/integration.adoc b/src/docs/asciidoc/integration.adoc index 1b905d5d6cf..d8d346633ec 100644 --- a/src/docs/asciidoc/integration.adoc +++ b/src/docs/asciidoc/integration.adoc @@ -7873,4 +7873,4 @@ directly through the backing cache (when configuring it) or through its native A -include::integration-appendix.adoc[leveloffset=+1] +include::integration/integration-appendix.adoc[leveloffset=+1] diff --git a/src/docs/asciidoc/integration-appendix.adoc b/src/docs/asciidoc/integration/integration-appendix.adoc similarity index 100% rename from src/docs/asciidoc/integration-appendix.adoc rename to src/docs/asciidoc/integration/integration-appendix.adoc diff --git a/src/docs/asciidoc/testing.adoc b/src/docs/asciidoc/testing.adoc index d9b78d55264..eb164ffc027 100644 --- a/src/docs/asciidoc/testing.adoc +++ b/src/docs/asciidoc/testing.adoc @@ -8494,7 +8494,7 @@ Spring MVC Test's own tests include https://github.com/spring-projects/spring-framework/tree/master/spring-test/src/test/java/org/springframework/test/web/client/samples[example tests] of client-side REST tests. -include::testing-webtestclient.adoc[leveloffset=+2] +include::testing/testing-webtestclient.adoc[leveloffset=+2] diff --git a/src/docs/asciidoc/testing-webtestclient.adoc b/src/docs/asciidoc/testing/testing-webtestclient.adoc similarity index 100% rename from src/docs/asciidoc/testing-webtestclient.adoc rename to src/docs/asciidoc/testing/testing-webtestclient.adoc From a532c527dd47fef9e92e1afb8945d05257bfc3f0 Mon Sep 17 00:00:00 2001 From: Brian Clozel Date: Thu, 24 Sep 2020 17:49:37 +0200 Subject: [PATCH 3/3] Fix missing reference doc from docs archive Prior to this commit, the `docsZip` task would not reference the new output locations for the `asciidoctor` and `asciidoctorPdf` tasks. This results with missing reference docs in the docs zip. This commit updates the input locations of the Zip task to include the produced reference docs. Fixes gh-25783 --- gradle/docs.gradle | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/gradle/docs.gradle b/gradle/docs.gradle index e64d5af08a4..23d0d24b613 100644 --- a/gradle/docs.gradle +++ b/gradle/docs.gradle @@ -153,7 +153,6 @@ asciidoctorj { * in "build/docs/ref-docs/html5". */ asciidoctor { - dependsOn asciidoctorPdf baseDirFollowsSourceDir() configurations 'asciidoctorExt' sources { @@ -186,7 +185,7 @@ asciidoctorPdf { /** * Zip all docs (API and reference) into a single archive */ -task docsZip(type: Zip, dependsOn: ['api', 'asciidoctor', 'dokka']) { +task docsZip(type: Zip, dependsOn: ['api', 'asciidoctor', 'asciidoctorPdf', 'dokka']) { group = "Distribution" description = "Builds -${archiveClassifier} archive containing api and reference " + "for deployment at https://docs.spring.io/spring-framework/docs." @@ -199,10 +198,10 @@ task docsZip(type: Zip, dependsOn: ['api', 'asciidoctor', 'dokka']) { from (api) { into "javadoc-api" } - from ("$asciidoctor.outputDir/html5") { + from ("$asciidoctor.outputDir") { into "spring-framework-reference" } - from ("$asciidoctor.outputDir/pdf") { + from ("$asciidoctorPdf.outputDir") { into "spring-framework-reference/pdf" } from (dokka) {