Default¶
Default style is a stricter implementation of legacy_ where the definition item
description is parsed using the DefinitionItem which
follows the rst definition more closely.
For class objects the default renders 5 types of sections:
| Heading | Description | Parse as | Max | Rendered as |
|---|---|---|---|---|
| Attributes | Class attributes and their usage | DefinitionItem | – | Sphinx attributes |
| Arguments | function arguments and type | DefinitionItem | – | Parameters field list |
| Parameters | function arguments and type | DefinitionItem | – | Parameters field list |
| Methods | Class methods with summary | MethodItem | – | Table with links to the methods |
| Notes | Useful notes | paragraph | 1 | Note admonition |
For functions the default renders six types of sections:
| Heading | Description | Parse as | Max | Rendered as |
|---|---|---|---|---|
| Arguments | function arguments and type | DefinitionItem | – | Parameters field list |
| Parameters | function arguments and type | DefinitionItem | – | Parameters field list |
| Returns | Return value | DefinitionItem | – | Unordered list |
| Raises | Raised exceptions | DefinitionItem | – | Unordered list |
| Yields | Yield values | DefinitionItem | – | Unordered list |
| Notes | Useful notes | paragraph | 1 | Note admonition |
Note
All other sections are rendered using the .. rubric:: directive by
default.
layout rules¶
To be able to detect and render the sections properly the docstrings should follow the following rules:
Between the section header and the first section item there can be at most only one empty line.
The end of the section is designated by one of the following:
- The allowed number of items by the section has been parsed.
- Two consecutive empty lines are found.
- The line is not identified as a possible header of the section item.
Hint
Please check the docstring of the specific definition item class to have more information regarding the valid item header format.
Examples¶
Argument section¶
Arguments
---------
inputa : str
The first argument holds the first input!.
This is the second paragraph.
inputb : float : int
The second argument is a float.
the default value is 0.
.. note:: this is an optional value.
Attribute sections¶
Attributes
----------
docstring : list
A list of strings (lines) that holds docstrings. The lines are
changed inplace.
index : int
The zero-based line number of the docstring that is currently
processed.
-
class
Attributes -
docstring= list A list of strings (lines) that holds docstrings
-
index= int The current zero-based line number of the docstring that is proccessed.
-
Returns sections¶
Returns
-------
myvalue : list
A list of important values.
But we need to say more things about it.
-
returns() Returns: myvalue (list) – A list of important values. But we need to say more things about it.
Raises section¶
Raises
------
TypeError
This is the first paragraph of the description.
More description.
ValueError
Description of another case where errors are raised.
-
raises() Raises: - TypeError – This is the first paragraph of the description. More description.
- ValueError – Description of another case where errors are raised.
Method section¶
Methods
-------
extract_fields(indent='', field_check=None)
Extract the fields from the docstring
get_field()
Get the field description.
get_next_paragraph()
Get the next paragraph designated by an empty line.
-
class
MyClass Method Description extract_fields(indent='', field_check=None)Extract the fields from the docstring get_field()Get the field description. get_next_paragraph()Get the next paragraph designated by an empty line.