root
/
spring-framework
mirror of https://github.com/spring-projects/spring-framework.git
1
0
Fork 0
Code Issues Actions Packages Projects Releases Wiki Activity

CONTRIBUTING-DOCUMENTATION.adoc edit 

I made it be more formal and be easier to read.

Closes gh-1512
This commit is contained in:
Jay Bryant 2017-08-31 12:01:37 -05:00 committed by Stephane Nicoll
parent 3a006439ee
commit 3736b049d0
1 changed files with 15 additions and 11 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

26
CONTRIBUTING-DOCUMENTATION.adoc
View File

@ -1,4 +1,4 @@
= How to contribute to the reference manual = How to Contribute to the Reference Manual
The Spring Framework reference manual uses http://asciidoctor.org/[asciidoctor]. This The Spring Framework reference manual uses http://asciidoctor.org/[asciidoctor]. This
document describes how to contribute documentation updates. document describes how to contribute documentation updates.
@ -13,14 +13,16 @@ from the project root execute the following command:
./gradlew asciidoctor ./gradlew asciidoctor
---- ----
The generated reference manual will then be available at `build/asciidoc/html5/index.html`. The generated reference manual will then be available at
`build/asciidoc/html5/index.html`.
== Live Editing == Live Editing
One of the nice features about using asciidoctor is the support for 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`. You will find a Guardfile already present at
Make sure first to follow the setup instructions within the `spring-framework/src/docs/asciidoc/Guardfile`. First, follow the setup instructions
within the
http://asciidoctor.org/docs/editing-asciidoc-with-live-preview/[Editing AsciiDoc 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 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]): install to make it work (assuming that you are using http://livereload.com/[LiveReload]):
@ -31,26 +33,28 @@ install to make it work (assuming that you are using http://livereload.com/[Live
---- ----
When running `guard start` within the `src/asciidoc/` folder, any changes to the 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/index.adoc` file are automatically written to
`src/asciidoc/build/index.html`. `src/asciidoc/build/index.html`.
== Troubleshooting == Troubleshooting
* If you are using LiveReload, make sure to select _Allow access to file URLs_ in the * If you are using LiveReload, select _Allow access to file URLs_ in the
LiveEdit plugin options of your browser. LiveEdit plugin options of your browser.
* The icon used to enable _LiveReload_ can be a bit confusing. The dot is empty when it * 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 is disabled and full when the plugin is active. Make sure to enable it on the tab
displaying the `index.html` file. displaying the `index.html` file.
* Ensure you are _not_ running `guard start` at all as two instances could not run at the * Ensure you are _not_ running `guard start` at all, as two instances could not run at
same time. To exit a current session in a clean way, type `e` in the shell. the same time. To exit a current session in a clean way, type `e` in the shell.
== Documentation Notes == Documentation Notes
Some notes on the documentation. Some notes on the documentation.
* Documentation is wrapped at 90 chars; ensure that you manually wrap your edits. * Documentation is wrapped at 90 chars. Ensure that you manually wrap your edits.
* Tabs are used for indentation; do not use spaces. * Tabs are used for indentation. Do not use spaces.
* Follow the existing style when inserting `source` blocks. * Follow the existing style when inserting `source` blocks.
Here are some useful resources for working with Asciidoctor:
* http://asciidoctor.org/docs/asciidoc-syntax-quick-reference/[Asciidoctor Quick Reference] * http://asciidoctor.org/docs/asciidoc-syntax-quick-reference/[Asciidoctor Quick Reference]
* http://asciidoctor.org/docs/user-manual/[Asciidoctor Manual] * http://asciidoctor.org/docs/user-manual/[Asciidoctor Manual]
* http://asciidoctor.org/docs/asciidoc-writers-guide/[Asciidoctor Writers Guide] * http://asciidoctor.org/docs/asciidoc-writers-guide/[Asciidoctor Writers Guide]