AsciiDoc content & config improvements

- upgrade Asciidoctor Gradle plugin to 1.5.2
- upgrade Gradle to 2.2.1
- fix header in index.asc
- use project version in header
- switch README to AsciiDoc
- fix broken callout number

README.adoc

@@ -0,0 +1,20 @@
+= Serenity BDD Documentation
+
+This project contains the main Serenity BDD documentation.
+The documentation is broken up into chapters, so many people can contribute simultaneously.
+
+== Building and contributing
+
+The Serenity documentation is written in Asciidoc.
+The build uses Gradle and Asciidoctor.
+You can generate the documentation by running the `asciidoctor` task:
+
+ $ gradle clean asciidoctor
+
+The documentation is generated in [path]_build/asciidoc_.
+
+The master document is [path]_index.asc_.
+All of the chapters are included into this document.
+
+All of the source code in the documentation is included as snippets from the sample projects in the [path]_src/sample_ directory.
+Look in [path]_src/ascidoc/first-steps.asc_ to see an example of how this is done.

build.gradle

@@ -4,13 +4,18 @@ buildscript {
     }
 
     dependencies {
-        classpath 'org.asciidoctor:asciidoctor-gradle-plugin:1.5.0'
+        classpath 'org.asciidoctor:asciidoctor-gradle-plugin:1.5.2'
     }
 }
 
-apply plugin: 'org.asciidoctor.gradle.asciidoctor'
+apply plugin: 'org.asciidoctor.convert'
 
-version="1.0.1"
+version='1.0.1.1'
 
 asciidoctor {
-}
+  sourceDir 'src/asciidoc'
+  sources {
+    include 'index.asc'
+  }
+  separateOutputDirs false
+}

gradle/wrapper/gradle-wrapper.properties

@@ -3,4 +3,4 @@ distributionBase=GRADLE_USER_HOME
 distributionPath=wrapper/dists
 zipStoreBase=GRADLE_USER_HOME
 zipStorePath=wrapper/dists
-distributionUrl=https\://services.gradle.org/distributions/gradle-2.1-bin.zip
+distributionUrl=https\://services.gradle.org/distributions/gradle-2.2.1-bin.zip

src/asciidoc/index.asc

@@ -1,10 +1,8 @@
-The Serenity Reference Manual
-=============================
-Version 1.0.1.1
-John Ferguson Smart @wakaleo
+= The Serenity Reference Manual
+John Ferguson Smart <https://twitter.com/wakaleo[@wakaleo]>
+ifdef::project-version[:revnumber: {project-version}]
 :description: Comprehensive Reference manual for the Serenity BDD living documentation tool
 :lang: en
-:encoding: 'iso-8859-1'
 :keywords: serenity-bdd, bdd, reference, learn, how to 
 :doctype: book
 :compat-mode:

src/samples/junit-quick-start/src/test/java/net/serenitybdd/samples/junit/features/searching/WhenSearchingOnGoogle.java

@@ -29,7 +29,7 @@ public class WhenSearchingOnGoogle {
 
     @Test
     public void shouldInstantiateAWebDriverInstanceForAWebTest() {
-        driver.get("http://www.google.com");                                //<3>
+        driver.get("http://www.google.com");                                //<2>
 
         driver.findElement(By.name("q")).sendKeys("firefly", Keys.ENTER);