The Spring Framework reference manual uses asciidoctor. This document describes how to contribute documentation updates.
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.
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.
-
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.htmlfile. -
Ensure you are not running
guard startat all, as two instances could not run at the same time. To exit a current session in a clean way, typeein the shell.
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
sourceblocks.
Here are some useful resources for working with Asciidoctor: * Asciidoctor Quick Reference * Asciidoctor Manual * Asciidoctor Writers Guide