Section components

Each section is composed into a number of components these components are described below.

Section header

The start of the section is designated with the section header, which is a standard rst header. The underline is however restricted to using only - or =:

Section
-------

and:

Section
=======

Each section header is followed by a section definition block which can be either a list of items or one or more definition items. In general, The number and format of these items depends on the type of section that is currently parsed.

Definition list

Two of the most common formats are described

bellow:

The standard definition item format is based on the item of a variation of the definition list item as it defined in restructured text

+-------------------------------------------------+
| term [ " : " classifier [ " or " classifier] ]  |
+--+----------------------------------------------+---+
   | definition                                       |
   | (body elements)+                                 |
   +--------------------------------------------------+

where <term> is the single word (e.g. my_field) and <definition> is a indented block of rst code. The item header can optionally include the <classifier> attribute. This type of item is commonly used to describe class attributes and function arguments. In this documentation we will refer to this format as variable item to avoid confusion with sphinx directives.

A similar definition item format is the method item where the item header is composed of a function signature:

+------------------------------+
| term "(" [  classifier ] ")" |
+--+---------------------------+---+
   | definition                    |
   | (body elements)+              |
   +-------------------------------+

This item is commonly used to describe provided functions (or methods) and thus is referred to as the method item. The <classifier> in this case is a list of arguments as it appears in the signature and <definition> the method summary (one sentence). All method fields should be separated by a single empty line.

Paragraph

Instead of a list of items the section can contain a paragraph:

+-------------------------+
| definition              |
| (body elements)+        |
+-------------------------+

This type of field is used for information sections like Notes.

Note

Currently the <paragraph> is a single unindented block with no empty lines. However, this will probably should change in future versions of RefactorDoc.