This page provides guidance when working with the RST format.

General formatting

Italics - use single asterisks:

*this is in italics*

Bold - use double asterisks:

**this is in bold**

Monospace - use double backticks:

the ``--force`` option may help

Section headers

There are five section headers:

H1 (double equal signs)

H2 (dashes)

H3 (tildes)

H4 (carets)

H5 (dots)

Inline commands

For commands or utilities that are mentioned in a sentence use the :command: directive:

You can type the :command:`juju status` command to get an overview of the

The :command:`openstack` client is the preferred tool.

Linking to an external site

see the `Juju documentation`_ for more details ...


The issue is tracked in bug `LP #1846279`_ ...

<bottom of page>

.. _Juju documentation:

.. _LP #1846279:

Linking to a page in the doc set

Assuming that the destination document is install-maas.rst then in the source document:

In the :doc:`previous section <install-maas>`

The linking is relative. If the destination document was in the parent directory:

In the :doc:`previous section <../install-maas>`

Linking to a location within the current page

Section headers are valid targets by default (implicit links).

Deploy OpenStack


In the `Deploy OpenStack`_ step above

First create a target in order to link to a non-header. Use one of three methods:

In the example_ below

or in `example #5`_

or in the :ref:`Crisis situation <example_crisis>` example


.. _example:


.. _example #5:


.. _example_crisis:

Linking to a location within a page in the doc set

In the source document:

during the :ref:`Install MAAS <install_maas>` step on the previous page

In the destination document insert the target code (typically above a section header):

.. _install_maas:

Install MAAS


Admonishment types and their purpose:




to provide auxiliary information


to inform


to accentuate


to draw special attention to


to warn about potential breakage or data loss


.. <type>::

   text goes here. text goes here. text goes here. text goes here. text goes
   maintain the alignment.

The text is left-aligned with the admonishment type.


.. note::

   This is a note.

Code blocks

Syntax for code blocks:

.. code-block:: <type>

   something goes here

The block is left-aligned with ‘code-block’.

Code block types:




console input


console output

python, bash, yaml

code snippets/scripts


miscellaneous file content

Console input

The following command shows the relations:

.. code-block:: none

   juju status --relations

Console output

Sample output of the last command is:

.. code-block:: console

   Name            Version      Rev    Tracking        Publisher    Notes
   charm           2.8.2        609    latest/stable   canonical✓   classic
   charmcraft      1.4.0        761    latest/stable   canonical✓   classic

Code snippet

This bit of Python will do the trick:

.. code-block:: python

   def anagram(first, second):
    return Counter(first) == Counter(second)

Do not use the bash type for simple command invocations.

Miscellaneous file contents

The contents of file ``/etc/ec2_version`` is:

.. code-block:: ini

   Ubuntu 20.04.1 LTS (Focal)


Add a blank line between each item if any list items are multi-lined.

Unordered list

* First item. Align any word-wrapped lines
  like this.

* Second item

Nested unordered list

For nested lists, indent items so they align with the parent text:

* First item

  * Nested item
  * Nested item

* First item

  * Nested item
  * Nested item

Ordered list

#. First item
#. Second item

Nested ordered list

For nested lists, indent items so they align with the parent text:

#. First item

   #. Nested item
   #. Nested item

#. First item

   #. Nested item
   #. Nested item


To define a term, indent its definition by two spaces:

Charm upgrade
  An upgrade of the charm software which is used to deploy and manage
  OpenStack. This includes charms that manage applications which are not
  technically part of the OpenStack project.

Images and figures

To insert an image or a figure:

.. image:: <relative/path/to/image.png>

See RST documentation on images and figures for details.