.. :tabSize=2:indentSize=2:noTabs=true: .. _regxlist: ================================================================= :mod:`rusty.regxlist` -- List regular expression matching entries ================================================================= .. module:: regxlist :platform: Unix, Windows :synopsis: Creates a list from current RST document entries matching with the regular expression rule .. moduleauthor:: Juha Mustonen .. versionadded:: 0.2.0 .. contents:: :local: Features ======== Regxlist (a.k.a :term:`regular expression ` list) is a :term:`directive` that can create a bullet list from all the document entries matching with the defined :term:`regular expression `. The directive is a spin-off from :doc:`rolelist` -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 :ref:`use cases `. .. _regxlist-example: Example ======= The initial reason for writing the :ref:`rolelist` -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. .. literalinclude:: example/regxlist.rst :language: rst Second is an example meeting minutes where there offen are actions points (AP) listed - and by highlighting them they hopefully will be done :) .. literalinclude:: example/memo.rst :language: rst **Output** Output of the processed documents shown above. --------- .. include:: example/regxlist.rst --------- .. include:: example/memo.rst Usage ===== The complete syntax for the directive: .. code-block:: rst .. 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(\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 :term:`regular expression ` and string: .. code-block:: text regexp: Fixed #(\d+)\s*(?P.*) 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 ... )`` -part, if can be referenced *also* with name. Thus, the previous example can be referenced as follows: .. code-block:: text ${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 :ref:`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 :ref:`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: #. Set ``siblings`` option to directive #. Try increasing the number in ``levelsup`` option If the text continues to multiple rows, remember to but ``\n`` in regexp: .. code-block:: rst .. regxlist:: BUG: (?P(.|\n)*) :template: $desc :siblings: * BUG: defect description that continues to multiple rows * BUG: single line entry Module in detail ================ .. automodule:: rusty.regxlist .. autoclass:: rusty.regxlist.RegXListNode .. autoclass:: rusty.regxlist.RegXListDirective :members: .. automethod:: rusty.regxlist.process_regxlist .. automethod:: rusty.regxlist.setup