spring-framework/CONTRIBUTING-DOCUMENTATION....

= How to contribute to the reference

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:

  ./gradlew reference

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`. 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

* 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.
* 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]
Migrate documentation to asciidoctor This commit migrates to asciidoctor to ease writing documentation. Issues: SPR-10960 2013-11-05 01:21:53 +08:00			`= How to contribute to the reference`

Update CONTRIBUTING-DOCUMENTATION.adoc 2013-11-05 04:56:48 +08:00			`The Spring Framework reference now uses http://asciidoctor.org/[asciidoctor]. This document describes how to contribute documentation updates.`
Migrate documentation to asciidoctor This commit migrates to asciidoctor to ease writing documentation. Issues: SPR-10960 2013-11-05 01:21:53 +08:00
			`== Building with Gradle`

Improve the "contributing documentation" readme Update the "contributing documentation" readme to include the correct gradle goal and provide a troubleshooting section. 2014-01-08 18:29:49 +08:00			You can build the documentation using gradle using the `reference` task. For example, from the project root execute the following command:
Migrate documentation to asciidoctor This commit migrates to asciidoctor to ease writing documentation. Issues: SPR-10960 2013-11-05 01:21:53 +08:00
Improve the "contributing documentation" readme Update the "contributing documentation" readme to include the correct gradle goal and provide a troubleshooting section. 2014-01-08 18:29:49 +08:00			`./gradlew reference`
Migrate documentation to asciidoctor This commit migrates to asciidoctor to ease writing documentation. Issues: SPR-10960 2013-11-05 01:21:53 +08:00
Improve the "contributing documentation" readme Update the "contributing documentation" readme to include the correct gradle goal and provide a troubleshooting section. 2014-01-08 18:29:49 +08:00			the output will be available at `spring-framework/build/reference/htmlsingle/index.html`
Migrate documentation to asciidoctor This commit migrates to asciidoctor to ease writing documentation. Issues: SPR-10960 2013-11-05 01:21:53 +08:00
			`== Live editing`

			`One of the nice features about using asciidoctor is the support for live editing.`

Improve the "contributing documentation" readme Update the "contributing documentation" readme to include the correct gradle goal and provide a troubleshooting section. 2014-01-08 18:29:49 +08:00			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`
Migrate documentation to asciidoctor This commit migrates to asciidoctor to ease writing documentation. Issues: SPR-10960 2013-11-05 01:21:53 +08:00
			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`.

Improve the "contributing documentation" readme Update the "contributing documentation" readme to include the correct gradle goal and provide a troubleshooting section. 2014-01-08 18:29:49 +08:00			`== 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.`

Migrate documentation to asciidoctor This commit migrates to asciidoctor to ease writing documentation. Issues: SPR-10960 2013-11-05 01:21:53 +08:00			`== 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.`
			`* http://asciidoctor.org/docs/asciidoc-syntax-quick-reference/[Asciidoctor Quick Reference]`
			`* http://asciidoctor.org/docs/user-manual/[Asciidoctor Manual]`
Update CONTRIBUTING-DOCUMENTATION.adoc 2013-11-05 04:56:26 +08:00			`* http://asciidoctor.org/docs/asciidoc-writers-guide/[Asciidoctor Writers Guide]`