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

Hard-wrap CONTRIBUTING-DOCUMENTATION at 90 chars

This commit is contained in:
Phillip Webb 2014-01-09 16:35:14 -08:00
parent d2e5ec6736
commit 54805bc212
1 changed files with 25 additions and 16 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

41
CONTRIBUTING-DOCUMENTATION.adoc
View File

@ -1,12 +1,14 @@
= How to contribute to the reference = How to contribute to the reference
The Spring Framework reference now uses http://asciidoctor.org/[asciidoctor]. This document describes how to contribute documentation updates. The Spring Framework reference now uses http://asciidoctor.org/[asciidoctor]. This
document describes how to contribute documentation updates.
== Building with Gradle == Building with Gradle
You can build the documentation using gradle using the `reference` task. For example, from the project root execute the following command: You can build the documentation using gradle using the `reference` task. For example, from
the project root execute the following command:
./gradlew reference ./gradlew reference
the output will be available at `spring-framework/build/reference/htmlsingle/index.html` the output will be available at `spring-framework/build/reference/htmlsingle/index.html`
@ -14,29 +16,36 @@ the output will be available at `spring-framework/build/reference/htmlsingle/ind
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`. Make sure first to follow You will find a Guardfile already present at `spring-framework/src/asciidoc/Guardfile`.
the setup instructions within the http://asciidoctor.org/docs/editing-asciidoc-with-live-preview/[Editing AsciiDoc with Live Preview] Make sure first to follow the setup instructions within the
document. Once you have done that, there are additional gems to install to make it work (assuming that you are using http://asciidoctor.org/docs/editing-asciidoc-with-live-preview/[Editing AsciiDoc with Live Preview]
http://livereload.com/[LiveReload]): 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 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`. 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 == Troubleshooting
* If you are using LiveReload, make sure to select _Allow access to file URLs_ in the LiveEdit plugin options of * If you are using LiveReload, make sure to select _Allow access to file URLs_ in the
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 is disabled and full when * The icon used to enable _LiveReload_ can be a bit confusing. The dot is empty when it is
the plugin is active. Make sure to enable it on the tab displaying the `index.html` file. disabled and full when the plugin is active. Make sure to enable it on the tab
* Ensure you are _not_ running guard start at all as two instances could not run at the same time. To exit a current displaying the `index.html` file.
session in a clean way, just type e in the shell. * 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 == Documentation notes
Some notes on documentation Some notes on documentation
* It is important to keep whitespaces to a minimum to make it simple to edit files. This means use an editor with line wrapping rather than manually inserting hard returns. * 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/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]