RST also includes directives. A directive is written in a block that starts with ... A directive may contain content that's indented. It may also have parameters. RST has a large number of directives that we might use to create a more sophisticated document. For docstring preparation, we'll rarely use more than a few of the directives available. The directives are open-ended; tools such as Sphinx will add directives to produce more sophisticated documentation.

Three commonly used directives are image, csv-table, and math. If we have an image that should be part of our document, we might include it in the following way:

..  image:: media/some_file.png 
    :width: 6in 

We named the file media/some_file.png. We also provided it with a width parameter to ensure that our image fits our document page layout. There are a number of other parameters that we can use to adjust the presentation of an image.

• :align:: We can provide keywords such as top, middle, bottom, left, center, or right. This value will be provided to the align attribute of the HTML <img> tag.
• :alt:: This is the alternative text for the image. This value will be provided to the alt attribute of the HTML <img> tag.
• :height:: This is the height of the image.
• :scale:: This is a scale factor that can be provided instead of the height and width.
• :width:: This is the width of the image.
• :target:: This is a target hyperlink for the image. This can be a complete URI or an RST reference of the `name`_ form.

For the height and width, any of the length units available in CSS can be used. These include em (the height of the element's font), ex (the height of the letter x), px (pixels), as well as absolute sizes; in, cm, mm, pt (point), and pc (pica).

We can include a table in our document in the following manner:

..  csv-table:: Suits 
    :header: symbol, name 
     
    "'♣'", Clubs 
    "'♦'", Diamonds 
    "'♥'", Hearts 
    "'♠'", Spades 

This allows us to prepare data that will become a complex HTML table in a simple CSV notation. We can have a more complex formula using the math directive:

..  math:: 

    	extbf{O}(2^n)

This allows us to write larger LaTeX math to create a separate equation. These can be numbered and cross-referenced as well. Note the blank lines and the indentation around the formula; these are essential for helping the RST tools locate the relevant text to be treated as math.

There are a number of other RST markup techniques. In the next section, we'll suggest some ways to learn how to annotate text so that it is properly formatted and indexed.