rusty.rolelist – List document roles

Platforms: Unix, Windows

Features

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

Usage

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:

role-name

required, string value

Name of the role entries that are wanted to be listed in the bullet list. See example

template

optional, string value

String template is used for formatting the bullet list items texts. The supported keywords are:

• value: The contents between '' or <>
• text: The contents of :role:'this if key is defined <key>'

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

docwide

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.

levelsup

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

siblings

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:

1. Set siblings option to directive
2. Try increasing the number in levelsup option

Module in detail

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

class rusty.rolelist.RoleListNode(rawsource='', *children, **attributes)

Custom placeholder node that is replaced in process_rolelist

class rusty.rolelist.RoleListDirective(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)

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:

run()

Implements the directive. In this case, it only stores the given argument and options into custom RoleListNode object - which are taken from there in process_rolelist().

static rolelist.process_rolelist(app, doctree)

Iterates the document nodes once the doctree has been constructed and replaces the custom rolelist node with actual content (a bullet list of selected role)

static rolelist.setup(app)

Extension setup, called by Sphinx