Render reference documentation with Asciidoctor

This commit removes docbook from the documentation toolchain and
instead makes use of asciidoctor to render the reference documentation
in HTML and PDF formats.

The main Gradle build has been refactored with the documentation tasks
and sniffer tasks extracted to their own gradle file in the "gradle"
folder.

A new asciidoctor Spring theme is also used to render the HTML5 backend.

Issue: SPR-14997

Author: bclozel

build.gradle

@@ -6,8 +6,10 @@ buildscript {
 		classpath("io.spring.gradle:dependency-management-plugin:1.0.0.RELEASE")
 		classpath("io.spring.gradle:propdeps-plugin:0.0.8")
 		classpath("io.spring.gradle:docbook-reference-plugin:0.3.1")
-		classpath("org.asciidoctor:asciidoctor-gradle-plugin:1.5.3")
 		classpath("org.jetbrains.kotlin:kotlin-gradle-plugin:1.1.1")
+		classpath("org.asciidoctor:asciidoctor-gradle-plugin:1.5.3")
+		classpath("org.asciidoctor:asciidoctorj-pdf:1.5.0-alpha.14")
+		classpath("org.asciidoctor:asciidoctorj-epub3:1.5.0-alpha.6")
 	}
 }
 
@@ -86,7 +88,6 @@ configure(allprojects) { project ->
 	ext.servletVersion         = "3.1.0"
 	ext.slf4jVersion           = "1.7.25"
 	ext.snakeyamlVersion       = "1.18"
-	ext.snifferVersion         = "1.15"
 	ext.testngVersion          = "6.11"
 	ext.tiles3Version          = "3.0.7"
 	ext.tomcatVersion          = "8.5.12"
@@ -104,6 +105,7 @@ configure(allprojects) { project ->
 	apply plugin: "java"
 	apply plugin: "test-source-set-dependencies"
 	apply from: "${gradleScriptDir}/ide.gradle"
+	apply from: "${gradleScriptDir}/sniffer.gradle"
 
 	// Kotlin compiler does not support JDK 9 yet, see https://youtrack.jetbrains.com/issue/KT-14988
 	if (!JavaVersion.current().java9Compatible) {
@@ -119,11 +121,6 @@ configure(allprojects) { project ->
 		}
 	}
 
-	configurations {
-		sniffer
-		javaApiSignature
-	}
-
 	configurations.all {
 		// Check for updates every build
 		resolutionStrategy.cacheChangingModulesFor 0, 'seconds'
@@ -192,44 +189,6 @@ configure(allprojects) { project ->
 		testCompile("org.hamcrest:hamcrest-all:${hamcrestVersion}")
 		testRuntime("org.apache.logging.log4j:log4j-core:${log4jVersion}")
 		testRuntime("org.apache.logging.log4j:log4j-jcl:${log4jVersion}")
-
-		sniffer("org.codehaus.mojo:animal-sniffer-ant-tasks:${snifferVersion}")
-		javaApiSignature("org.codehaus.mojo.signature:java18:1.0@signature")
-	}
-
-	task copyJavaApiSignature(type: Copy) {
-		ext.to = file("$buildDir/javaApiSignature/")
-		description "Copy the resolved Animal Sniffer signature dependency artifact to a known location and name"
-		from configurations.javaApiSignature
-		into to
-		rename '.*signature', 'javaApi.signature'
-	}
-
-	task sniff {
-		group = "Verification"
-		description = "Checks the Java API signatures"
-
-		dependsOn compileJava
-		dependsOn copyJavaApiSignature
-
-		inputs.dir sourceSets.main.output.classesDir
-		inputs.dir copyJavaApiSignature.to
-
-		doLast {
-			ant.taskdef(
-				name: 'animalSniffer',
-				classname: 'org.codehaus.mojo.animal_sniffer.ant.CheckSignatureTask',
-				classpath: configurations.sniffer.asPath
-			)
-
-			// TODO: Animal Sniffer currently chokes on optional JDK 9 bytecode in AspectJ 1.9 beta 5
-			// ant.animalSniffer(
-			// 		signature: "$buildDir/javaApiSignature/javaApi.signature",
-			// 		classpath: sourceSets.main.compileClasspath.asPath) {
-			// 	path(path: sourceSets.main.output.classesDir)
-			// 	annotation(className: "org.springframework.lang.UsesSunHttpServer")
-			// }
-		}
 	}
 
 	ext.javadocLinks = [
@@ -1240,13 +1199,11 @@ sonarqube {
 configure(rootProject) {
 	description = "Spring Framework"
 
-	apply plugin: "org.asciidoctor.convert"
-	apply plugin: "docbook-reference"
 	apply plugin: "groovy"
 	apply plugin: "io.spring.dependency-management"
-
 	// apply plugin: "detect-split-packages"
 	apply from: "${gradleScriptDir}/jdiff.gradle"
+	apply from: "${gradleScriptDir}/docs.gradle"
 
 	dependencyManagement {
 		imports {
@@ -1258,25 +1215,6 @@ configure(rootProject) {
 		applyMavenExclusions = false
 	}
 
-	asciidoctor {
-		sourceDir project.file('src/asciidoc')
-		separateOutputDirs = false
-		backends = ['docbook']
-		options doctype: 'book', eruby: 'erubis'
-		attributes 'spring-version': project.version, 'revnumber': project.version, 'docinfo': ""
-	}
-
-	reference {
-		sourceDir = asciidoctor.outputDir
-		pdfFilename = "spring-framework-reference.pdf"
-		epubFilename = "spring-framework-reference.epub"
-		expandPlaceholders = ""
-	}
-
-	afterEvaluate {
-		tasks.findAll { it.name.startsWith("reference") }.each{ it.dependsOn.add("asciidoctor") }
-	}
-
 	// TODO: DetectSplitPackagesPlugin fails in line 154 due to method not found on java.io.File.
 	// TODO: Possibly related to user rights or OS differences; passes on local Windows machine.
 	// detectSplitPackages {
@@ -1305,159 +1243,6 @@ configure(rootProject) {
 		testCompile("org.hsqldb:hsqldb:${hsqldbVersion}")
 	}
 
-	task api(type: Javadoc) {
-		group = "Documentation"
-		description = "Generates aggregated Javadoc API documentation."
-		title = "${rootProject.description} ${version} API"
-
-		dependsOn {
-			subprojects.collect {
-				it.tasks.getByName("jar")
-			}
-		}
-		options.memberLevel = org.gradle.external.javadoc.JavadocMemberLevel.PROTECTED
-		options.author = true
-		options.header = rootProject.description
-		options.overview = "src/api/overview.html"
-		options.stylesheetFile = file("src/api/stylesheet.css")
-		options.splitIndex = true
-		options.links(project.ext.javadocLinks)
-		options.addStringOption('Xdoclint:none', '-quiet')
-
-		source subprojects.collect { project ->
-			project.sourceSets.main.allJava
-		}
-
-		maxMemory = "1024m"
-		destinationDir = new File(buildDir, "api")
-
-		doFirst {
-			classpath = files(
-				// Ensure the javadoc process can resolve types compiled from .aj sources
-				project(":spring-aspects").sourceSets.main.output
-			)
-			classpath += files(subprojects.collect { it.sourceSets.main.compileClasspath })
-		}
-	}
-
-	task docsZip(type: Zip, dependsOn: 'reference') {
-		group = "Distribution"
-		baseName = "spring-framework"
-		classifier = "docs"
-		description = "Builds -${classifier} archive containing api and reference " +
-			"for deployment at http://static.springframework.org/spring-framework/docs."
-
-		from("src/dist") {
-			include "changelog.txt"
-		}
-
-		from (api) {
-			into "javadoc-api"
-		}
-
-		from (reference) {
-			into "spring-framework-reference"
-		}
-	}
-
-	task schemaZip(type: Zip) {
-		group = "Distribution"
-		baseName = "spring-framework"
-		classifier = "schema"
-		description = "Builds -${classifier} archive containing all " +
-			"XSDs for deployment at http://springframework.org/schema."
-		duplicatesStrategy 'exclude'
-		moduleProjects.each { subproject ->
-			def Properties schemas = new Properties();
-
-			subproject.sourceSets.main.resources.find {
-				it.path.endsWith("META-INF/spring.schemas")
-			}?.withInputStream { schemas.load(it) }
-
-			for (def key : schemas.keySet()) {
-				def shortName = key.replaceAll(/http.*schema.(.*).spring-.*/, '$1')
-				assert shortName != key
-				File xsdFile = subproject.sourceSets.main.resources.find {
-					it.path.endsWith(schemas.get(key))
-				}
-				assert xsdFile != null
-				into (shortName) {
-					from xsdFile.path
-				}
-			}
-		}
-	}
-
-	task distZip(type: Zip, dependsOn: [docsZip, schemaZip]) {
-		group = "Distribution"
-		baseName = "spring-framework"
-		classifier = "dist"
-		description = "Builds -${classifier} archive, containing all jars and docs, " +
-			"suitable for community download page."
-
-		ext.baseDir = "${baseName}-${project.version}";
-
-		from("src/dist") {
-			include "readme.txt"
-			include "license.txt"
-			include "notice.txt"
-			into "${baseDir}"
-			expand(copyright: new Date().format("yyyy"), version: project.version)
-		}
-
-		from(zipTree(docsZip.archivePath)) {
-			into "${baseDir}/docs"
-		}
-
-		from(zipTree(schemaZip.archivePath)) {
-			into "${baseDir}/schema"
-		}
-
-		moduleProjects.each { subproject ->
-			into ("${baseDir}/libs") {
-				from subproject.jar
-				if (subproject.tasks.findByPath("sourcesJar")) {
-					from subproject.sourcesJar
-				}
-				if (subproject.tasks.findByPath("javadocJar")) {
-					from subproject.javadocJar
-				}
-			}
-		}
-	}
-
-	// Create a distribution that contains all dependencies (required and optional).
-	// Not published by default; only for use when building from source.
-	task depsZip(type: Zip, dependsOn: distZip) { zipTask ->
-		group = "Distribution"
-		baseName = "spring-framework"
-		classifier = "dist-with-deps"
-		description = "Builds -${classifier} archive, containing everything " +
-			"in the -${distZip.classifier} archive plus all runtime dependencies."
-
-		from zipTree(distZip.archivePath)
-
-		gradle.taskGraph.whenReady { taskGraph ->
-			if (taskGraph.hasTask(":${zipTask.name}")) {
-				def projectNames = rootProject.subprojects*.name
-				def artifacts = new HashSet()
-				subprojects.each { subproject ->
-					(subproject.configurations.runtime.resolvedConfiguration.resolvedArtifacts +
-					subproject.configurations.optional.resolvedConfiguration.resolvedArtifacts).each { artifact ->
-						def dependency = artifact.moduleVersion.id
-						if (!projectNames.contains(dependency.name)) {
-							artifacts << artifact.file
-						}
-					}
-				}
-
-				zipTask.from(artifacts) {
-					into "${distZip.baseDir}/deps"
-				}
-			}
-		}
-	}
-
 	artifacts {
 		archives docsZip
 		archives schemaZip
@@ -1497,22 +1282,6 @@ configure(project(':spring-core')) {
 	}
 }
 
-/*
- * Copyright 2002-2016 the original author or authors.
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- *      http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
-
 /*
  * Support publication of artifacts versioned by topic branch.
  * CI builds supply `-P BRANCH_NAME=<TOPIC>` to gradle at build time.