reST Style Reference Guide

A quick reference for reST formatting for the procedural documentation included in Rubin Observatory Operations Documentation.

The information provided below is based on the LSST DM reStructuredText style guide.

ReStructuredText is an extensible markup language used by LSST.

In-line Text Styling

Italics

Italics can be used to lend emphasis to specific ideas, concepts and new terms, e.g. scheduling algorithm, seeing, ATCS cRIO user, highlighting their importance within the text.

Use also italics to declare hostnames, e.g. aux-brick01.cp.lsst.org.

Italics

reST

renders as

*text in italics*

*aux-brick01.cp.lsst.org*

text in italics

aux-brick01.cp.lsst.org

Bold

bold formatting serves to provide a stronger emphasis on specific ideas or key steps within procedures. However, use sparingly to maintain its impact and avoid overwhelming the readers.

Bold

reST

renders as

1. **Connect to the dimm machine** using ssh.
User and password are stored under DIMM remote
login in the 1Password Operators Vault.
  1. Connect to the dimm machine using ssh. User and password are stored under DIMM remote login in the 1Password Operators Vault.

Monospaced

Utilize double back quotes to generate a monospaced style, appropriate for referencing variables, configuration parameters, and summary states.

Monospaced

reST

renders as

Transition the CSC to ``STANDBY``.
Set the *configuration* ``config`` to ``None``.
Send the CSC back to ``ENABLED``

Transition the CSC to STANDBY. Set the configuration config to None. Send the CSC back to ENABLED

Filenames and paths

Apply this formatting style consistently to represent file and directory names, paths, and SAL scripts throughout the documentation. When referring to SAL scripts, ensure that the full path is included.

Filenames and paths

reST

renders as

:file:`auxtel/standard_scripts/prepare_for/vent.py`

auxtel/standard_scripts/prepare_for/vent.py

Shell Commands

In-line shell commands that are generally compact can be expressed as:

Shell Commands

reST

renders as

:command:`ls -la`

ls -la

Keyboard Shortcuts

When referring to key combinations for specific actions, employ the format below to represent the keys, such as using the ‘+’ symbol to denote simultaneous key presses.

Keyboard shortcuts

reST

renders as

:kbd:`Control+q+A`

Control+q+A

Buttons or text labels in interactive programs

When indicating user interaction with buttons, text labels or tabs (e.g. in LOVE, EUIs), use the formatting shown below.

Buttons in interactive programs

reST

renders as

:guilabel:`Main Axes`

:guilabel:`Power Supply`

:guilabel:`Change to Configuration`

Main Axes

Power Supply

Change to Configuration

Math

The :math: directive can be used in-line or in a separate paragraph.

Math formulae

reST

renders as

:math:`\mu = -2.5 \log_{10}(\mathrm{DN}) + m_0`

\(\mu = -2.5 \log_{10}(\mathrm{DN}) + m_0\)

Headings

Start each section with a heading. Use heading 1 for the page title, heading 2 for the page’s main sections, and headings 3, 4 and 5 for the respectively subsections.

Use title case for headings and tiles: First and last words are always capitalized, as well as all other main words. “Minor words” like articles, coordinating conjunctions and prepositions are lower-case.

######################
Page Title - Heading 1
######################

Heading 2
=========

Heading 3
---------

Heading 4
^^^^^^^^^

Heading 5
"""""""""

Table of contents

With the directive toctree:: you can organize your content into a coherent hierarchy, mirroring the structure and functionality of a tree data structure.

Improving the flow and readability, the table of content also facilitates seamless navigation as it creates an intuitive sidebar menu to the left, and inserts in-page navigation links.

.. toctree::
    :titlesonly:

   ../Safety/emergency-response-guide
   ../Safety/out-of-hours-support
   license

Code

To markup content or code blocks that readers can easily copy and paste for use elsewhere, utilize the directives below. These directives will appear as separate paragraphs enclosed within a box, making them suitable for longer lines or extensive chunks of code, or to draw focus on crucial information.

Bash prompts and commands

.. prompt:: bash

 mkdir -p hello/world
 cd hello/world

renders as:

mkdir -p hello/world
cd hello/world

SAL scripts configuration - Text

This formatting should be used when detailing the configuration required for a SAL script. Use the parameter :caption: with the name of the SAL script to display it above the block of configuration.

The code-block::text directive can be used to preserve the formatting and spacing of text. This feature is particularly useful when displaying content that relies on precise spacing, layout or format, such as code snippets, structured data, or formatted text excerpts.

.. code-block:: text
  :caption: run_command.py

  component: MTDome
  cmd: stop
  parameters:
      engageBrakes: true
      subSystemIds: 1

renders in HTML as:

run_command.py
 component: MTDome
 cmd: stop
 parameters:
     engageBrakes: true
     subSystemIds: 1

Code blocks

Use the code_block:: python or code_block:: JSON directive to adequately display python or JSON code, respectively. You may also add the parameter :caption:: to this directive to include a title above the code.

.. code-block:: python

  large_file_object = await remote.evt_largeFileObjectAvailable.aget(timeout=5)

  print(large_file_object.url)

will be displayed as, in python language:

large_file_object = await remote.evt_largeFileObjectAvailable.aget(timeout=5)

print(large_file_object.url)
.. code-block:: JSON

  {
          "name": "auxtel/take_image_latiss.py",
          "standard": true,
          "parameters": {
              "image_type": "FLAT",
              "filter": "SDSSr_65mm",
              "grating": "empty_1",
              "reason": "daily_sflat",
              "exp_times": [
                  0.5,
                  0.5,
                  12.8,
                  12.8,
              ]
          }
      }

is displayed in HTML like:

{
        "name": "auxtel/take_image_latiss.py",
        "standard": true,
        "parameters": {
            "image_type": "FLAT",
            "filter": "SDSSr_65mm",
            "grating": "empty_1",
            "reason": "daily_sflat",
            "exp_times": [
                0.5,
                0.5,
                12.8,
                12.8
            ]
        }
    }

Images and other media

Images must be stored in the ./_static/ directory within your working directory, in PNG or GIF formats. Use the ..figure:: directive and always include a descriptive caption for each figure.

.. figure:: ./_static/Snow_Rubin.png
  :name: Your figure

  This is the caption for this snowy image of Rubin Observatory.

will show:

../_images/Snow_Rubin.png

This is the caption for this snowy image of Rubin Observatory.

Tables

The .. list-table:: directive facilitates the creation of tables in your docs. Asterisks indicate each row, and hyphens denote each column (* and - must be aligned, respectively).

.. list-table:: Title
 :widths: 25 25 25
 :header-rows: 1

 * - Heading: row 1, column 1
   - Heading: row 1, column 2
   - Heading: row 1, column 3
 * - Row 2, column 1
   - (Even if the content is empty must be accounted for)
   - Row 2, column 3
 * - Row 3, column 1
   - Row 3, column 2
   - Row 3, column 3
Title

Heading: row 1, column 1

Heading: row 1, column 2

Heading: row 1, column 3

Row 2, column 1

(Even if the content is empty each cell must be accounted for)

Row 2, column 3

Row 3, column 1

Row 3, column 2

Row 3, column 3

Notes

Use these to make specific information stand out from the surrounding text, either to convey critical content or to draw attention to certain aspects of the document. Use admonitions sparingly. There is some evidence that readers skip them.

.. warning::

  Critical information

.. caution:

  Proceed carefully.

.. note::

  A note looks like this.

.. tip::

  Maybe useful.

.. admonition:: Personalized Title

  This is how an admonition looks like. Do you like it?

Warning

Critical information

Caution

Proceed carefully.

Note

A note looks like this.

Tip

Maybe useful.

Personalized Title

This is how an admonition looks like. Do you like it?

Lists

Ordered Lists

Use hash symbols for numbered lists:

#. Step 1

#. Step 2

   #. Step 2.1

   #. Step 2.2

   #. Step 2.3

#. Step 3

   #. Step 3.1

#. Step 4
  1. Step 1

  2. Step 2

    1. Step 2.1

    2. Step 2.2

    3. Step 2.3

  3. Step 3

    1. Step 3.1

  4. Step 4

Unordered Lists

Use asterisks for bulleted lists:

* one

* two

* three

* four
  • one

  • two

  • three

  • four

Diagrams

Uses Mermaid directive to generate engaging and visually appealing conceptual diagrams by using plain text.

.. mermaid::

 flowchart LR
   Checkout(Daytime Checkout)
   Checkout --> C(Calibrations)
   C --> V(Venting)
   V --> S(On-Sky)
   Checkout --> V
   Checkout --> S
        flowchart LR
  Checkout(Daytime Checkout)
  Checkout --> C(Calibrations)
  C --> V(Venting)
  V --> S(On-Sky)
  Checkout --> V
  Checkout --> S