|
|
|
|
= How to contribute to the reference manual
|
|
|
|
|
|
|
|
|
|
The Spring Framework reference manual 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 `asciidoctor` task. For example,
|
|
|
|
|
from the project root execute the following command:
|
|
|
|
|
|
|
|
|
|
[indent=0]
|
|
|
|
|
----
|
|
|
|
|
./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/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]):
|
|
|
|
|
|
|
|
|
|
[indent=0]
|
|
|
|
|
----
|
|
|
|
|
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 to
|
|
|
|
|
`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, 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.
|
|
|
|
|
* 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]
|
