Migrate documentation to asciidoctor

This commit migrates to asciidoctor to ease writing documentation.

Issues: SPR-10960

.gitignore

@@ -20,6 +20,7 @@ activemq-data/
 /build
 buildSrc/build
 /spring-*/build
+/src/asciidoc/build
 target/
 
 # Eclipse artifacts, including WTP generated manifests

CONTRIBUTING-DOCUMENTATION.adoc

@@ -0,0 +1,28 @@
+= How to contribute to the reference
+
+The Spring reference now uses http://asciidoctor.org/[asciidoctor]. This document describes how to contribute documentation updates to the Spring reference.
+
+== Building with Gradle
+
+You can build the documentation using gradle using the `asciidoc` task. For example, from the project root execute the following command:
+
+  gradlew asciidoc
+
+the output will be available at `spring-framework/build/asciidoc/index.html`
+
+== Live editing
+
+One of the nice features about using asciidoctor is the support for live editing.
+
+You will find a Guardfile already present at `spring-framework/src/asciidoc/Guardfile`. Then ensure to follow the setup instructions within the http://asciidoctor.org/docs/editing-asciidoc-with-live-preview/[Editing AsciiDoc with Live Preview] document.
+
+When running `guard start` within the `src/asciidoc/` folder, any changes to the `src/asciidoc/index.adoc` file will automatically be written at `src/asciidoc/build/index.html`.
+
+== Documentation notes
+
+Some notes on documentation
+
+* It is important to keep whitespaces to a minimum to make it simple to edit files. This means use an editor with line wrapping rather than manually inserting hard returns.
+* http://asciidoctor.org/docs/asciidoc-syntax-quick-reference/[Asciidoctor Quick Reference]
+* http://asciidoctor.org/docs/user-manual/[Asciidoctor Manual]
+* http://asciidoctor.org/docs/asciidoc-writers-guide/[Asciidoctor Writers Guide]

build.gradle

@@ -4,7 +4,7 @@ buildscript {
 	}
 	dependencies {
 		classpath("org.springframework.build.gradle:propdeps-plugin:0.0.4")
-		classpath("org.springframework.build.gradle:docbook-reference-plugin:0.2.7")
+		classpath("org.asciidoctor:asciidoctor-gradle-plugin:0.7.0")
 	}
 }
 
@@ -874,14 +874,28 @@ project("spring-aspects") {
 configure(rootProject) {
 	description = "Spring Framework"
 
-	apply plugin: "docbook-reference"
+    apply plugin: "asciidoctor"
 	apply plugin: "groovy"
+
 	// apply plugin: "detect-split-packages"
 	apply from: "${gradleScriptDir}/jdiff.gradle"
 
-	reference {
-		sourceDir = file("src/reference/docbook")
-		pdfFilename = "spring-framework-reference.pdf"
+	asciidoctor {
+		options = [
+				eruby: 'erubis',
+				attributes: [
+						copycss : '',
+						icons : 'font',
+						'source-highlighter': 'prettify',
+						sectanchors : '',
+						toc2: '',
+						idprefix: '',
+						idseparator: '-',
+						doctype: 'book',
+						'spring-version' : project.version,
+						revnumber : project.version
+				]
+		]
 	}
 
 	// TODO: DetectSplitPackagesPlugin fails in line 154 due to method not found on java.io.File.
@@ -953,7 +967,7 @@ configure(rootProject) {
 		}
 	}
 
-	task docsZip(type: Zip) {
+	task docsZip(type: Zip, dependsOn: 'asciidoctor') {
 		group = "Distribution"
 		baseName = "spring-framework"
 		classifier = "docs"
@@ -968,8 +982,10 @@ configure(rootProject) {
 			into "javadoc-api"
 		}
 
-		from (reference) {
-			into "spring-framework-reference"
+		from (asciidoctor.outputDir) {
+            exclude "build"
+            exclude "Guardfile"
+			into "spring-framework-reference/htmlsingle"
 		}
 	}
 

src/asciidoc/Guardfile

@@ -0,0 +1,16 @@
+require 'asciidoctor'
+require 'erb'
+require 'fileutils'
+
+FileUtils.mkdir_p('build')
+FileUtils.cp_r('images','build')
+
+guard 'shell' do
+  watch(/^.*\.adoc$/) {|m|
+    Asciidoctor.render_file(m[0], :to_dir => "build", :safe => Asciidoctor::SafeMode::UNSAFE, :attributes=> {'idprefix' => '', 'idseparator' => '-', 'copycss' => '', 'icons' => 'font', 'source-highlighter' => 'prettify', 'sectanchors' => '', 'doctype' => 'book','toc2' => '', 'spring-version' => '4.0.0.BUILD-SNAPSHOT', 'revnumber' => '4.0.0.BUILD-SNAPSHOT' })
+  }
+end
+
+guard 'livereload' do
+  watch(%r{build/.+\.(css|js|html)$})
+end