ReStructured Text (ReST) Extensions

Note

The community driven documentation is being migrated to a sphinx-based setup. This tutorial needs to be updated accordingly.

Write documentation that makes use of the extended set of text-roles and directives available on this web site.

How to write docs with extended ReST

Before you proceed, you should be familiar with the standard roles and directives provided by the standard docutils package.

Primers are available all over the net. The page:

http://docutils.sourceforge.net/rst.html

might serve as a starting point.

The extensions of this package provide additional docutils roles and directives, that are related to API entities like functions, classes etc.

Using Roles

Roles are written by enclosing a role-keyword in colons (‘:’) followed by a term that is enclosed in backticks:

:<rolename>:`<term>`

In the rendered document, the rolename should disappear and the term itself be rendered in a special fashion.

Example: a role:

Here we talk about the function :func:`my_function`

This renders as:

Here we talk about the function my_function()

In this example, the func role is used to express that my_function is a function name. You can also use whitespaces in the term:

Example: role-term with whitespace:

A more elaborated description: :func:`my_function(param1, param2)`

which renders as:

A more elaborated description: my_function(param1, param2)()

There are many more roles than only the func role defined in this package. Please see README.txt for a complete list.

Using Directives

Directives are used to mark a whole block of text as special. Their general syntax is as follows:

.. <directive-name>:: <directive-header>

   <text-block>

It is very important, that the text block is indented. This way, the parser knows that it belongs to the directive.

Example: simple directive:

Normal text.

.. function:: my_func(param1,[ param2=None])

   A function to do something.

   *param1* -- a parameter.

   *param2* -- an optional parameter.

   Use this function with care.

Normal text again.

This will render as:

Normal text.

my_func(param1[, param2=None])

A function to do something.

param1 – a parameter.

param2 – an optional parameter.

Use this function with care.

Normal text again.

In this example the function directive is used to indicate, that a complete function description is given. In the text block you can write, whatever you like, as long as it is indented correctly.

Some directives require a text block (or ‘body’ or ‘content’) to exist. This includes the version-related directives versionadded, versionchanged and deprecated as well as the seealso directive.

Some directives require a heading. This includes the version-related directives, which take the heading as a version number.

Example: `versionadded` directive:

Normal text.

.. versionadded:: 0.11

   This function was added because of trouble with the core modules.

Normal text again.

This renders to:

Normal text.

New in version 0.11: This function was added because of trouble with the core modules.

Normal text again.

You can (and should) nest directives:

Example: nested directives:

Normal text.

.. function:: my_func(param1,[ param2=None])

  A function to do something.

  *param1* -- a parameter.

  *param2* -- an optional parameter.

  Use this function with care.

  .. versionadded:: 0.11

     This function was added because of trouble with the core modules.

Normal text again.

This is rendered as:

Normal text.

my_func(param1[, param2=None])

A function to do something.

param1 – a parameter.

param2 – an optional parameter.

Use this function with care.

New in version 0.11: This function was added because of trouble with the core modules.

Normal text again.

As you can see, nesting is done simply by more indenting parts. Here, the versionadded directive is written as part of the function-description.

Syntax highlighting

Syntax highlighting is enabled by using the sourcecode or code-block directive (both names are aliases), with a language name as ‘heading’:

Example: code block with syntax highlighting:

Normal text.

.. code-block:: python

  class Cave(object):
      pass

Normal text (continued).

This will be rendered as:

Normal text.

class Cave(object):
    pass

Normal text (continued).

In this example python is the option, that tells pygments, the syntax- highlighting engine, that works in background, which type of code you want to be highlighted.

Other supported code types are:

• pycon (Python console sessions, the stuff with >>>)
• pytb (Python tracebacks)
• sh (Bash or other shell scripts)
• bat (DOS/Windoes batch files)
• html (HTML)
• xml (XML)
• css (Cascaded stylesheets)
• js (Javascript, aka ECMA-script)
• c (C-code)
• cpp (C++-code)
• ... dozens of code types more.

A complete list can be found here:

http://pygments.org/docs/lexers/

If you have some kind of code, that is not supported natively, for example a more esoteric configuration file, then you can use ‘text’.

To enable linenumbers, you can use the :linenos option.

Example: Code with linenumbers:

.. code-block:: python
   :linenos:

   class Cave(object):
       pass

This will be rendered as:

class Cave(object):
    pass

Note, that the linenumber are 1-based, i.e. first linenumber will be the number one (not zero).

There are some more directives than only the ones described above defined in this package. Please see README.txt for a complete list.