Permalink
Switch branches/tags
debian/2.10.0+rc4 debian/2.10.0+rc3 debian/2.10.0+rc2 debian/2.10.0+rc1 debian/2.10.0+rc0 debian/2.8.1+rc0 debian/2.8.0+thefinal0 debian/2.8.0+rc13 debian/2.8.0+rc12 debian/2.8.0+rc11 debian/2.8.0+rc10 debian/2.8.0+rc9 debian/2.8.0+rc8 debian/2.8.0+rc7 debian/2.8.0+rc6 debian/2.8.0+rc5 debian/2.8.0+rc4 debian/2.8.0+rc3 debian/2.8.0+rc2 debian/2.8.0+rc1 debian/2.8.0+rc0 debian/2.7.5+dev20180124154147 debian/2.7.5+dev20180123112419 debian/2.7.4+dev20171114153121 debian/2.7.2+dev20171013181704 debian/2.7.1+dev20171013111656 debian/2.7.0+thefinal0 debian/2.6.3+thefinal0 debian/2.6.2+thefinal0 debian/2.6.1+thefinal0 debian/2.6.0+thefinal0 debian/2.6.0+rc1 debian/2.6.0+beta1 debian/2.6.0+alpha1 debian/2.5.15+thefinal0 debian/2.5.14+thefinal0 debian/2.5.13+thefinal0 debian/2.5.12+thefinal0 debian/2.5.11+thefinal0 debian/2.5.10+thefinal0 debian/2.5.9+thefinal5 debian/2.5.9+thefinal4 debian/2.5.9+thefinal3 debian/2.5.9+thefinal2 debian/2.5.9+thefinal1 debian/2.5.9+thefinal0 debian/2.5.9+dev20170116091118 debian/2.5.7+thefinal0 debian/2.5.6+thefinal0 debian/2.5.5+thefinal0 debian/2.5.4+thefinal0 debian/2.5.3+thefinal0 debian/2.5.2+thefinal0 debian/2.5.1+thefinal0 debian/2.5.0+thefinal0 debian/2.4.1+thefinal1 debian/2.4.0+thefinal0 debian/2.4.0+rc4 debian/2.4.0+rc3 debian/2.4.0+rc2 debian/2.4.0+rc1 debian/2.4.0+dev20141024171719 debian/2.4.0+beta28 debian/2.4.0+beta27 debian/2.4.0+beta26 debian/2.4.0+beta25 debian/2.4.0+beta24 debian/2.4.0+beta23 debian/2.4.0+beta22 debian/2.4.0+beta21 debian/2.4.0+beta20 debian/2.4.0+beta19 debian/2.4.0+beta18 debian/2.4.0+beta17 debian/2.4.0+beta16 debian/2.4.0+beta15 debian/2.4.0+beta14 debian/2.4.0+beta13 debian/2.4.0+beta12 debian/2.4.0+beta11 debian/2.4.0+beta10 debian/2.4.0+beta9 debian/2.4.0+beta8 debian/2.4.0+beta7 debian/2.4.0+beta6 debian/2.4.0+beta5 debian/2.4.0+beta4 debian/2.4.0+beta3 debian/2.4.0+beta2 debian/2.4.0+beta1 debian/2.4.0+alpha38 debian/2.4.0+alpha37 debian/2.4.0+alpha36 debian/2.4.0+alpha35 debian/2.4.0+alpha34 debian/2.4.0+alpha33 debian/2.4.0+alpha32 debian/2.4.0+alpha31 debian/2.4.0+alpha30 debian/2.4.0+alpha29
Nothing to show
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
274 lines (164 sloc) 7.23 KB
.. _doc_guidelines:
==========================
How to write Documentation
==========================
GeoNode uses reStructuredText with `Sphinx <http://www.sphinx-doc.org>`_ . Writing style should follow the same policies as GeoServer does in their `Documentation Style Guide <http://docs.geoserver.org/latest/en/docguide/style.html>`_
Sphinx Syntax
=============
This page contains syntax rules, tips, and tricks for using Sphinx and reStructuredText. For more information, please see:
* `RST Quick Reference <http://docutils.sourceforge.net/docs/user/rst/quickref.html#section-structure>`_
* `Comprehensive guide to reStructuredText <http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html>`_
* `Sphinx reStructuredText Primer <http://www.sphinx-doc.org/rest.html>`_
Basic markup
------------
A reStructuredText document is written in plain text. Without the need for complex formatting, one can be composed simply, just like one would any plain text document. For basic formatting, see this table:
.. list-table::
:widths: 30 40 30
* - **Format**
- **Syntax**
- **Output**
* - Italics
- ``*italics*`` (single asterisk)
- *italics*
* - Bold
- ``**bold**`` (double asterisk)
- **bold**
* - Monospace
- `` ``monospace`` `` (double back quote)
- ``monospace``
Sections, subtitles and titles
------------------------------
Use sections to break up long pages and to help Sphinx generate tables of contents.
The top of the page (i.e. the title) should have an equals sign (=) above and below::
==============
Camel Spotting
==============
Level 2 section headers should have an equals sign (=) below the section name with same length as name::
I am a level 2 header
=====================
Level 3 sections should have a single minus symbol (-)::
I am a level 3 header
---------------------
Level 4 sections should have a single dot, period symbol (.)::
I am a level 4 header
.....................
Level 5 sections should have a single dot, period symbol (.)::
I am a level 5 header
+++++++++++++++++++++
Page labels
-----------
**Ensure every page has a label.** For example if the page is named ``foo_bar.txt`` then the page should have the label at the top of the file (line1) ::
.. _foo_bar:
Other pages can then link to that page by using the following code::
:ref:`foo_bar`
.. _linking:
Linking
-------
Links to other pages should never be titled as "here". Sphinx makes this easy by automatically inserting the title of the linked document.
Using the following code::
:ref:`linking`
And here is the link in action :ref:`linking` to use the link place this code some where in your open file::
.. _linking:
To insert a link to an external website::
`Text of the link <http://docs.geoserver.org/latest/en/docguide/style.html>`_
The resulting link would look like this: `Text of the link <http://example.com>`_
Lists
-----
There are two types of lists, bulleted lists and numbered lists.
A **bulleted list** looks like this:
* An item
* Another item
* Yet another item
This is accomplished with the following code::
* An item
* Another item
* Yet another item
A **numbered list** looks like this:
#. First item
#. Second item
#. Third item
This is accomplished with the following code::
#. First item
#. Second item
#. Third item
Note that numbers are automatically generated, making it easy to add/remove items.
List-tables
-----------
Bulleted lists can sometimes be cumbersome and hard to follow. When dealing with a long list of items, use list-tables. For example, to talk about a list of options, create a table that looks like this:
.. list-table::
:widths: 20 80
:header-rows: 1
* - Shapes
- Description
* - Square
- Four sides of equal length, 90 degree angles
* - Rectangle
- Four sides, 90 degree angles
This is done with the following code::
.. list-table::
:widths: 20 80
:header-rows: 1
* - Shapes
- Description
* - Square
- Four sides of equal length, 90 degree angles
* - Rectangle
- Four sides, 90 degree angles
Notes and warnings
------------------
To emphasize something Sphinx has two ways, a note and a warning. They work the same, and only differ in their coloring. You should use notes and warnings sparingly, however, as adding emphasis to everything makes the emphasis less effective.
Here is an example of a note:
.. note:: This is a note.
This note is generated with the following code::
.. note:: This is a note.
Similarly, here is an example of a warning:
.. warning:: Beware of dragons.
This warning is generated by the following code::
.. warning:: Beware of dragons.
Images
------
Add images to your documentation when possible. Images, such as screen shots, are a very helpful way of making documentation understandable. When making screenshots, try to crop out unnecessary content (browser window, desktop, etc). Avoid scaling the images, as the Sphinx theme automatically resizes large images. It is also helpful to include a caption underneath the image.
.. figure:: img/logo.png
:align: center
*The GeoNode logo as shown on the homepage.*
This image is generated by the following code::
.. figure:: img/logo.png
:align: center
*The GeoNode logo as shown on the homepage.*
In this example, the image file exists in the same directory as the source page. If this is not the case, you can insert path information in the above command.
External files
--------------
Text snippets, large blocks of downloadable code, and even zip files or other binary sources can all be included as part of the documentation. To include files as part of the build process, use the following syntax::
:download:`An external file <README>`
The result of this code will generate a standard link to an :download:`external file <readme.txt>`
Reference files and paths
-------------------------
Use the following syntax to reference files and paths::
:file:`myfile.txt`
This will output: :file:`myfile.txt`.
You can reference paths in the same way::
:file:`path/to/myfile.txt`
This will output: :file:`path/to/myfile.txt`.
For Windows paths, use double backslashes::
:file:`C:\\myfile.txt`
This will output: :file:`C:\\myfile.txt`.
If you want to reference a non-specific path or file name::
:file:`{your/own/path/to}/myfile.txt`
This will output: :file:`{your/own/path/to}/myfile.txt`
Reference commands
------------------
Reference commands (such as :command:`make`) with the following syntax::
:command:`make`
Reference an element in a GUI
-----------------------------
Use the following syntax to direct a user to click a link or look to a certain area of the GUI::
:guilabel:`Main Menu`
This will output: :guilabel:`Main Menu`.
Menu traversal
--------------
Direct a user through a menu with the following syntax::
:menuselection:`Start Menu --> Programs --> Geonode`
This will output :menuselection:`Start Menu --> Programs --> Geonode`.
Show Source
-----------
Every page in the GeoNode documentation has a link for ``Show Source`` under the Table of Contents on the right side of the page. This allows for easy reverse engineering of unfamiliar markup. When in doubt, look at the source!