diff --git a/CONTRIBUTING-DOCUMENTATION.adoc b/CONTRIBUTING-DOCUMENTATION.adoc index 54ee0b8439e..6b51e5d7d22 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] +