You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
51 lines
2.1 KiB
51 lines
2.1 KiB
= How to contribute to the reference |
|
|
|
The Spring Framework reference now uses https://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 |
|
https://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 |
|
|
|
* 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 |
|
* https://asciidoctor.org/docs/asciidoc-syntax-quick-reference/[Asciidoctor Quick Reference] |
|
* https://asciidoctor.org/docs/user-manual/[Asciidoctor Manual] |
|
* https://asciidoctor.org/docs/asciidoc-writers-guide/[Asciidoctor Writers Guide] |
|
|
|
|