Merge pull request #310 from Gerrit Meier

* gh-310:
  Polish contribution and rework to use default attribute rather than macro
  Provide a default output directory for snippets based on build tool

build.gradle

@@ -67,6 +67,7 @@ subprojects {
 			dependency 'javax.servlet:javax.servlet-api:3.1.0'
 			dependency 'javax.validation:validation-api:1.1.0.Final'
 			dependency 'junit:junit:4.12'
+			dependency 'org.asciidoctor:asciidoctorj:1.5.3.1'
 			dependency 'org.hamcrest:hamcrest-core:1.3'
 			dependency 'org.hamcrest:hamcrest-library:1.3'
 			dependency 'org.hibernate:hibernate-validator:5.2.2.Final'

docs/src/docs/asciidoc/getting-started.adoc

@@ -94,13 +94,9 @@ the configuration are described below.
 		<scope>test</scope>
 	</dependency>
 
-	<properties> <2>
-		<snippetsDirectory>${project.build.directory}/generated-snippets</snippetsDirectory>
-	</properties>
-
 	<build>
 		<plugins>
-			<plugin> <3>
+			<plugin> <2>
 				<groupId>org.apache.maven.plugins</groupId>
 				<artifactId>maven-surefire-plugin</artifactId>
 				<configuration>
@@ -109,26 +105,30 @@ the configuration are described below.
 					</includes>
 				</configuration>
 			</plugin>
-			<plugin> <4>
+			<plugin> <3>
 				<groupId>org.asciidoctor</groupId>
 				<artifactId>asciidoctor-maven-plugin</artifactId>
-				<version>1.5.2</version>
+				<version>1.5.3</version>
 				<executions>
 					<execution>
 						<id>generate-docs</id>
-						<phase>prepare-package</phase> <6>
+						<phase>prepare-package</phase> <4>
 						<goals>
 							<goal>process-asciidoc</goal>
 						</goals>
 						<configuration>
 							<backend>html</backend>
 							<doctype>book</doctype>
-							<attributes>
-								<snippets>${snippetsDirectory}</snippets> <5>
-							</attributes>
 						</configuration>
 					</execution>
 				</executions>
+				<dependencies>
+					<dependency> <5>
+						<groupId>org.springframework.restdocs</groupId>
+						<artifactId>spring-restdocs-asciidoctor</artifactId>
+						<version>{project-version}</version>
+					</dependency>
+				</dependencies>
 			</plugin>
 		</plugins>
 	</build>
@@ -136,49 +136,50 @@ the configuration are described below.
 <1> Add a dependency on `spring-restdocs-mockmvc` in the `test` scope. If you want to use
 	REST Assured rather than MockMvc, add a dependency on `spring-restdocs-restassured`
 	instead.
-<2> Configure a property to define the output location for generated snippets.
-<3> Add the SureFire plugin and configure it to include files whose names end with
+<2> Add the SureFire plugin and configure it to include files whose names end with
 	`Documentation.java`.
-<4> Add the Asciidoctor plugin
-<5> Define an attribute named `snippets` that can be used when including the generated
-	snippets in your documentation.
-<6> Using `prepare-package` allows the documentation to be
+<3> Add the Asciidoctor plugin.
+<4> Using `prepare-package` allows the documentation to be
 	<<getting-started-build-configuration-maven-packaging, included in the package>>.
+<5> Add `spring-restdocs-asciidoctor` as a dependency of the Asciidoctor plugin. This
+	will automatically configure the `snippets` attribute for use in your `.adoc` files to
+	point to `target/generated-snippets`.
 
 [source,groovy,indent=0,subs="verbatim,attributes",role="secondary"]
 .Gradle
 ----
 	plugins { <1>
-		id "org.asciidoctor.convert" version "1.5.2"
+		id "org.asciidoctor.convert" version "1.5.3"
 	}
 
-	dependencies { <2>
-		testCompile 'org.springframework.restdocs:spring-restdocs-mockmvc:{project-version}'
+	dependencies {
+		asciidoctor 'org.springframework.restdocs:spring-restdocs-asciidoctor:{project-version}' <2>
+		testCompile 'org.springframework.restdocs:spring-restdocs-mockmvc:{project-version}' <3>
 	}
 
-	ext { <3>
+	ext { <4>
 		snippetsDir = file('build/generated-snippets')
 	}
 
-	test { <4>
+	test { <5>
 		outputs.dir snippetsDir
 	}
 
-	asciidoctor { <5>
-		attributes 'snippets': snippetsDir <6>
+	asciidoctor { <6>
 		inputs.dir snippetsDir <7>
 		dependsOn test <8>
 	}
 ----
 <1> Apply the Asciidoctor plugin.
-<2> Add a dependency on `spring-restdocs-mockmvc` in the `testCompile` configuration. If
+<2> Add a dependency on `spring-restdocs-asciidoctor` in the `asciidoctor` configuration.
+	This will automatically configure the `snippets` attribute for use in your `.adoc`
+	files to point to `build/generated-snippets`.
+<3> Add a dependency on `spring-restdocs-mockmvc` in the `testCompile` configuration. If
 	you want to use REST Assured rather than MockMvc, add a dependency on
 	`spring-restdocs-restassured` instead.
-<3> Configure a property to define the output location for generated snippets.
-<4> Configure the `test` task to add the snippets directory as an output.
-<5> Configure the `asciidoctor` task
-<6> Define an attribute named `snippets` that can be used when including the generated
-	snippets in your documentation.
+<4> Configure a property to define the output location for generated snippets.
+<5> Configure the `test` task to add the snippets directory as an output.
+<6> Configure the `asciidoctor` task
 <7> Configure the snippets directory as an input.
 <8> Make the task depend on the test task so that the tests are run before the
 	documentation is created.
@@ -271,28 +272,38 @@ are also supported although slightly more setup is required.
 ===== Setting up your JUnit tests
 
 When using JUnit, the first step in generating documentation snippets is to declare a
-`public` `JUnitRestDocumentation` field that's annotated as a JUnit `@Rule`. The
-`JUnitRestDocumentation` rule is configured with the output directory into which generated
-snippets should be written. This output directory should match the snippets directory that
-you have configured in your `build.gradle` or `pom.xml` file.
+`public` `JUnitRestDocumentation` field that's annotated as a JUnit `@Rule`.
 
-For Maven (`pom.xml`) that will typically be `target/generated-snippets` and for
-Gradle (`build.gradle`) it will typically be `build/generated-snippets`:
 
-[source,java,indent=0,role="primary"]
-.Maven
+[source,java,indent=0]
 ----
 @Rule
-public JUnitRestDocumentation restDocumentation =
-		new JUnitRestDocumentation("target/generated-snippets");
+public JUnitRestDocumentation restDocumentation = new JUnitRestDocumentation();
 ----
 
-[source,java,indent=0,role="secondary"]
-.Gradle
+
+By default, the `JUnitRestDocumentation` rule is automatically configured with an output
+directory based on your project's build tool:
+
+[cols="2,5"]
+|===
+| Build tool | Output directory
+
+| Maven
+| `target/generated-snippets`
+
+| Gradle
+| `build/generated-snippets`
+
+|===
+
+The default can be overridden by providing an output directory when creating the
+`JUnitRestDocumentation` instance:
+
+[source,java,indent=0]
 ----
 @Rule
-public JUnitRestDocumentation restDocumentation =
-		new JUnitRestDocumentation("build/generated-snippets");
+public JUnitRestDocumentation restDocumentation = new JUnitRestDocumentation("custom");
 ----
 
 Next, provide an `@Before` method to configure MockMvc or REST Assured:
@@ -331,18 +342,9 @@ illustrates the approach.
 The first difference is that `ManualRestDocumentation` should be used in place of
 `JUnitRestDocumentation` and there's no need for the `@Rule` annotation:
 
-[source,java,indent=0,role="primary"]
-.Maven
+[source,java,indent=0]
 ----
-private ManualRestDocumentation restDocumentation =
-		new ManualRestDocumentation("target/generated-snippets");
-----
-
-[source,java,indent=0,role="secondary"]
-.Gradle
-----
-private ManualRestDocumentation restDocumentation =
-		new ManualRestDocumentation("build/generated-snippets");
+private ManualRestDocumentation restDocumentation = new ManualRestDocumentation();
 ----
 
 Secondly, `ManualRestDocumentation.beforeTest(Class, String)`
@@ -441,7 +443,8 @@ the resulting HTML files depends on whether you are using Maven or Gradle:
 The generated snippets can then be included in the manually created Asciidoctor file from
 above using the
 http://asciidoctor.org/docs/asciidoc-syntax-quick-reference/#include-files[include macro].
-The `snippets` attribute specified in the <<getting-started-build-configuration, build
+The `snippets` attribute that is automatically set by `spring-restdocs-asciidoctor`
+configured in the <<getting-started-build-configuration, build
 configuration>> can be used to reference the snippets output directory. For example:
 
 [source,adoc,indent=0]

docs/src/docs/asciidoc/working-with-asciidoctor.adoc

@@ -17,10 +17,11 @@ relevant to Spring REST Docs.
 [[working-with-asciidoctor-including-snippets]]
 === Including snippets
 
-The  http://asciidoctor.org/docs/asciidoc-syntax-quick-reference/#include-files[include
+The http://asciidoctor.org/docs/asciidoc-syntax-quick-reference/#include-files[include
 macro] is used to include generated snippets in your documentation. The `snippets`
-attribute specified in the <<getting-started-build-configuration, build configuration>>
-can be used to reference the snippets output directory, for example:
+attribute that is automatically set by `spring-restdocs-asciidoctor` configured in the
+<<getting-started-build-configuration, build configuration>> can be used to reference the
+snippets output directory. For example:
 
 [source,adoc,indent=0]
 ----

docs/src/test/java/com/example/mockmvc/CustomDefaultSnippets.java

@@ -31,8 +31,7 @@ import static org.springframework.restdocs.mockmvc.MockMvcRestDocumentation.docu
 public class CustomDefaultSnippets {
 
 	@Rule
-	public final JUnitRestDocumentation restDocumentation = new JUnitRestDocumentation(
-			"build");
+	public final JUnitRestDocumentation restDocumentation = new JUnitRestDocumentation();
 
 	@Autowired
 	private WebApplicationContext context;

docs/src/test/java/com/example/mockmvc/CustomEncoding.java

@@ -29,7 +29,7 @@ import static org.springframework.restdocs.mockmvc.MockMvcRestDocumentation.docu
 public class CustomEncoding {
 
 	@Rule
-	public final JUnitRestDocumentation restDocumentation = new JUnitRestDocumentation("build");
+	public final JUnitRestDocumentation restDocumentation = new JUnitRestDocumentation();
 
 	@Autowired
 	private WebApplicationContext context;

docs/src/test/java/com/example/mockmvc/CustomFormat.java

@@ -30,7 +30,7 @@ import static org.springframework.restdocs.mockmvc.MockMvcRestDocumentation.docu
 public class CustomFormat {
 
 	@Rule
-	public final JUnitRestDocumentation restDocumentation = new JUnitRestDocumentation("build");
+	public final JUnitRestDocumentation restDocumentation = new JUnitRestDocumentation();
 
 	@Autowired
 	private WebApplicationContext context;

docs/src/test/java/com/example/mockmvc/CustomUriConfiguration.java

@@ -29,7 +29,7 @@ import static org.springframework.restdocs.mockmvc.MockMvcRestDocumentation.docu
 public class CustomUriConfiguration {
 
 	@Rule
-	public final JUnitRestDocumentation restDocumentation = new JUnitRestDocumentation("build");
+	public final JUnitRestDocumentation restDocumentation = new JUnitRestDocumentation();
 
 	@Autowired
 	private WebApplicationContext context;

docs/src/test/java/com/example/mockmvc/EveryTestPreprocessing.java

@@ -38,8 +38,7 @@ import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.
 public class EveryTestPreprocessing {
 
 	@Rule
-	public final JUnitRestDocumentation restDocumentation = new JUnitRestDocumentation(
-			"target/generated-snippets");
+	public final JUnitRestDocumentation restDocumentation = new JUnitRestDocumentation();
 
 	private WebApplicationContext context;
 

docs/src/test/java/com/example/mockmvc/ExampleApplicationTestNgTests.java

@@ -30,8 +30,7 @@ import static org.springframework.restdocs.mockmvc.MockMvcRestDocumentation.docu
 
 public class ExampleApplicationTestNgTests {
 
-	public final ManualRestDocumentation restDocumentation = new ManualRestDocumentation(
-			"target/generated-snippets");
+	public final ManualRestDocumentation restDocumentation = new ManualRestDocumentation();
 	@SuppressWarnings("unused")
 	// tag::setup[]
 	private MockMvc mockMvc;

docs/src/test/java/com/example/mockmvc/ExampleApplicationTests.java

@@ -30,8 +30,7 @@ import static org.springframework.restdocs.mockmvc.MockMvcRestDocumentation.docu
 public class ExampleApplicationTests {
 
 	@Rule
-	public final JUnitRestDocumentation restDocumentation = new JUnitRestDocumentation(
-			"target/generated-snippets");
+	public final JUnitRestDocumentation restDocumentation = new JUnitRestDocumentation();
 
 	@SuppressWarnings("unused")
 	// tag::setup[]

docs/src/test/java/com/example/mockmvc/ParameterizedOutput.java

@@ -29,7 +29,7 @@ import static org.springframework.restdocs.mockmvc.MockMvcRestDocumentation.docu
 public class ParameterizedOutput {
 
 	@Rule
-	public final JUnitRestDocumentation restDocumentation = new JUnitRestDocumentation("build");
+	public final JUnitRestDocumentation restDocumentation = new JUnitRestDocumentation();
 
 	@SuppressWarnings("unused")
 	private MockMvc mockMvc;

docs/src/test/java/com/example/restassured/CustomDefaultSnippets.java

@@ -29,8 +29,7 @@ import static org.springframework.restdocs.restassured.RestAssuredRestDocumentat
 public class CustomDefaultSnippets {
 
 	@Rule
-	public final JUnitRestDocumentation restDocumentation = new JUnitRestDocumentation(
-			"build");
+	public final JUnitRestDocumentation restDocumentation = new JUnitRestDocumentation();
 
 	@SuppressWarnings("unused")
 	private RequestSpecification spec;

docs/src/test/java/com/example/restassured/CustomEncoding.java

@@ -28,7 +28,7 @@ import static org.springframework.restdocs.restassured.RestAssuredRestDocumentat
 public class CustomEncoding {
 
 	@Rule
-	public final JUnitRestDocumentation restDocumentation = new JUnitRestDocumentation("build");
+	public final JUnitRestDocumentation restDocumentation = new JUnitRestDocumentation();
 
 	@SuppressWarnings("unused")
 	private RequestSpecification spec;

docs/src/test/java/com/example/restassured/CustomFormat.java

@@ -29,7 +29,7 @@ import static org.springframework.restdocs.restassured.RestAssuredRestDocumentat
 public class CustomFormat {
 
 	@Rule
-	public final JUnitRestDocumentation restDocumentation = new JUnitRestDocumentation("build");
+	public final JUnitRestDocumentation restDocumentation = new JUnitRestDocumentation();
 	
 	@SuppressWarnings("unused")
 	private RequestSpecification spec;

docs/src/test/java/com/example/restassured/EveryTestPreprocessing.java

@@ -38,8 +38,7 @@ import static org.springframework.restdocs.restassured.RestAssuredRestDocumentat
 public class EveryTestPreprocessing {
 
 	@Rule
-	public final JUnitRestDocumentation restDocumentation = new JUnitRestDocumentation(
-			"target/generated-snippets");
+	public final JUnitRestDocumentation restDocumentation = new JUnitRestDocumentation();
 
 	// tag::setup[]
 	private RequestSpecification spec;

docs/src/test/java/com/example/restassured/ExampleApplicationTestNgTests.java

@@ -29,8 +29,7 @@ import static org.springframework.restdocs.restassured.RestAssuredRestDocumentat
 
 public class ExampleApplicationTestNgTests {
 
-	private final ManualRestDocumentation restDocumentation = new ManualRestDocumentation(
-			"build/generated-snippets");
+	private final ManualRestDocumentation restDocumentation = new ManualRestDocumentation();
 
 	@SuppressWarnings("unused")
 	// tag::setup[]

docs/src/test/java/com/example/restassured/ExampleApplicationTests.java

@@ -28,8 +28,7 @@ import static org.springframework.restdocs.restassured.RestAssuredRestDocumentat
 public class ExampleApplicationTests {
 
 	@Rule
-	public final JUnitRestDocumentation restDocumentation = new JUnitRestDocumentation(
-			"build/generated-snippets");
+	public final JUnitRestDocumentation restDocumentation = new JUnitRestDocumentation();
 
 	@SuppressWarnings("unused")
 	// tag::setup[]

docs/src/test/java/com/example/restassured/ParameterizedOutput.java

@@ -29,8 +29,7 @@ import static org.springframework.restdocs.restassured.RestAssuredRestDocumentat
 public class ParameterizedOutput {
 
 	@Rule
-	public final JUnitRestDocumentation restDocumentation = new JUnitRestDocumentation(
-			"build/generated-snippets");
+	public final JUnitRestDocumentation restDocumentation = new JUnitRestDocumentation();
 
 	@SuppressWarnings("unused")
 	private RequestSpecification spec;

samples/rest-assured/build.gradle

@@ -37,6 +37,7 @@ dependencies {
 	compile 'org.springframework.boot:spring-boot-starter-web'
 	testCompile 'org.springframework.boot:spring-boot-starter-test'
 	testCompile "org.springframework.restdocs:spring-restdocs-restassured:${project.ext['spring-restdocs.version']}"
+	asciidoctor "org.springframework.restdocs:spring-restdocs-asciidoctor:${project.ext['spring-restdocs.version']}"
 }
 
 test {
@@ -44,7 +45,6 @@ test {
 }
 
 asciidoctor {
-	attributes 'snippets': snippetsDir
 	inputs.dir snippetsDir
 	dependsOn test
 }

samples/rest-assured/src/test/java/com/example/restassured/SampleRestAssuredApplicationTests.java

@@ -42,7 +42,7 @@ import com.jayway.restassured.specification.RequestSpecification;
 public class SampleRestAssuredApplicationTests {
 
 	@Rule
-	public final JUnitRestDocumentation restDocumentation = new JUnitRestDocumentation("build/generated-snippets");
+	public final JUnitRestDocumentation restDocumentation = new JUnitRestDocumentation();
 	
 	private RequestSpecification documentationSpec;
 	

samples/rest-notes-grails/.gitignore

@@ -11,7 +11,4 @@ classes/
 .settings
 .classpath
 gradlew*
-gradle/wrapper
-
-
-src/docs/generated-snippets
+gradle/wrapper

samples/rest-notes-grails/build.gradle

@@ -44,6 +44,7 @@ repositories {
 dependencyManagement {
 	dependencies {
 		dependency "org.springframework.restdocs:spring-restdocs-restassured:$restDocsVersion"
+		dependency "org.springframework.restdocs:spring-restdocs-asciidoctor:$restDocsVersion"
 	}
 	imports {
 		mavenBom "org.grails:grails-bom:$grailsVersion"
@@ -53,6 +54,8 @@ dependencyManagement {
 }
 
 dependencies {
+	asciidoctor "org.springframework.restdocs:spring-restdocs-asciidoctor"
+
 	compile "org.springframework.boot:spring-boot-starter-logging"
 	compile "org.springframework.boot:spring-boot-starter-actuator"
 	compile "org.springframework.boot:spring-boot-autoconfigure"
@@ -85,24 +88,16 @@ task wrapper(type: Wrapper) {
 }
 
 ext {
-	snippetsDir = file('src/docs/generated-snippets')
-}
-
-task cleanTempDirs(type: Delete) {
-	delete fileTree(dir: 'src/docs/generated-snippets')
+	snippetsDir = file('build/generated-snippets')
 }
 
 test {
-	dependsOn cleanTempDirs
 	outputs.dir snippetsDir
 }
 
 asciidoctor {
 	dependsOn integrationTest
 	inputs.dir snippetsDir
-	sourceDir = file('src/docs')
-	separateOutputDirs = false
-	attributes 'snippets': snippetsDir
 }
 
 build.dependsOn asciidoctor

samples/rest-notes-grails/src/integration-test/groovy/com/example/ApiDocumentationSpec.groovy

@@ -45,7 +45,7 @@ import spock.lang.Specification
 class ApiDocumentationSpec extends Specification {
 
 	@Rule
-	JUnitRestDocumentation restDocumentation = new JUnitRestDocumentation('src/docs/generated-snippets')
+	JUnitRestDocumentation restDocumentation = new JUnitRestDocumentation()
 
 	@Value('${local.server.port}')
 	Integer serverPort

samples/rest-notes-slate/src/test/java/com/example/notes/ApiDocumentation.java

@@ -61,7 +61,7 @@ import com.fasterxml.jackson.databind.ObjectMapper;
 public class ApiDocumentation {
 
 	@Rule
-	public final JUnitRestDocumentation restDocumentation = new JUnitRestDocumentation("build/generated-snippets");
+	public final JUnitRestDocumentation restDocumentation = new JUnitRestDocumentation();
 
 	@Autowired
 	private NoteRepository noteRepository;

samples/rest-notes-spring-data-rest/pom.xml

@@ -84,12 +84,16 @@
 						<configuration>
 							<backend>html</backend>
 							<doctype>book</doctype>
-							<attributes>
-								<snippets>${project.build.directory}/generated-snippets</snippets>
-							</attributes>
 						</configuration>
 					</execution>
 				</executions>
+				<dependencies>
+					<dependency>
+						<groupId>org.springframework.restdocs</groupId>
+						<artifactId>spring-restdocs-asciidoctor</artifactId>
+						<version>${spring-restdocs.version}</version>
+					</dependency>
+				</dependencies>
 			</plugin>
 			<plugin>
 				<artifactId>maven-resources-plugin</artifactId>

samples/rest-notes-spring-data-rest/src/test/java/com/example/notes/ApiDocumentation.java

@@ -61,7 +61,7 @@ import com.fasterxml.jackson.databind.ObjectMapper;
 public class ApiDocumentation {
 	
 	@Rule
-	public final JUnitRestDocumentation restDocumentation = new JUnitRestDocumentation("target/generated-snippets");
+	public final JUnitRestDocumentation restDocumentation = new JUnitRestDocumentation();
 
 	@Autowired
 	private NoteRepository noteRepository;

samples/rest-notes-spring-data-rest/src/test/java/com/example/notes/GettingStartedDocumentation.java

@@ -58,7 +58,7 @@ import com.jayway.jsonpath.JsonPath;
 public class GettingStartedDocumentation {
 	
 	@Rule
-	public final JUnitRestDocumentation restDocumentation = new JUnitRestDocumentation("target/generated-snippets");
+	public final JUnitRestDocumentation restDocumentation = new JUnitRestDocumentation();
 
 	@Autowired
 	private ObjectMapper objectMapper;

samples/rest-notes-spring-hateoas/build.gradle

@@ -34,6 +34,8 @@ ext['spring.version']='4.3.1.RELEASE'
 ext['spring-restdocs.version'] = '1.2.0.BUILD-SNAPSHOT'
 
 dependencies {
+	asciidoctor "org.springframework.restdocs:spring-restdocs-asciidoctor:${project.ext['spring-restdocs.version']}"
+
 	compile 'org.springframework.boot:spring-boot-starter-data-jpa'
 	compile 'org.springframework.boot:spring-boot-starter-hateoas'
 
@@ -50,7 +52,6 @@ test {
 }
 
 asciidoctor {
-	attributes 'snippets': snippetsDir
 	inputs.dir snippetsDir
 	dependsOn test
 }

samples/rest-notes-spring-hateoas/src/test/java/com/example/notes/ApiDocumentation.java

@@ -70,7 +70,7 @@ import com.fasterxml.jackson.databind.ObjectMapper;
 public class ApiDocumentation {
 	
 	@Rule
-	public final JUnitRestDocumentation restDocumentation = new JUnitRestDocumentation("build/generated-snippets");
+	public final JUnitRestDocumentation restDocumentation = new JUnitRestDocumentation();
 	
 	private RestDocumentationResultHandler documentationHandler; 
 

samples/rest-notes-spring-hateoas/src/test/java/com/example/notes/GettingStartedDocumentation.java

@@ -61,7 +61,7 @@ import com.jayway.jsonpath.JsonPath;
 public class GettingStartedDocumentation {
 	
 	@Rule
-	public final JUnitRestDocumentation restDocumentation = new JUnitRestDocumentation("build/generated-snippets");
+	public final JUnitRestDocumentation restDocumentation = new JUnitRestDocumentation();
 
 	@Autowired
 	private ObjectMapper objectMapper;

samples/testng/build.gradle

@@ -34,7 +34,10 @@ ext['spring.version']='4.3.1.RELEASE'
 ext['spring-restdocs.version'] = '1.2.0.BUILD-SNAPSHOT'
 
 dependencies {
+	asciidoctor "org.springframework.restdocs:spring-restdocs-asciidoctor:${project.ext['spring-restdocs.version']}"
+
 	compile 'org.springframework.boot:spring-boot-starter-web'
+
 	testCompile('org.springframework:spring-test') {
 		exclude group: 'junit', module: 'junit;'
 	}
@@ -48,7 +51,6 @@ test {
 }
 
 asciidoctor {
-	attributes 'snippets': snippetsDir
 	inputs.dir snippetsDir
 	dependsOn test
 }

samples/testng/src/test/java/com/example/testng/SampleTestNgApplicationTests.java

@@ -39,7 +39,7 @@ import org.testng.annotations.Test;
 @WebAppConfiguration
 public class SampleTestNgApplicationTests extends AbstractTestNGSpringContextTests {
 
-	private final ManualRestDocumentation restDocumentation = new ManualRestDocumentation("build/generated-snippets");
+	private final ManualRestDocumentation restDocumentation = new ManualRestDocumentation();
 
 	@Autowired
 	private WebApplicationContext context;

settings.gradle

@@ -1,6 +1,7 @@
 rootProject.name = 'spring-restdocs'
 
 include 'docs'
+include 'spring-restdocs-asciidoctor'
 include 'spring-restdocs-core'
 include 'spring-restdocs-mockmvc'
-include 'spring-restdocs-restassured'
+include 'spring-restdocs-restassured'

spring-restdocs-asciidoctor/build.gradle

@@ -0,0 +1,7 @@
+description = 'Asciidoctor extensions for Spring REST Docs'
+
+dependencies {
+	compileOnly 'org.asciidoctor:asciidoctorj'
+	testCompile 'junit:junit'
+	testCompile 'org.asciidoctor:asciidoctorj'
+}

spring-restdocs-asciidoctor/src/main/java/org/springframework/restdocs/asciidoctor/DefaultAttributesPreprocessor.java

@@ -0,0 +1,43 @@
+/*
+ * Copyright 2014-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.
+ */
+
+package org.springframework.restdocs.asciidoctor;
+
+import java.io.File;
+
+import org.asciidoctor.ast.Document;
+import org.asciidoctor.extension.Preprocessor;
+import org.asciidoctor.extension.PreprocessorReader;
+
+/**
+ * {@link Preprocessor} that sets defaults for REST Docs-related {@link Document}
+ * attributes.
+ *
+ * @author Andy Wilkinson
+ */
+final class DefaultAttributesPreprocessor extends Preprocessor {
+
+	private final SnippetsDirectoryResolver snippetsDirectoryResolver = new SnippetsDirectoryResolver(
+			new File("."));
+
+	@Override
+	public PreprocessorReader process(Document document, PreprocessorReader reader) {
+		document.setAttr("snippets", this.snippetsDirectoryResolver
+				.getSnippetsDirectory(document.getAttributes()), false);
+		return reader;
+	}
+
+}

spring-restdocs-asciidoctor/src/main/java/org/springframework/restdocs/asciidoctor/RestDocsExtensionRegistry.java

@@ -0,0 +1,35 @@
+/*
+ * Copyright 2014-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.
+ */
+
+package org.springframework.restdocs.asciidoctor;
+
+import org.asciidoctor.Asciidoctor;
+import org.asciidoctor.extension.spi.ExtensionRegistry;
+
+/**
+ * Asciidoctor {@link ExtensionRegistry} for Spring REST Docs.
+ *
+ * @author Andy Wilkinson
+ */
+public final class RestDocsExtensionRegistry implements ExtensionRegistry {
+
+	@Override
+	public void register(Asciidoctor asciidoctor) {
+		asciidoctor.javaExtensionRegistry()
+				.preprocessor(new DefaultAttributesPreprocessor());
+	}
+
+}

spring-restdocs-asciidoctor/src/main/java/org/springframework/restdocs/asciidoctor/SnippetsDirectoryResolver.java

@@ -0,0 +1,58 @@
+/*
+ * Copyright 2014-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.
+ */
+
+package org.springframework.restdocs.asciidoctor;
+
+import java.io.File;
+import java.nio.file.Path;
+import java.nio.file.Paths;
+import java.util.Map;
+
+/**
+ * Resolves the directory from which snippets can be read for inclusion in an Asciidoctor
+ * document. The resolved directory is relative to the {@code docdir} of the Asciidoctor
+ * document that it being rendered.
+ *
+ * @author Andy Wilkinson
+ */
+class SnippetsDirectoryResolver {
+
+	private final File root;
+
+	SnippetsDirectoryResolver(File root) {
+		this.root = root;
+	}
+
+	File getSnippetsDirectory(Map<String, Object> attributes) {
+		if (new File(this.root, "pom.xml").exists()) {
+			return getMavenSnippetsDirectory(attributes);
+		}
+		return getGradleSnippetsDirectory(attributes);
+	}
+
+	private File getMavenSnippetsDirectory(Map<String, Object> attributes) {
+		Path rootPath = Paths.get(this.root.getAbsolutePath());
+		Path docDirPath = Paths.get((String) attributes.get("docdir"));
+		Path relativePath = docDirPath.relativize(rootPath);
+		return new File(relativePath.toFile(), "target/generated-snippets");
+	}
+
+	private File getGradleSnippetsDirectory(Map<String, Object> attributes) {
+		return new File((String) attributes.get("projectdir"),
+				"build/generated-snippets");
+	}
+
+}

spring-restdocs-asciidoctor/src/main/resources/META-INF/services/org.asciidoctor.extension.spi.ExtensionRegistry

@@ -0,0 +1 @@
+org.springframework.restdocs.asciidoctor.RestDocsExtensionRegistry

spring-restdocs-asciidoctor/src/test/java/org/springframework/restdocs/asciidoctor/DefaultAttributesPreprocessorTests.java

@@ -0,0 +1,58 @@
+/*
+ * Copyright 2014-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.
+ */
+
+package org.springframework.restdocs.asciidoctor;
+
+import org.asciidoctor.Asciidoctor;
+import org.asciidoctor.Attributes;
+import org.asciidoctor.Options;
+import org.junit.Test;
+
+import static org.hamcrest.CoreMatchers.containsString;
+import static org.junit.Assert.assertThat;
+
+/**
+ * Tests for {@link DefaultAttributesPreprocessor}.
+ *
+ * @author Andy Wilkinson
+ */
+public class DefaultAttributesPreprocessorTests {
+
+	@Test
+	public void snippetsAttributeIsSet() {
+		String converted = Asciidoctor.Factory.create().convert("{snippets}",
+				new Options());
+		assertThat(converted, containsString("build/generated-snippets"));
+	}
+
+	@Test
+	public void snippetsAttributeFromConvertArgumentIsNotOverridden() {
+		Options options = new Options();
+		options.setAttributes(new Attributes("snippets=custom"));
+		String converted = Asciidoctor.Factory.create().convert("{snippets}", options);
+		assertThat(converted, containsString("custom"));
+	}
+
+	@Test
+	public void snippetsAttributeFromDocumentPreambleIsNotOverridden() {
+		Options options = new Options();
+		options.setAttributes(new Attributes("snippets=custom"));
+		String converted = Asciidoctor.Factory.create()
+				.convert(":snippets: custom\n{snippets}", options);
+		assertThat(converted, containsString("custom"));
+	}
+
+}

spring-restdocs-asciidoctor/src/test/java/org/springframework/restdocs/asciidoctor/SnippetsDirectoryResolverTests.java

@@ -0,0 +1,68 @@
+/*
+ * Copyright 2014-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.
+ */
+
+package org.springframework.restdocs.asciidoctor;
+
+import java.io.File;
+import java.io.IOException;
+import java.util.HashMap;
+import java.util.Map;
+
+import org.junit.Rule;
+import org.junit.Test;
+import org.junit.rules.TemporaryFolder;
+
+import static org.hamcrest.CoreMatchers.equalTo;
+import static org.hamcrest.CoreMatchers.is;
+import static org.junit.Assert.assertThat;
+
+/**
+ * Tests for {@link SnippetsDirectoryResolver}.
+ *
+ * @author Andy Wilkinson
+ */
+public class SnippetsDirectoryResolverTests {
+
+	@Rule
+	public TemporaryFolder temporaryFolder = new TemporaryFolder();
+
+	@Test
+	public void mavenProjectsUseTargetGeneratedSnippetsRelativeToDocDir()
+			throws IOException {
+		this.temporaryFolder.newFile("pom.xml");
+		Map<String, Object> attributes = new HashMap<>();
+		attributes.put("docdir",
+				new File(this.temporaryFolder.getRoot(), "src/main/asciidoc")
+						.getAbsolutePath());
+		File snippetsDirectory = new SnippetsDirectoryResolver(
+				this.temporaryFolder.getRoot()).getSnippetsDirectory(attributes);
+		assertThat(snippetsDirectory.isAbsolute(), is(false));
+		assertThat(snippetsDirectory,
+				equalTo(new File("../../../target/generated-snippets")));
+	}
+
+	@Test
+	public void gradleProjectsUseBuildGeneratedSnippetsBeneathProjectDir()
+			throws IOException {
+		Map<String, Object> attributes = new HashMap<>();
+		attributes.put("projectdir", "project/dir");
+		File snippetsDirectory = new SnippetsDirectoryResolver(
+				this.temporaryFolder.getRoot()).getSnippetsDirectory(attributes);
+		assertThat(snippetsDirectory,
+				equalTo(new File("project/dir/build/generated-snippets")));
+	}
+
+}

spring-restdocs-asciidoctor/src/test/resources/sample-snippet.adoc

@@ -0,0 +1,4 @@
+[source,bash]
+----
+$ curl 'http://localhost:8080/' -i -H 'Accept: application/hal+json'
+----

spring-restdocs-core/src/main/java/org/springframework/restdocs/JUnitRestDocumentation.java

@@ -32,6 +32,14 @@ public class JUnitRestDocumentation
 
 	private final ManualRestDocumentation delegate;
 
+	/**
+	 * Creates a new {@code JUnitRestDocumentation} instance that will generate snippets
+	 * to <gradle/maven build path>/generated-snippet.
+	 */
+	public JUnitRestDocumentation() {
+		this.delegate = new ManualRestDocumentation();
+	}
+
 	/**
 	 * Creates a new {@code JUnitRestDocumentation} instance that will generate snippets
 	 * to the given {@code outputDirectory}.

spring-restdocs-core/src/main/java/org/springframework/restdocs/ManualRestDocumentation.java

@@ -35,6 +35,14 @@ public final class ManualRestDocumentation implements RestDocumentationContextPr
 
 	private RestDocumentationContext context;
 
+	/**
+	 * Creates a new {@code ManualRestDocumentation} instance that will generate snippets
+	 * to <gradle/maven build path>/generated-snippet.
+	 */
+	public ManualRestDocumentation() {
+		this(getDefaultOutputDirectory());
+	}
+
 	/**
 	 * Creates a new {@code ManualRestDocumentation} instance that will generate snippets
 	 * to the given {@code outputDirectory}.
@@ -42,7 +50,11 @@ public final class ManualRestDocumentation implements RestDocumentationContextPr
 	 * @param outputDirectory the output directory
 	 */
 	public ManualRestDocumentation(String outputDirectory) {
-		this.outputDirectory = new File(outputDirectory);
+		this(new File(outputDirectory));
+	}
+
+	private ManualRestDocumentation(File outputDirectory) {
+		this.outputDirectory = outputDirectory;
 	}
 
 	/**
@@ -79,4 +91,11 @@ public final class ManualRestDocumentation implements RestDocumentationContextPr
 		return this.context;
 	}
 
+	private static File getDefaultOutputDirectory() {
+		if (new File("pom.xml").exists()) {
+			return new File("target/generated-snippets");
+		}
+		return new File("build/generated-snippets");
+	}
+
 }

spring-restdocs-core/src/main/java/org/springframework/restdocs/RestDocumentation.java

@@ -32,6 +32,14 @@ public class RestDocumentation implements TestRule, RestDocumentationContextProv
 
 	private final JUnitRestDocumentation delegate;
 
+	/**
+	 * Creates a new {@code RestDocumentation} instance that will generate snippets to the
+	 * to <gradle/maven build path>/generated-snippet.
+	 */
+	public RestDocumentation() {
+		this.delegate = new JUnitRestDocumentation();
+	}
+
 	/**
 	 * Creates a new {@code RestDocumentation} instance that will generate snippets to the
 	 * given {@code outputDirectory}.

spring-restdocs-mockmvc/src/test/java/org/springframework/restdocs/mockmvc/MockMvcRestDocumentationConfigurerTests.java

@@ -44,7 +44,7 @@ public class MockMvcRestDocumentationConfigurerTests {
 	private MockHttpServletRequest request = new MockHttpServletRequest();
 
 	@Rule
-	public JUnitRestDocumentation restDocumentation = new JUnitRestDocumentation("test");
+	public JUnitRestDocumentation restDocumentation = new JUnitRestDocumentation();
 
 	@Test
 	public void defaultConfiguration() {

spring-restdocs-mockmvc/src/test/java/org/springframework/restdocs/mockmvc/MockMvcRestDocumentationIntegrationTests.java

@@ -101,8 +101,7 @@ import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.
 public class MockMvcRestDocumentationIntegrationTests {
 
 	@Rule
-	public JUnitRestDocumentation restDocumentation = new JUnitRestDocumentation(
-			"build/generated-snippets");
+	public JUnitRestDocumentation restDocumentation = new JUnitRestDocumentation();
 
 	@Autowired
 	private WebApplicationContext context;

spring-restdocs-restassured/src/test/java/org/springframework/restdocs/restassured/RestAssuredRestDocumentationConfigurerTests.java

@@ -47,8 +47,7 @@ import static org.mockito.Mockito.verify;
 public class RestAssuredRestDocumentationConfigurerTests {
 
 	@Rule
-	public final JUnitRestDocumentation restDocumentation = new JUnitRestDocumentation(
-			"build");
+	public final JUnitRestDocumentation restDocumentation = new JUnitRestDocumentation();
 
 	private final FilterableRequestSpecification requestSpec = mock(
 			FilterableRequestSpecification.class);

spring-restdocs-restassured/src/test/java/org/springframework/restdocs/restassured/RestAssuredRestDocumentationIntegrationTests.java

@@ -91,8 +91,7 @@ import static org.springframework.restdocs.test.SnippetMatchers.snippet;
 public class RestAssuredRestDocumentationIntegrationTests {
 
 	@Rule
-	public JUnitRestDocumentation restDocumentation = new JUnitRestDocumentation(
-			"build/generated-snippets");
+	public JUnitRestDocumentation restDocumentation = new JUnitRestDocumentation();
 
 	@Value("${local.server.port}")
 	private int port;