ReStructuredText Style Guide¶

Other semantic markup¶

In addition to the fundamental inline typesetting styles above, you may use additional reST roles to provide semantic meaning to the text. The documentation’s CSS takes advantage of this semantic meaning to provide visual cues to readers.

Abbreviations

:abbr:`LSST (Large Synoptic Survey Telescope` → LSST (a tool tip exposes the definition)

Filenames and paths

:file:`repos.yaml` → repos.yaml

Shell commands

:command:`git rebase -i master` → git rebase -i master

User interface labels

:guilabel:`New Pull Request` → New Pull Request. This markup can be used for button labels, menus, or even text labels in interactive shell programs.

Keyboard commands

:kbd:`Control-a s` → Control-a s. Spell out the keys rather than using Emacs short hand, such as C-x.

To semantically markup Python or C++ code objects, refer to the section on Links to code objects.

Definition lists¶

Definition lists are terms with an indented content section. For example:

LSST
    Large Synoptic Survey Telescope

DM
    Data Management

produces

LSST

Large Synoptic Survey Telescope

DM

Data Management

Definition lists are not limited to dictionary-like usage; they can be employed whenever a series of terms with associated micro content is needed.

External links¶

Links to external web pages can be made two ways. The first way is:

When writing Python, it's a good idea to use the `PEP8 style guide`_.

.. _PEP8 style guide: https://www.python.org/dev/peps/pep-0008/

The link reference should be provided directly following the paragraph to make it easier for editors to ensure the text in backticks matches the link reference line. Despite this fragility, this style is good since it makes the reST itself more readable.

The second method is to put the URL inline:

When writing Python, it's a good idea to use the
`PEP8 style guide <https://www.python.org/dev/peps/pep-0008/>`_.

You may decide to use either method, taking readability into consideration.

Internal links to labels¶

Any content block can be labeled. For example, to give a section the label making-labels, we write:

.. _making-labels:

Making Labels
-------------

Labels are an empty directive that appear directly before any block, such
as a section, image, table, or code block.
Labels start with an underscore, and words in labels are separated by
hyphens.
Labels are a **global namespace**, so make them as specific as possible.

With the :ref: role you can link to a labeled block:

For internal links, :ref:`you'll need to make labels <making-labels>`.

You can also make references with :ref:`label-name` and the link text will automatically be populated with the section title or figure caption, for example.

Internal links to other pages¶

To link to another page in the same doc project, use the :doc: role with the relative path to the target .rst document.

See our :doc:`Styleguide <rst_styleguide>` to learn how to write reST docs.

Note how the .rst extension wasn’t included.

Links to equations¶

Equations can be linked to using a :ref: to their label, as described above. If the equation with numbered by adding a :label: field to the math directive itself then that equation can be reference with the :eq: role. See Referencing equations for more information.

Links to code objects¶

When describing a code object, you can also link to that object’s API definition using a syntax similar to the :ref: role used above.

:py:func:`~numpy.sin`

:py:func:`Numpy's sine function <numpy.sin>`

.. default-domain:: py

Plain images¶

Plain images can be included with the image directive. For example:

.. image:: /_static/development/docs/lsst_logo.jpg
   :target: ../../_static/development/docs/lsst_logo.jpg
   :alt: LSST Logo

This example shows how an image can by hyperlinked to any URL with the target field. Internal links, as in the example, must be relative to the reST document; Sphinx does not process URLs in an image‘s target field.

The image directive has more configurable fields. If image sizes need to be manipulated from reST, we recommend using scale since it is responsive. We hope to provide better support for responsive image sizing.

Be sure to leave a blank line before and after the image directive.

Figure directive¶

Figures include both an image and a caption. For example:

.. figure:: /_static/development/docs/lsst_logo.jpg
   :name: fig-example-figure-label
   :target: ../../_static/development/docs/lsst_logo.jpg
   :alt: LSST Logo

   LSST Logo.

LSST Logo.

Note that the :name: field takes the place of a separate label for hyperlinking. By convention, these labels should be prefixed with “fig-.”

Be sure to leave a blank line before and after the figure directive.

Note on paths to image files¶

Images are included in the _static/ directory of the git repository for this documentation project. Sphinx requires image assets to be located in this _static/ directory in order to properly copy files into the built website. By using a prefix “/” we indicate that a path is relative to the root of the documentation repository.

Package documentation is hosted in doc/ directories of the git repositories of individual Stack packages. For such package documentation, image files should be placed inside a directory in doc/_static/ named for the package itself. For example doc/_static/obs_decam/ for the obs_decam package. This nested directory structure is needed to merge package documentation content into the root documentation build.

Inline math¶

Write inline math expressions with the math role. For example, :math:`\sigma_\mathrm{mean} = \sigma / \sqrt{N}` produces \(\sigma_\mathrm{mean} = \sigma / \sqrt{N}\).

Block math¶

To display math as a block element, use the math directive (be sure to leave a blank line before and after the math directive). For example:

.. math:: \sigma_\mathrm{mean} = \frac{\sigma}{\sqrt{N}}
   :label: math-sample

renders as

.. math::

   \nabla \cdot \mathbf{E} = \frac{\rho}{\epsilon_0}

   \nabla \cdot \mathbf{B} = 0

.. math::

   x &= (a + b)^2 \\
     &= a^2 + 2ab + b^2

Including source code examples from other files with literalinclude¶

The code-block directive is great for code examples written in the reStructuredText source file itself. You might also want to show a code sample contained in a separate file. For this you can use the literalinclude directive:

.. literalinclude:: path/to/example.py
   :language: py

The source path can either be relative to the reST document or relative to the documentation root by prefixing the path with /.

The literalinclude directive also supports code-block fields, such as name and emphasize-lines. In addition, you can selective include ranges of lines with the lines field. For example, to include only lines 10 – 20:

.. literalinclude:: path/to/example.py
   :language: py
   :lines: 10-20

To omit the first two lines from a file:

.. literalinclude:: path/to/example.py
   :language: py
   :lines: 2-

Sophisticated inclusion patterns can be achieved by listing multiple spans, such as :lines: 3-10,20-, which shows the first ten lines and all lines after the 20^th.

When including code example snippets from other files, it may be useful to remove indentation. Use the dedent field for that. For example:

.. literalinclude:: path/to/example.py
   :language: py
   :lines: 5-10
   :dedent: 4

will show lines 5 – 10 and remove 4 space characters (presumably because the snippet is inside a Python class or function).

Lightweight syntax for Python code and sessions¶

You can markup Python code blocks using a lightweight syntax:

::

   print('hello world!')

Interactive python sections can be marked up as

>>> print('Hello world!')
Hello world!

This lightweight syntax is used in Python docstrings.

Text wrapping¶

When writing reST documentation in Python files, documentation lines should be kept to lengths of 75 characters or fewer (discounting leading indentation).

For reStructuredText documents (e.g., .rst files), reST doesn’t care about line formatting. Emacs users, for example, are free to use hard-wrap formatting lines at 72 characters if that helps you write docs. Whenever possible, we encourage you to use soft-wrapping for your text. This allows others format text columns in their editors as they wish. As well, the GitHub.com code editor does not have hard-wrap auto-formatting. Those making doc edits on GitHub.com will tend to use soft-wrap by default (see ‘GitHub Flow in the Browser‘).

When using soft-wrap formatting, you might write one sentence per line (i.e., put a line break after each sentence). As a writer, this has the advantage of making it easier to check the rhythm of your writing, including sentence lengths. Shorter sentences are easier to read. One-sentence-per-line is also semantically correct in the sense of Git.

At LSST, we place a single blank line between all content blocks, such as directives, paragraphs and lists.

Indentation¶

ReStructuredText should be indented consistently with the context, which generally means taking visual alignment cues rather than adhering to a fixed indent width.

In directives, align to the directive’s name:

.. code-block:: python

   print('hello world')

In lists, align naturally with the text:

- First item.

  Another paragraph for the first item.
- Second item.

Note how that alignment adapts to numbered lists:

1. First item.

   Another paragraph for the first item.
2. Second item.

For argument lists in Python docstrings we indent descriptions by four spaces:

Parameters
----------
x_coord : float
    Particle's x-coordinate.
y_coord : float
    Particle's y-coordinate.

Encoding and special characters¶

LSST’s reStructuredText source files should be encoded as UTF-8 unicode. This means that special characters such as en (–) and em (—) dashes can just be written as such. We do run a variant of smartypants in an attempt to convert -- and --- into en and em dashes, respectively, and to covert dumb quotes (") into “typographic” quotes.