Sphinx Syntax

This page contains syntax rules, tips, and tricks for using Sphinx and reStructuredText. For more information, please see this comprehensive guide to reStructuredText, as well as the Sphinx reStructuredText Primer.

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:

Format Syntax Output
Italics *italics* (single asterisk) italics
Bold **bold** (double asterisk) bold
Monospace `` monospace `` (double back quote) monospace

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:

  1. First item
  2. Second item
  3. 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:

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

Page labels

Ensure every page has a label that matches the name of the file. For example if the page is named foo_bar.rst then the page should have the label:

..  _foo_bar:

Other pages can then link to that page by using the following code:

:ref:`foo_bar`

Linking

Links to other pages should never be titled as “here”. Sphinx makes this easy by automatically inserting the title of the linked document.

Bad
More information about linking can be found here.
Good
For more information, please see the section on Linking.

To insert a link to an external website:

`Text of the link <http://example.com>`_

The resulting link would look like this: Text of the link

Sections

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 a double underline:

Camel Spotting
==============

Subsequent section headers should have a single underline:

Camel Spotting
==============

Intro to the Camel
------------------

Finding a Camel
---------------

Recording its Serial Number
---------------------------

Should these sections require subsections, use the back quote:

Intro to the Camel
------------------

Camel History
`````````````

Camels Today
````````````

Notes and warnings

When it is beneficial to have a section of text stand out from the main text, Sphinx has two such boxes, the note and the warning. They function identically, 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 screenshots, 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.

_images/pagelogo.png

The GeoServer logo as shown on the homepage.

This image is generated by the following code:

.. figure:: pagelogo.png
   :align: center

   *The GeoServer 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.txt>`

The result of this code will generate a standard link to an external file

Reference files and paths

Use the following syntax to reference files and paths:

:file:`myfile.txt`

This will output: myfile.txt.

You can reference paths in the same way:

:file:`path/to/myfile.txt`

This will output: path/to/myfile.txt.

For Windows paths, use double backslashes:

:file:`C:\\myfile.txt`

This will output: 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: your/own/path/to/myfile.txt

Reference commands

Reference commands (such as 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: Main Menu.

Show Source

Every page in the GeoServer 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!

Previous: Workflow