rusty.regxlist – List regular expression matching entries

Platforms: Unix, Windows

New in version 0.2.0.

Features

Regxlist (a.k.a regular expression list) is a directive that can create a bullet list from all the document entries matching with the defined regular expression.

The directive is a spin-off from rusty.rolelist – List document roles -directive, but instead of matching the roles, the regxlist can list any entries matching with regular expression rule. This might be the wanted situation in some of the use cases.

Example

The initial reason for writing the rusty.rolelist – List document roles -directive was the requirement to generate list of fixes and features listed in the changelog/release notes. After completing the rolelist it was noticed that role definition may not always be available/wanted. To provide alternative solution, regxlist directive was created.

Regxlist is handy both listing bug fixes and for example picking the action points from the meeting memos. Consider following example:

Source document

First example is an imaginary release notes where features and bug fixes are retrieved from the complete changelog.

This is an example document that uses the ``regxlist`` directive. One of the 
most obvious use cases is the release notes and generating the list of bug
fixes.
 
**Release X**

Features:

  .. regxlist:: Added:\s*(.*)
     :siblings:
     :levelsup: 2
     :template: FEAT: ${0}

Bug fixes:

  .. regxlist:: Fixed (#\d+)(:\s*)(?P<desc>.*)
     :siblings:
     :levelsup: 2
     :template: BUG: ${desc} (${0})
   

All changes:

  - Fixed #2345: Crash while loading invalid document
  - Fixed #3454: Configuration parameter is missing
  - Added: Support for Vista
  - Changed default configuration parameter for ``show_version`` to ``False`` 

Second is an example meeting minutes where there offen are actions points (AP) listed - and by highlighting them they hopefully will be done :)

**Meeting minutes**

:author: Alan Author
:date: 2008-04-21

.. IMPORTANT:: Action points

    .. regxlist:: (AP|-->)+\s+(to)*\s*(?P<name>(\w|\s)+):\s*(?P<desc>(\w|\n|\s)*) 
       :template: ${name}: ${desc}
       :siblings:
       :levelsup: 2
  
- Software building process is still hard, AP Sarah: improve building process
- AP to Tom: document the building process
- Lorem ipsum dolor sit amet, consectetur adipiscing elit. Aenean risus mauris, 
  ultrices id, pretium sed, lobortis in, nisl. Nunc tincidunt neque vel libero 
  hendrerit malesuada.
- Pellentesque dolor augue, dapibus dictum, elementum quis, tincidunt consectetur, 
  nunc. Sed vulputate dolor ut sem. In varius rutrum odio.   
- Release needs to be ready for monday --> Sarah: create official release
- Nunc sit amet neque sed lorem condimentum interdum. In hac habitasse platea dictumst. 
  Vivamus vel libero eget lectus ultrices vestibulum.
- Blah blah...

Output

Output of the processed documents shown above.

---

This is an example document that uses the regxlist directive. One of the most obvious use cases is the release notes and generating the list of bug fixes.

Release X

Features:

• FEAT: Support for Vista

Bug fixes:

• BUG: Crash while loading invalid document (#2345)
• BUG: Configuration parameter is missing (#3454)

All changes:

• Fixed #2345: Crash while loading invalid document
• Fixed #3454: Configuration parameter is missing
• Added: Support for Vista
• Changed default configuration parameter for show_version to False

---

Meeting minutes

author:Alan Author date:2008-04-21

Important

Action points

• Sarah: improve building process
• Tom: document the building process
• Sarah: create official release

• Software building process is still hard, AP Sarah: improve building process
• AP to Tom: document the building process
• Lorem ipsum dolor sit amet, consectetur adipiscing elit. Aenean risus mauris, ultrices id, pretium sed, lobortis in, nisl. Nunc tincidunt neque vel libero hendrerit malesuada.
• Pellentesque dolor augue, dapibus dictum, elementum quis, tincidunt consectetur, nunc. Sed vulputate dolor ut sem. In varius rutrum odio.
• Release needs to be ready for monday –> Sarah: create official release
• Nunc sit amet neque sed lorem condimentum interdum. In hac habitasse platea dictumst. Vivamus vel libero eget lectus ultrices vestibulum.
• Blah blah...

Usage

The complete syntax for the directive:

.. regxlist:: [regexp-rule]
   :template:   [optional, with string value]
   :docwide:    [optional, set to list entries from the whole document. The option *has 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:

regexp-rule

required, string value

Regular expression matching rule. The rule is likely to contain groups that can be then again listed in template:

.. regxlist:: Fixed: (\d\d\d\d)

Note

In a case you need to match text line written on multiple lines, remember to put \n in regexp rule:

.. regxlist:: (?P<desc>(\w|\n|\s)*)

template

optional, string value

String template containing the placeholders. Template is used for formatting the bullet list items texts. The names of place holders comes from the regular expression groups. Both positional and named entries are supported. Consider following regular expression and string:

regexp:  Fixed #(\d+)\s*(?P<desc>.*)

string:  Fixed #23453 compilation fails

Each ( ... ) marks the group. The reference to group can be done with number (positional), starting from number 0. If expression contains the (?P<name> ... ) -part, if can be referenced also with name. Thus, the previous example can be referenced as follows:

${0}    --> 23453
${1}    --> compilation fails
${desc} --> compilation fails

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 a better idea from the option, see the rolelist example. The usage is same with this directive.

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:

To get a better idea from the option, see the rolelist example. The usage is same with this directive.

Note

Regxlist 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

If the text continues to multiple rows, remember to but \n in regexp:

.. regxlist:: BUG: (?P<desc>(.|\n)*)
   :template: $desc
   :siblings:

* BUG: defect description
  that continues to multiple rows
* BUG: single line entry

Module in detail

Regxlist module implements the regxlist directive, which creates a list of entries that matches with the regular expression rule, found from the document:

Fixes in this release:

.. regxlist:: Fixed #\d+:.*
   :template:

class rusty.regxlist.RegXListNode(rawsource='', *children, **attributes)

Custom placeholder node that is replaced in process_regxlist

class rusty.regxlist.RegXListDirective(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)

Implements the directive. The class is registered as a directive in rusty.regxlist.setup().

The structure of the directive:

.. regxlelist:: regexp-rule
   :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 regxlist.process_regxlist(app, doctree)

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

static regxlist.setup(app)

Extension setup, called by Sphinx