From d2e5ec67361910cba76b7bbe778636d6ca21ad20 Mon Sep 17 00:00:00 2001 From: Stephane Nicoll Date: Wed, 8 Jan 2014 11:29:49 +0100 Subject: [PATCH 1/2] Improve the "contributing documentation" readme Update the "contributing documentation" readme to include the correct gradle goal and provide a troubleshooting section. --- CONTRIBUTING-DOCUMENTATION.adoc | 22 ++++++++++++++++++---- 1 file changed, 18 insertions(+), 4 deletions(-) diff --git a/CONTRIBUTING-DOCUMENTATION.adoc b/CONTRIBUTING-DOCUMENTATION.adoc index 6277805828..54ee0b8439 100644 --- a/CONTRIBUTING-DOCUMENTATION.adoc +++ b/CONTRIBUTING-DOCUMENTATION.adoc @@ -4,20 +4,34 @@ The Spring Framework reference now uses http://asciidoctor.org/[asciidoctor]. Th == Building with Gradle -You can build the documentation using gradle using the `asciidoc` task. For example, from the project root execute the following command: +You can build the documentation using gradle using the `reference` task. For example, from the project root execute the following command: - gradlew asciidoc + ./gradlew reference -the output will be available at `spring-framework/build/asciidoc/index.html` +the output will be available at `spring-framework/build/reference/htmlsingle/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. +You will find a Guardfile already present at `spring-framework/src/asciidoc/Guardfile`. Make sure first to follow +the setup instructions within the http://asciidoctor.org/docs/editing-asciidoc-with-live-preview/[Editing AsciiDoc with Live Preview] +document. Once you have done that, there are additional gems to install to make it work (assuming that you are using +http://livereload.com/[LiveReload]): + + gem install guard-rspec guard-livereload 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`. +== Troubleshooting + +* If you are using LiveReload, make sure to select _Allow access to file URLs_ in the LiveEdit plugin options of + your browser. +* The icon used to enable _LiveReload_ can be a bit confusing. The dot is empty when it is disabled and full when + the plugin is active. Make sure to enable it on the tab displaying the `index.html` file. +* Ensure you are _not_ running guard start at all as two instances could not run at the same time. To exit a current + session in a clean way, just type e in the shell. + == Documentation notes Some notes on documentation From 54805bc21296b8c7a4b6a9bd487bf38f99e223d0 Mon Sep 17 00:00:00 2001 From: Phillip Webb Date: Thu, 9 Jan 2014 16:35:14 -0800 Subject: [PATCH 2/2] Hard-wrap CONTRIBUTING-DOCUMENTATION at 90 chars --- CONTRIBUTING-DOCUMENTATION.adoc | 41 ++++++++++++++++++++------------- 1 file changed, 25 insertions(+), 16 deletions(-) diff --git a/CONTRIBUTING-DOCUMENTATION.adoc b/CONTRIBUTING-DOCUMENTATION.adoc index 54ee0b8439..6b51e5d7d2 100644 --- a/CONTRIBUTING-DOCUMENTATION.adoc +++ b/CONTRIBUTING-DOCUMENTATION.adoc @@ -1,12 +1,14 @@ = How to contribute to the reference -The Spring Framework reference now uses http://asciidoctor.org/[asciidoctor]. This document describes how to contribute documentation updates. +The Spring Framework reference now uses http://asciidoctor.org/[asciidoctor]. This +document describes how to contribute documentation updates. == Building with Gradle -You can build the documentation using gradle using the `reference` task. For example, from the project root execute the following command: +You can build the documentation using gradle using the `reference` task. For example, from +the project root execute the following command: - ./gradlew reference + ./gradlew reference the output will be available at `spring-framework/build/reference/htmlsingle/index.html` @@ -14,29 +16,36 @@ the output will be available at `spring-framework/build/reference/htmlsingle/ind 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`. Make sure first to follow -the setup instructions within the http://asciidoctor.org/docs/editing-asciidoc-with-live-preview/[Editing AsciiDoc with Live Preview] -document. Once you have done that, there are additional gems to install to make it work (assuming that you are using -http://livereload.com/[LiveReload]): +You will find a Guardfile already present at `spring-framework/src/asciidoc/Guardfile`. +Make sure first to follow the setup instructions within the +http://asciidoctor.org/docs/editing-asciidoc-with-live-preview/[Editing AsciiDoc with Live Preview] +document. Once you have done that, there are additional gems to install to make it work +(assuming that you are using http://livereload.com/[LiveReload]): - gem install guard-rspec guard-livereload + gem install guard-rspec guard-livereload -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`. +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`. == Troubleshooting -* If you are using LiveReload, make sure to select _Allow access to file URLs_ in the LiveEdit plugin options of - your browser. -* The icon used to enable _LiveReload_ can be a bit confusing. The dot is empty when it is disabled and full when - the plugin is active. Make sure to enable it on the tab displaying the `index.html` file. -* Ensure you are _not_ running guard start at all as two instances could not run at the same time. To exit a current - session in a clean way, just type e in the shell. +* If you are using LiveReload, make sure to select _Allow access to file URLs_ in the + LiveEdit plugin options of your browser. +* The icon used to enable _LiveReload_ can be a bit confusing. The dot is empty when it is + disabled and full when the plugin is active. Make sure to enable it on the tab + displaying the `index.html` file. +* Ensure you are _not_ running guard start at all as two instances could not run at the + same time. To exit a current session in a clean way, just type e in the shell. == 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. +* Documentation is wrapped at 90 chars, ensure that you manually wrap your edits +* Tabs are used for indentation, do not use spaces +* Follow the existing style when inserting `source` blocks * 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] +