******************************************* 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:: ::`` 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:: .. :: 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 `
` or `

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