Other reST directives

Table of contents

You can create a table of contents with the sections. Use :local: to create a table with only subsections of the current section. Otherwise, it will cover the whole file. Title is optional. Example:

.. contents:: `Table of contents`
   :depth: ‹number›
   :local:

Warning

reST table of contents is limited to the file. The table of contents from Sphinx covers multiple documents.

Images and figures

To include an image in your docs, you only need to use the image directive

.. image:: /_static/myimage.png

Usually, you place your images inside the _static folder under the source folder of your documentation. This folder will be copied when building HTML output, so images can be fetched from a server.

There are also a number of options you can use to tweak your image:

.. image:: /_static/myimage.png
   :height: 100px
   :width: 200 px
   :scale: 50 %
   :alt: alternate text
   :align: right

The figure directive an extension of the image one, enabling to add an optional caption and legend to your image:

.. figure:: /_static/myimage.png

   This is the caption.

   The legend consists of all elements after the caption.

Substituions

Substituions can be done by:

.. |name| replace:: text for *replacing*

Any |name| will be replaced by the text.

Substituions can also be done for images:

.. |caution| image:: warning.png
             :alt: Warning!

As reST does not support nested inline markup, substitutions are used in combination with the “replace” directive to create a reference with styled text.

E.g. to add bold to text in an hyperlink:

I recommend you try |Python|_.

.. |Python| replace:: Python, *the* best language around
.. _Python: http://www.python.org/

I recommend you try Python, the best language around.

E.g. to have an hyperlink with abbreviation:

I recommend you try |py|_.

.. |py| replace:: :abbr:`py (Python)`
.. _py: http://www.python.org/

I recommend you try py.

Topic

a topic

is a self-contained idea that is separate from the flow of the document

Example:

.. topic:: title

   the body is separated
   by a blank line

Admonitions

How the different admonitions are displayed depends on the themes. Not all themes support all of the admonitions. The most common ones are the first ones.

.. warning::
   warning

Warning

warning

 
.. note::
   note

Note

note

 
.. error::
   error

Error

error

 
.. hint::
   hint

Hint

hint

 
.. attention::
   attention!

Attention

attention!

 
.. caution::
   caution

Caution

caution

 
.. danger::
   danger!!

Danger

danger!!

 
.. important::
   important

Important

important

 
.. tip::
   tip

Tip

tip

Raw

The raw directive can be used to include non-reST data.

.. raw:: html

   raw <b>html</b> <i>code</i>
raw html code

There is also a raw role (inline) that can be used with the Role to have inline non-reST data. Find an example below

Role

The role directive can be used to create new roles and to register them. E.g. .. role:: custom creates a new role, named custom which can be used as :custom:`some text`.

An interesting feature is that roles can inherit from a base role:

.. role::<new role>(<base role>)
   <directives>

For example, we can create a role for inline HTML:

.. role:: raw-html(raw)
   :format: html

and use it to include inline HTML code:

line :raw-html:`<br/>` break

line
break

Todo

Compound paragraph, Parsed literal block, Class, Container