Merge pull request #258 from melexis/callback-inspect

Add secondary callback function to inspect items

doc/conf.py

@@ -18,6 +18,7 @@
 from collections import OrderedDict
 
 import mlx.traceability
+from mlx.traceability import report_warning
 from pkg_resources import get_distribution
 
 pkg_version = get_distribution('mlx.traceability').version
@@ -347,12 +348,41 @@
 traceability_json_export_path = '_build/exported_items.json'
 
 def traceability_callback_per_item(name, collection):
+    """Callback function called when an item-directive is being processed.
+
+    Note: attributes, relationships and content (body) of the item can be modified. Sphinx processes each directive
+    in turn, so attributes and relationships added or modified by other directives may not have been processed yet.
+
+    Args:
+        name (str): Name (id) of the item currently being parsed
+        collection (TraceableCollection): Collection of all items that have been parsed so far
+    """
     if name == 'r001':
         item = collection.get_item(name)
         content_str = item.get_content()
         content_str += '\n\nThis line was added by ``traceability_callback_per_item`` and is parsed as |RST| syntax.'
         item.set_content(content_str)
 
+
+def traceability_inspect_item(name, collection):
+    """Callback function called when an item-directive is being rendered.
+
+    Warning: the item cannot not be modified, only inspected.
+
+    Note: At this stage of the documentation build, all directives, e.g. attribute-link and item-link,
+    have been processed and any gaps in your documentation can be exposed by reporting a warning.
+
+    Args:
+        name (str): Name (id) of the item currently being parsed
+        collection (TraceableCollection): Collection of all items that have been parsed so far
+    """
+    if name.startswith('CL-'):
+        item = collection.get_item(name)
+        if 'checked' not in item.attributes:
+            report_warning("traceability_inspect_item: Checklist item {!r} is missing the 'checked' attribute."
+                           .format(name))
+
+
 rst_epilog = ".. |RST|   replace:: :abbr:`RST (reStructuredText)`"
 
 # OrderedDict([('regex', (default, :hover+:active, :visited)), ...])

doc/configuration.rst

@@ -270,40 +270,70 @@ The actual content (RST content with images, formulas, etc) of the item is curre
 Callback per item (advanced)
 ----------------------------
 
+Callback to modify item
+=======================
+
 The plugin allows parsing and modifying documentation objects *behind the scenes* using a callback. The callback
 has this prototype:
 
 .. code-block:: python
 
     def traceability_callback_per_item(name, collection):
-        ''' Custom callback on items
+        """Callback function called when an item-directive is being processed.
+
+        Note: attributes, relationships and content (body) of the item can be modified. Sphinx processes each directive
+        in turn, so attributes and relationships added or modified by other directives may not have been processed yet.
 
         Args:
             name (str): Name (id) of the item currently being parsed
             collection (TraceableCollection): Collection of all items that have been parsed so far
-        '''
+        """
         pass
 
-The callback is executed while parsing the documentation item from your rst-file. Note that not all items are
-available at the time this callback executes, the *collection* parameter is a growing collection of documentation
-objects.
+.. note::
 
-.. _traceability_no_callback:
+    The callback is executed while parsing the documentation item from your RST file. Note that not all items are
+    available at the time this callback executes, the *collection* parameter is a growing collection of documentation
+    objects.
 
-Example of no callback per item
-===============================
+Callback to inspect item
+========================
+
+To overcome the limitation of ``traceability_callback_per_item`` (see note above), a secondary callback function can be
+defined. This function will be called when *rendering* each ``item``-directive. At that moment, all other directive
+types, e.g. ``attribute-link`` and ``item-link``, will have been processed. You can use this callback function to detect
+and warn about any gaps in your documentation but you cannot use it to make any modifications.
+The callback has this prototype:
 
 .. code-block:: python
 
-    traceability_callback_per_item = None
+    def traceability_inspect_item(name, collection):
+        """Callback function called when an item-directive is being rendered.
+
+        Warning: the item cannot not be modified, only inspected.
+
+        Note: At this stage of the documentation build, all directives, e.g. attribute-link and item-link,
+        have been processed and any gaps in your documentation can be exposed by reporting a warning.
+
+        Args:
+            name (str): Name (id) of the item currently being parsed
+            collection (TraceableCollection): Collection of all items that have been parsed so far
+        """
+        pass
+
+.. warning::
+
+    The collection should not be modified, only inspected. Modifying the collection in this step can corrupt it without
+    triggering any warnings.
 
 .. _traceability_optional_mandatory:
 
 Example of requiring certain attributes on an item
 ==================================================
 
 The callback function can modify traceable items, e.g. add attributes. In this example it reports a warning
-when the item doesn't have either the `functional` or `non-functional` attribute:
+when the item doesn't have either the `functional` or `non-functional` attribute defined *at the time its
+``item``-directive is being processed*:
 
 .. code-block:: python
 
@@ -316,6 +346,7 @@ when the item doesn't have either the `functional` or `non-functional` attribute
                            "adding 'functional'".format(name), docname=item.docname, lineno=item.lineno)
             item.add_attribute('functional', '')
 
+
 .. _traceability_config_link_colors:
 
 ------------------------------

mlx/directives/item_directive.py

@@ -30,6 +30,8 @@ def perform_replacement(self, app, collection):
             top_node.append(dl_node)
         # Note: content should be displayed during read of RST file, as it contains other RST objects
         self.replace_self(top_node)
+        if app.config.traceability_inspect_item:
+            app.config.traceability_inspect_item(item_id, collection)
 
     def _process_attributes(self, dl_node, app):
         """ Processes all attributes for the given item and adds the list of attributes to the given definition list.

mlx/traceability.py

@@ -473,9 +473,12 @@ def setup(app):
     # Configuration for exporting collection to json
     app.add_config_value('traceability_json_export_path', None, 'env')
 
-    # Configuration for adapting items through a callback
+    # Configuration for adapting items through a callback while processing the ``item`` directives
     app.add_config_value('traceability_callback_per_item', None, 'env')
 
+    # Configuration for inspecting items through a callback after all directives have been processed
+    app.add_config_value('traceability_inspect_item', None, 'env')
+
     # Create default attributes dictionary. Can be customized in conf.py
     app.add_config_value(
         'traceability_attributes',

tox.ini

@@ -73,8 +73,8 @@ whitelist_externals =
     tee
     mlx-warnings
 commands=
-    mlx-warnings --sphinx --exact-warnings 22 --command make -C doc html
-    mlx-warnings --sphinx --exact-warnings 22 --command make -C doc latexpdf
+    mlx-warnings --sphinx --exact-warnings 23 --command make -C doc html
+    mlx-warnings --sphinx --exact-warnings 23 --command make -C doc latexpdf
 
 [testenv:sphinx-latest]
 deps=
@@ -87,8 +87,8 @@ whitelist_externals =
     tee
     mlx-warnings
 commands=
-    mlx-warnings --sphinx --exact-warnings 22 --command make -C doc html
-    mlx-warnings --sphinx --exact-warnings 22 --command make -C doc latexpdf
+    mlx-warnings --sphinx --exact-warnings 23 --command make -C doc html
+    mlx-warnings --sphinx --exact-warnings 23 --command make -C doc latexpdf
 
 [testenv:coveralls]
 deps =