Platforms: Unix, Windows
New in version 0.2.0.
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.
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...
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:
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)*)
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
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 a better idea from the option, see the rolelist example. The usage is same with this directive.
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:
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
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:
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: