===================================
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 :func:`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: :func:`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.

  .. 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.

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.

  .. versionadded:: 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.

  .. 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.

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.

  .. code-block:: python

    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:

.. code-block:: python
   :linenos:

   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.