Skip to content

CONTRIBUTING-DOCUMENTATION.adoc edit #1512

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 1 commit into from
Closed

CONTRIBUTING-DOCUMENTATION.adoc edit #1512

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
26 changes: 15 additions & 11 deletions CONTRIBUTING-DOCUMENTATION.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
document describes how to contribute documentation updates.
Expand All @@ -13,14 +13,16 @@ from the project root execute the following command:
./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

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 the setup instructions within the
You will find a Guardfile already present at
`spring-framework/src/docs/asciidoc/Guardfile`. First, 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]):
Expand All @@ -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
`src/asciidoc/index.adoc` file will automatically be written to
`src/asciidoc/index.adoc` file are automatically written to
`src/asciidoc/build/index.html`.

== 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.
* 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.
* 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.
* 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.

Here are some useful resources for working with Asciidoctor:
* 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]