*******************************************
ReStructured Text (ReST) Extensions - Usage
*******************************************

This doument explains, how you can write documentation that makes use
of the extended set of text-roles and directives defined in this
package. It also contains a section, that explains how to write
Stylesheets, that make use of these extensions.


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.

*Example: a role*::

  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)`

As you see, a text-role is written following this patter::

  :<rolename>:`<term>`

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

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

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 example might render to something like::

  Added in version 0.11:
    This function was added because of trouble with the core modules.
  
The exact rendering output is of course a matter of the used writer.

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.

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

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

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.



How to write CSS for extended ReST
==================================

The ReST extensions in this package provide additional CSS-classes. If
rendering to HTML, these additional classes will appear in the tags
enclosing the respective entities. There is, however, no guarantee,
that a certain role or directive will be rendered as a `<div>` or
`<p>` or whatever.

If you want to give terms, that have special roles, a different look,
then you can define a CSS-layout for the `role` class like this::

  .role {
     background-color: #00ff00;
  }

All terms that have a special role, provide also the `role` CSS
class.

If you only want a special role to be displayed differently, then you
can use the CSS classname `role-<rolename>`. For example, to render
all text, that has a `func`-role, in blue, you can do the following::

  .role-func {
     color: #0000ff;
  }

The applies also to directives. They too provide a certain
class-attribution, which can be used to render them in a special way::

  .seealso {
    margin-left: 1em;
  }

will indent the 'See also' block by 1em in the HTML output.

The CSS classes for directives are:

  - `highlight`
  - `seealso`
  - `versionadded`
  - `versionchanged`
  - `deprecated`
  - `desc-data`
  - `desc-class`
  - `desc-method`
  - `desc-attribute`
  - `desc-exception`
  - `desc-cmdoption`
  - `desc-envvar`
  - `desc-decribe`

where the first classname is attributed to code fragments that were
marked by the `code-block` or `sourcecode` directive.

