Platforms: Unix, Windows
Rolelist directive provides a generic way to list role entries from current document. While it may not sound interesting, consider following use cases:
Changelog
This use case happens to be initial reason for writing the directive. Consider the changelog/relese notes document, containing a list of new features, bug fixes and other changes. By using a role, each change can be separated for each other, by listing them in a separate list:
============= Release Notes ============= Release X ========= Following issues have been fixed in this release: Fixes .. rolelist:: bug :template: #${value}: ${text} :levelsup: 2 :siblings: New features .. rolelist:: feat :levelsup: 2 :siblings: All changes ----------- * Implemented the requested feature :feat:`Support for python 2.6 <235>` * :feat:`Added support for MacOS` * Fixed issue :bug:`285` * Fixed issue :bug:`Crash on start-up <284>`Note
The bug and ref used in the example are not part of the Sphinx nor docutils but custom roles. These and similar definitions can be added in Sphinx conf.py:
def setup(app): app.add_description_unit('bug', 'bug', 'pair: %s; Defect')
The complete syntax for the directive:
.. rolelist:: [role-name]
:template: [optional, with string value]
:docwide: [optional, set to list roles from non-nested sections - no value]
:levelsup: [optional, set with integer how high to climb in document tree]
:siblings: [optional, controller option to leave out the sibling nodes
when looking for role entries. The option *has no value* and
siblings are *leave out by default*]
Which breaks down as follows:
required, string value
Name of the role entries that are wanted to be listed in the bullet list. See example
optional, string value
String template is used for formatting the bullet list items texts. The supported keywords are:
The keywords are marked with notation: $keyword or ${keyword}. The following example is the default template, as the option is optional:
${text} (${value})
For example with :file: roles you might want to use following template instead of the default one:
.. rolelist:: file
:template: $text
optional, no value
A option flag to search only in nested sections or thorough the whole document. The flag is optional, and the default value is False.
Important
If the directive is in section and docwide is disabled, it cannot see the roles from sibling section - only nested.
optional, positive integer
Levelsup is an option that controls where to retrieve the roles - or how many steps to take up in the document tree nodes, to be exact. The allowed value is positive integer (>= 1) and default value is 0. All the nested nodes are always visited when searching for roles.
Note
If the value for the levelsup is very high, the endresult is the same as with docwide option.
To get the idea from the option, let’s see the example. The levelsup options is required as the values are separate section:
Bug fixes
=========
.. rolelist:: rolename
:levelsup: 1
:template: #${value}: ${text}
:siblings:
Changes
=======
* Fixed :bug:`application crashes <235>` -issue
* Fixed :bug:`application fails to load document <236>` -issue
optional, no value
controller option to take in the sibling nodes when looking for role entries. The option has no value and siblings are left out by default. Example:
Title
=====
Section A
---------
The contents from next section are taken in now that ``siblings`` flag
is set.
.. rolelist:: role
:levelsup: 1
:siblings:
Section B
---------
These entries are found:
* :role:`x`
* :role:`y`
* :role:`z`
Note
Rolelist can find the roles only for the current document - i.e. the documents included by Sphinx doctree are not covered. However, the documents imported by the include directive are read.
If the generated list is empty, the translatable string for having “No entries” item is generated in the list.
Tip
Finding a suitable selector (using options like levelsup and siblings) is sometimes a work of trial and error. This is due the node structure of the docutils.
In a case you don’t get any results into list, try following:
Rolelist module implements the rolelist directive, which can be used for example as follows:
Document with :file:`conf.xml` and :file:`conf.xml`.
The files listed in document:
.. rolelist:: file
IncludeShellDirective implements the directive. The class is registered as a directive in rusty.rolelist.setup().
The structure of the directive:
.. rolelist:: name-of-role
:template: ${text} - ${value}
:docwide:
:levelsup: posint
:siblings: