From eb46eaa3c55b5b6099aed9c5e406da602ee2f386 Mon Sep 17 00:00:00 2001 From: mle Date: Thu, 21 Jul 2016 20:06:15 +0200 Subject: [PATCH 1/2] Improve documention on how to use .adoc snippets Closes gh-279 --- docs/src/docs/asciidoc/getting-started.adoc | 21 ++++++++++++++++++++- 1 file changed, 20 insertions(+), 1 deletion(-) diff --git a/docs/src/docs/asciidoc/getting-started.adoc b/docs/src/docs/asciidoc/getting-started.adoc index 853e2a47..9bd7907a 100644 --- a/docs/src/docs/asciidoc/getting-started.adoc +++ b/docs/src/docs/asciidoc/getting-started.adoc @@ -419,7 +419,26 @@ that can be produced by Spring REST Docs. [[getting-started-using-the-snippets]] === Using the snippets -The generated snippets can be included in your documentation using the +Before using the generated snippets from above, an ```\*.adoc``` source file must be manually created. +Its filename does not matter for either of the two build tools' Asciidoctor plugins mentioned +above and will also be the name of the finally generated ```*.html``` file. +For the exact locations refer to the following table. + +[cols="2,5,8"] +|=== +| Build tool | Source files | Generated files + +| Maven +| ```src/main/asciidoc/*.adoc``` +| ```${project.build.directory}/generated-docs/*.html``` + +| Gradle +| ```src/docs/asciidoc/*.adoc``` +| ```$buildDir/asciidoc/*.html``` + +|=== + +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 <> can be used to reference the snippets output directory. For example: From 9c97c8b9bf17a8ebfa50ca38450e356da6663a92 Mon Sep 17 00:00:00 2001 From: Andy Wilkinson Date: Fri, 22 Jul 2016 10:45:14 +0100 Subject: [PATCH 2/2] Polish "Improve documention on how to use .adoc snippets" See gh-279 --- docs/src/docs/asciidoc/getting-started.adoc | 19 ++++++++++--------- 1 file changed, 10 insertions(+), 9 deletions(-) diff --git a/docs/src/docs/asciidoc/getting-started.adoc b/docs/src/docs/asciidoc/getting-started.adoc index 9bd7907a..0dd07620 100644 --- a/docs/src/docs/asciidoc/getting-started.adoc +++ b/docs/src/docs/asciidoc/getting-started.adoc @@ -419,26 +419,27 @@ that can be produced by Spring REST Docs. [[getting-started-using-the-snippets]] === Using the snippets -Before using the generated snippets from above, an ```\*.adoc``` source file must be manually created. -Its filename does not matter for either of the two build tools' Asciidoctor plugins mentioned -above and will also be the name of the finally generated ```*.html``` file. -For the exact locations refer to the following table. +Before using the generated snippets, a `.adoc` source file must be created. You can name +the file whatever you like as long as it has a `.adoc` suffix. The result HTML file will +have the same name but with a `.html` suffix. The default location of the source files and +the resulting HTML files depends on whether you are using Maven or Gradle: [cols="2,5,8"] |=== | Build tool | Source files | Generated files | Maven -| ```src/main/asciidoc/*.adoc``` -| ```${project.build.directory}/generated-docs/*.html``` +| `src/main/asciidoc/*.adoc` +| `target/generated-docs/*.html` | Gradle -| ```src/docs/asciidoc/*.adoc``` -| ```$buildDir/asciidoc/*.html``` +| `src/docs/asciidoc/*.adoc` +| `build/asciidoc/html5/*.html` |=== -The generated snippets can then be included in the manually created Asciidoctor file from above using the +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 <> can be used to reference the snippets output directory. For example: