CONTRIBUTING-DOCUMENTATION.adoc

How to Contribute to the Reference Manual

The Spring Framework reference manual uses asciidoctor. This document describes how to contribute documentation updates.

Building with Gradle

You can build the documentation using Gradle using the asciidoctor task. For example, from the project root execute the following command:

./gradlew asciidoctor

The generated reference manual will then be available at build/asciidoc/html5/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/docs/asciidoc/Guardfile. First, follow the setup instructions within the 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 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 are automatically written to src/asciidoc/build/index.html.

Troubleshooting

• If you are using LiveReload, 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, type e in the shell.

Documentation Notes

Some notes on the documentation.

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

Here are some useful resources for working with Asciidoctor:

• Asciidoctor Quick Reference

• Asciidoctor Manual

• Asciidoctor Writers Guide