forked from spring-projects/spring-framework
-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Hard-wrap CONTRIBUTING-DOCUMENTATION at 90 chars
- Loading branch information
Phillip Webb
committed
Jan 10, 2014
1 parent
d2e5ec6
commit 54805bc
Showing
1 changed file
with
25 additions
and
16 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,42 +1,51 @@ | ||
= 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 | ||
|
||
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` | ||
|
||
== 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]): | ||
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]): | ||
|
||
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 | ||
|
||
* 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. | ||
* 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 | ||
|
||
* 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/user-manual/[Asciidoctor Manual] | ||
* http://asciidoctor.org/docs/asciidoc-writers-guide/[Asciidoctor Writers Guide] | ||
|