Metadata-Version: 1.1
Name: mlx.traceability
Version: 3.3.0
Summary: Sphinx traceability extension (Melexis fork)
Home-page: https://github.com/melexis/sphinx-traceability-extension
Author: Stein Heselmans
Author-email: teh@melexis.com
License: GNU General Public License v3 (GPLv3)
Description: .. image:: https://img.shields.io/badge/License-GPL%20v3-blue.png
            :target: https://www.gnu.org/licenses/gpl-3.0
            :alt: GPL3 License
        
        .. image:: https://badge.fury.io/py/mlx.traceability.png
            :target: https://badge.fury.io/py/mlx.traceability
            :alt: Pypi packaged release
        
        .. image:: https://travis-ci.org/melexis/sphinx-traceability-extension.png?branch=master
            :target: https://travis-ci.org/melexis/sphinx-traceability-extension
            :alt: Build status
        
        .. image:: https://img.shields.io/badge/Documentation-published-brightgreen.png
            :target: https://melexis.github.io/sphinx-traceability-extension/
            :alt: Documentation
        
        .. image:: https://codecov.io/gh/melexis/sphinx-traceability-extension/coverage.png
            :target: https://codecov.io/gh/melexis/sphinx-traceability-extension
            :alt: Code Coverage
        
        .. image:: https://codeclimate.com/github/melexis/sphinx-traceability-extension/badges/gpa.png
            :target: https://codeclimate.com/github/melexis/sphinx-traceability-extension
            :alt: Code Climate Status
        
        .. image:: https://requires.io/github/melexis/sphinx-traceability-extension/requirements.png?branch=master
            :target: https://requires.io/github/melexis/sphinx-traceability-extension/requirements/?branch=master
            :alt: Requirements Status
        
        .. image:: https://img.shields.io/badge/contributions-welcome-brightgreen.png?style=flat
            :target: https://github.com/melexis/sphinx-traceability-extension/issues
            :alt: Contributions welcome
        
        ==========================
        Sphinx Traceability plugin
        ==========================
        
        Sphinx plugin that allows defining documentation items and relations between those items. Can be used
        as a requirements management tool for e.g. ISO26262 projects.
        
        .. contents:: `Contents`
            :depth: 2
            :local:
        
        .. _traceability_goal:
        
        ----
        Goal
        ----
        
        Define documentation items which can be linked to each other. E.g. define requirements which can be derived from
        other requirements, or linked to design items and test case descriptions.
        
        Every item is an object in the documentation, which can have different relations to other objects in the documentation.
        Documentation objects can be spread in different documents.
        
        Two kinds of relationships exist:
        
        - Internal relationships: Relationships between objects of the documentation (items). Once a (forward) relationship
          from item A to item B is defined, the reverse relationship from item B to item A is
          automatically generated by the plugin.
        
        - External relationships: Relationship from an object of the documentation (item), to an external reference (url of
          e.g. an external tool). As no item B exists, the reverse relationship is also not defined.
        
        Relationship are configurable.
        
        The plugin can generate
        
        - rendered versions of the defined documentation objects
        - flat lists of documentation objects
        - traceability matrices between objects
        
        .. _traceability_installing:
        
        ----------
        Installing
        ----------
        
        .. code-block:: bash
        
            pip3 install mlx.traceability
        
        .. _traceability_config:
        
        -------------
        Configuration
        -------------
        
        The *conf.py* file contains the documentation configuration for your project. This file needs to be equipped in order
        to configure the traceability plugin.
        
        First the plugin needs to be enabled in the *extensions* variable:
        
        .. code-block:: bash
        
            extensions = [
                'mlx.traceability',
                ...
            ]
        
        Second the path to the static javascript assets needs to be added to the sphinx ``html_static_path``
        variable.
        
        .. code-block:: bash
        
            import os
            import mlx.traceability
        
            html_static_path = [os.path.join(os.path.dirname(mlx.traceability.__file__), 'assets')]
        
        .. _traceability_config_attributes:
        
        Valid attributes
        ================
        
        Python variable *traceability_attributes* can be defined in order to override the
        default configuration of the traceability plugin.
        It is a *set* of attribute pairs: the *key* is the name of the attribute (can only be lowercase),
        while the *value* holds the regular expression to which the attribute-value should comply.
        
        Example of attributes and their regular expression:
        
        .. code-block:: python
        
            traceability_attributes = {
                'value': '^.*$',
                'asil': '^(QM|[ABCD])$',
            }
        
        .. _traceability_config_attribute2string:
        
        Stringification of attributes
        ================================
        
        Python variable *traceability_attribute_to_string* can be defined in order to override the
        default configuration of the traceability plugin.
        It is a *set* of attribute stringifications: the *key* is the name of the attribute, while
        the *value* holds the string representation (as to be rendered in html) of the attribute name.
        
        Example of attribute stringification:
        
        .. code-block:: python
        
            traceability_relationship_to_string = {
                'value': 'Value',
                'asil': 'ASIL',
            }
        
        .. _traceability_config_relations:
        
        Valid relationships
        ===================
        
        Python variable *traceability_relationsips* can be defined in order to override the
        default configuration of the traceability plugin.
        It is a *set* of relationship pairs: the *key* is the name of the forward relationship, while the *value* holds the
        name of the corresponding reverse relationship. Both can only be lowercase.
        
        Relationships with prefix *ext_* are treated in a different way: they are handled as external relationships and don't
        need a reverse relationship.
        
        Example of internal and external relationship pairs:
        
        .. code-block:: python
        
            traceability_relationships = {
                'validates': 'validated_by',
                'ext_polarion_reference': ''
            }
        
        .. _traceability_config_relation2string:
        
        Stringification of relationships
        ================================
        
        Python variable *traceability_relationship_to_string* can be defined in order to override the
        default configuration of the traceability plugin.
        It is a *set* of relationship stringifications: the *key* is the name of the (forward or reverse) relationship, while
        the *value* holds the string representation (as to be rendered in html) of the relationship.
        
        Example of internal and external relationship stringification:
        
        .. code-block:: python
        
            traceability_relationship_to_string = {
                'validates': 'Validates',
                'validated_by': 'Validated by',
                'ext_polarion_reference': 'Polarion reference'
            }
        
        .. _traceability_config_ext2url:
        
        External relationship to URL translation
        ========================================
        
        External relationships need to be translated to URL's while rendering. For each defined external relationship,
        an entry in the Python *set* named *traceability_external_relationship_to_url* is needed. The URL generation
        is templated using the *fieldx* keyword, where x is a number incrementing from 1 onwards for each value in the URL
        that needs to be replaced.
        
        Example configuration of URL translation of external relationship using 2 fields:
        
        .. code-block:: python
        
            traceability_external_relationship_to_url = {
                'ext_polarion_reference': 'https://melexis.polarion.com/polarion/#/project/field1/workitem?id=field2',
            }
        
        .. _traceability_config_render_relations:
        
        Rendering of relationships per documentation object
        ===================================================
        
        When rendering the documentation objects, the user has the option to include/exclude the rendering of the
        relationships to other documentation objects. This can be done through the Python variable
        *traceability_render_relationship_per_item* which is *boolean*: a value of ``True`` will enable rendering
        of relationships per documentation object, while a value of ``False`` will disable this rendering.
        
        Example configuration of enable rendering relationships per item:
        
        .. code-block:: python
        
            traceability_render_relationship_per_item = True
        
        Rendering of attributes per documentation object
        ================================================
        
        The rendering of attributes of documentation objects can be controlled through the *boolean* variable
        *traceability_render_attributes_per_item*: rendering of attributes is enabled by setting it to ``True`` (the default)
        while a value of ``False`` will prevent the attribute list from being rendered.
        
        Example configuration of disabling per item attribute rendering:
        
        .. code-block:: python
        
            traceability_render_attributes_per_item = False
        
        Ability to collapse the list of relationships and attributes per documentation object
        =====================================================================================
        
        A button is added to each documentation object that has rendered relationships and/or attributes to be able to show and
        hide these traceability links. The *boolean* configuration variable *traceability_collapse_links* allows selecting
        between hiding and showing the list of links for all items on page load: setting its value to ``True`` results in the
        list of links being hidden (collapsed) on page load, while a value of ``False`` results in the list being shown
        (uncollapsed)(the default).
        
        Example configuration of hiding the traceability links on page load:
        
        .. code-block:: python
        
            traceability_collapse_links = True
        
        .. _traceability_config_no_captions:
        
        No captions
        ===========
        
        By default, the output will contain hyperlinks to all related items. By default, the caption for the target
        item is displayed for each of the related items. The captions can be omitted at configuration level (see
        this section) and at directive level (see e.g. `traceability_usage_item_matrix`_).
        
        No captions for item
        --------------------
        
        Example configuration of disabling the rendering of captions on item:
        
        .. code-block:: python
        
            traceability_item_no_captions = True
        
        No captions for item-list
        -------------------------
        
        Example configuration of disabling the rendering of captions on item-list:
        
        .. code-block:: python
        
            traceability_list_no_captions = True
        
        No captions for item-matrix
        ---------------------------
        
        Example configuration of disabling the rendering of captions on item-matrix:
        
        .. code-block:: python
        
            traceability_matrix_no_captions = True
        
        No captions for item-attributes-matrix
        --------------------------------------
        
        Example configuration of disabling the rendering of captions on item-attributes-matrix:
        
        .. code-block:: python
        
            traceability_attributes_matrix_no_captions = True
        
        No captions for item-tree
        -------------------------
        
        Example configuration of disabling the rendering of captions on item-tree:
        
        .. code-block:: python
        
            traceability_tree_no_captions = True
        
        .. _traceability_config_export:
        
        Export
        ======
        
        The plugin allows exporting the documentation items.
        
        Export to JSON
        --------------
        
        As a preliminary test feature, the plugin allows to export the documentation items to a JSON database. The feature
        can be enabled by setting the configuration to your JSON-file to export to. Note, the JSON-file is overwritten
        (not appended) on every build of the documentation.
        
        .. code-block:: python
        
            traceability_json_export_path = '/path/to/your/database.json'
        
        As a preliminary feature, the database only contains per documentation item:
        
        - the id,
        - the caption,
        - the document name and line number,
        - the relations to other items.
        
        The actual content (RST content with images, formulas, etc) of the item is currently not stored.
        
        .. note:: Requires sphinx >= 1.6.0
        
        .. _traceability_config_callback:
        
        Callback per item (advanced)
        ============================
        
        The plugin allows parsing and modifying documentation objects 'behind the scenes' using a callback. The callback
        has this prototype:
        
        .. code-block:: python
        
            def traceability_my_callback_per_item(name, all_items):
                '''
                Custom callback on items
        
                :param name: Name (id) of the item currently being parsed
                :param all_items: Set of all items that are parsed so far
                '''
                return
        
        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 *all_items* parameter is a growing set of documentation objects.
        
        Example of no callback per item:
        
        .. code-block:: python
        
            traceability_callback_per_item = None
        
        .. _traceability_config_link_colors:
        
        Custom colors for linked items
        ==============================
        
        The plugin allows customization of the colors of traceable items in order to easily recognize the type of item which is
        linked to. A dictionary in the configuration file defines the regexp, which is used to match item IDs, as key and a
        tuple of 1-3 color defining strings as value. The first color is used for the default hyperlink state, the second color
        is used for the hover and active states, and the third color is used to override the default color of the visted state.
        Leaving a color empty results in the use of the default html style. The top regexp has the highest priority. To support
        Python versions lower than 3.7, we use an :code:`OrderedDict` to have a deterministic order for prioritizing regexes.
        
        .. code-block:: python
        
            traceability_hyperlink_colors = OrderedDict([
                (r'^(RQT|r[\d]+', ('#7F00FF', '#b369ff')),
                (r'^[IU]TEST_REP', ('rgba(255, 0, 0, 1)', 'rgba(255, 0, 0, 0.7)', 'rgb(200, 0, 0)')),
                (r'^[IU]TEST', ('goldenrod', 'hsl(43, 62%, 58%)', 'darkgoldenrod')),
                (r'^SYS_', ('', 'springgreen', '')),
                (r'^SRS_', ('', 'orange', '')),
            ])
        
        .. _traceability_default_config:
        
        Default config
        ==============
        
        The plugin itself holds a default config that can be used for any traceability documenting project:
        
        .. code-block:: python
        
            traceability_callback_per_item = None
            traceability_attributes = {
                'value': '^.*$',
                'asil': '^(QM|[ABCD])$',
                'aspice': '^[123]$',
                'status': '^.*$',
                'result': '(?i)^(pass|fail|error)$'
            }
            traceability_attribute_to_string = {
                'value': 'Value',
                'asil': 'ASIL',
                'aspice': 'ASPICE',
                'status': 'Status'
            }
            traceability_relationships = {
                'fulfills': 'fulfilled_by',
                'depends_on': 'impacts_on',
                'implements': 'implemented_by',
                'realizes': 'realized_by',
                'validates': 'validated_by',
                'trace': 'backtrace',
                'ext_toolname': ''
            }
            traceability_relationship_to_string = {
                'fulfills': 'Fulfills',
                'fulfilled_by': 'Fulfilled by',
                'depends_on': 'Depends on',
                'impacts_on': 'Impacts on',
                'implements': 'Implements',
                'implemented_by': 'Implemented by',
                'realizes': 'Realizes',
                'realized_by': 'Realized by',
                'validates': 'Validates',
                'validated_by': 'Validated by',
                'trace': 'Traces',
                'backtrace': 'Back traces',
                'ext_toolname': 'Reference to toolname'
            }
            traceability_external_relationship_to_url = {
                'ext_toolname': 'http://toolname.company.com/field1/workitem?field2'
            }
            traceability_render_relationship_per_item = False
        
        This default configuration, which is built into the plugin, can be overridden through the conf.py of your project.
        
        For Melexis.SWCC silicon projects, the SWCC process holds a default configuration in the *config/traceability_config.py*
        file. For each of the above configuration variables, the default configuration file holds a variable with *swcc_*
        prefix. Taking the default configuration is as easy as assiging the above configuration value with the *swcc_* variable.
        Overriding a configuration is as easy as assigning your own values to a configuration value.
        
        Example of accepting default configuration for relationships, while disabling (override) rendering of relationships
        per documentation object:
        
        .. code-block:: python
        
            sys.path.insert(0, os.path.abspath('<path_to_process_submodule>/config'))
        
            from traceability_config import swcc_traceability_attributes
            from traceability_config import swcc_traceability_relationships
            from traceability_config import swcc_traceability_relationship_to_string
        
            traceability_attributes = swcc_traceability_attributes
            traceability_relationships = swcc_traceability_relationships
            traceability_relationship_to_string = swcc_traceability_relationship_to_string
            traceability_render_relationship_per_item = False
        
        .. _traceability_usage:
        
        -----
        Usage
        -----
        
        .. _required_sphinx_options:
        
        Required sphinx options
        =======================
        
        By default, sphinx (*sphinx-build*) performs an incremental build: it only parses the changed files and generates
        new output for changed files. As this plugin generates automatic reverse relations, the incremental build option
        of sphinx needs to be disabled. This can be done using the *-E* option:
        
        .. code-block:: bash
        
            sphinx-build -E <other_options>
        
        :Rationale: The plugin allows linking documentation items through relations. If a forward relation from *item-A*
                    (in *document-a.rst*) to *item-B* (in *document-b.rst*) is created, the reverse relations from
                    *item-B* to *item-A* is automatically created. With incremental builds, documents only get re-generated
                    when they are changed. This means the automatic reverse relation cannot be created if that *document-B*
                    was not touched.
                    By disabling incremental builds, it is made sure every document is updated (with automatic reverse
                    relations) on every re-build.
        
        The plugin assumes incremental builds are disabled, as this makes the implementation of the plugin much easier.
        
        .. _traceability_usage_item:
        
        Defining documentation items
        ============================
        
        Documentation items can be defined using the *item* directive, specifying:
        
        - the name (id) of the documentation item
        - caption or short description of the documentation item
        - attributes for the documentation item
        - internal/external relationships to other documentation items (details in next paragraph)
        - content of documentation item including any rst content including text, images, formulas, code-blocks, etc.
        
        .. code-block:: rest
        
            .. item:: SWRQT-MY_FIRST_REQUIREMENT Caption of my first requirement
                :value: 400
                :status: Approved
                :validated_by: ITEST-MY_FIRST_INTEGRATION_TEST
                :ext_polarion_reference: project_x:workitem_y
                :nocaptions:
        
                According to the Polarion reference, the software **shall** implement my first requirement.
        
        Attributes can be added to the item, using the `configured attribute keys <traceability_default_config>`_
        (e.g. *value* in the above example). The content of the attribute is treated as a single string and should
        match the regular expression in configuration.
        
        The relations to other documentation items can be specified as:
        
        - a space-separated list of item ID's, or
        - items can be linked to on a newline (tabulated)
        
        .. code-block:: rest
        
            .. item:: SWRQT-MY_FIRST_REQUIREMENT Caption of my first requirement
                :validated_by:
                    ITEST-MY_FIRST_INTEGRATION_TEST
                    ITEST-MY_SECOND_INTEGRATION_TEST
        
        The output will contain hyperlinks to all related items. By default, the caption for the target item is displayed for
        each of these related items. With the option *nocaptions* these captions can be omitted.
        
        .. _adding_relations:
        
        Adding relations outside of the item definitions
        ================================================
        
        In some cases, it's useful to add relations outside of the definition of the items
        involved. In that case, you can use the ``item-link`` directive as follows:
        
        .. code-block:: rest
        
            .. item-link::
                :sources: RQT1 RQT2
                :targets: TST3 TST4 TST5
                :type: validates
        
        This directive has no representation in the documentation build output. It will
        just add an additional relationship to the items mentioned in ``sources`` and
        ``targets``.
        
        Adding description to attributes
        ================================
        
        Section `traceability_config_attributes`_ explain how attributes can be added to the configuration. It is possible
        to add content to the attributes. A detailed description can be added to an attribute definition:
        
        - The name (id) of the attribute needs to match the configured attribute. This name is not case sensitive.
        - Caption or short description of the attribute.
        - Content of attribute including any rst content including text, images, formulas, code-blocks, etc.
        
        .. code-block:: rest
        
            .. item-attribute:: status The status of a requirement
        
                The status of the requirement explains whether it is *draft*, *under-review*, *approved* or *invalid*.
        
        .. _traceability_usage_item_linking:
        
        Manual link to documentation items
        ==================================
        
        Manual links in RST documentation to any of the documentation items is possible using the *:item:* role:
        
        .. code-block:: rest
        
            For validating the :item:`SWRQT-MY_FIRST_REQUIREMENT`, we plan to use setup x in the y configuration.
        
        .. _traceability_usage_item_list:
        
        Flat list of documentation items
        ================================
        
        A flat list of documentation items can be generated using a Python regular expression filter:
        
        .. code-block:: rest
        
            .. item-list:: All software requirements
                :filter: SWRQT
                :status: Appr
                :nocaptions:
        
        where *SWRQT* (*filter* argument) can be replaced by any Python regular expression. Documentation items matching
        their ID to the given regular expression end up in the list.
        
        where *status* can be replaced by any configured attribute, and *Appr* can be replaced by any Python regular
        expression. Documentation items where the *status* attribute matches the given regular expression end up in the list.
        
        By default, the caption for every item in the list is shown. By providing the *nocaptions* flag, the
        caption can be omitted. This gives a smaller list, but also less details.
        
        .. _traceability_usage_item_attributes_matrix:
        
        Matrix with attributes of documentation items
        =============================================
        
        A matrix listing the attributes of documentation items can be generated using:
        
        .. code-block:: rest
        
            .. item-attributes-matrix:: Attributes for requirements
                :filter: SWRQT
                :status: Appr
                :attributes: status
                :sort: status
                :reverse:
                :transpose:
                :nocaptions:
        
        where the *filter* argument can be replaced by any Python regular expression. Documentation items matching
        their ID to the given regular expression end up in the list.
        
        where *status* can be replaced by any configured attribute, and *Appr* can be replaced by any Python regular
        expression. Documentation items where the *status* attribute matches the given regular expression end up in the list.
        
        where *attributes* argument is a space-separated list of attributes that should be matched in the matrix.
        
        Above arguments can be avoided, or left empty, in which case the table will contain all attributes for all
        documentation items.
        
        Documentation items matching their ID to the given *filter* regular expression end up as rows in the generated table.
        The matching attribute values end up as columns in the generated table. Documentation items
        that don't have a value for a certain attribute will have an empty cell at the corresponding location.
        
        By default, the caption for every item in the table is shown. By providing the *nocaptions* flag, the
        caption can be omitted. This gives a smaller table, but also less details.
        
        By default, items are sorted naturally based on their name. With the *sort* argument it is possible to sort on one
        or more attribute values alphabetically. When providing multiple attributes to sort on, the attribute keys are
        space-separated. With the *reverse* argument, the sorting is reversed.
        
        By default, the attribute names are listed the header row and every item takes up a row. Depending on the number of
        items and attributes it could be better to transpose the generated matrix (swap columns for row) by providing the
        *transpose* flag.
        
        Optionally, the *class* attribute can be specified to customize table output, especially useful when rendering to
        LaTeX. Normally the *longtable* class is used when the number of rows is greater than 30 which allows long tables to
        span multiple pages. By setting *class* to *longtable* manually, you can force the use of this environment.
        
        .. _traceability_usage_item_matrix:
        
        Traceability matrix of documentation items
        ==========================================
        
        A traceability matrix of documentation items can be generated using:
        
        .. code-block:: rest
        
            .. item-matrix:: Requirements to test case description traceability
                :source: SWRQT
                :target: [IU]TEST
                :status: Appr
                :sourcetitle: Software requirements
                :targettitle: Integration and unit test cases
                :type: validated_by
                :nocaptions:
                :stats:
        
        where the *source* and *target* arguments can be replaced by any Python regular expression.
        
        where *status* can be replaced by any configured attribute, and *Appr* can be replaced by any Python regular
        expression. Only documentation items where the *status* attribute matches the given regular expression end up in
        the *source* part of the matrix. The attribute value is **not** used as a filter on the *target* part.
        
        The *type* argument
        is a space-separated list of relationships that should be matched in the matrix. The *sourcetitle* and *targettitle*
        arguments are the titles of the columns in the generated matrix.
        
        Documentation items matching their ID to the given *source* regular expression end up in the left column of the
        generated table. Documentation items matching their ID to the given *target* regular expression with a matching
        relationship (see *type* argument) will end up in the right column of the generated table.
        
        By default, the caption for every item in the table is shown. By providing the *nocaptions* flag, the
        caption can be omitted. This gives a smaller table, but also less details.
        
        By providing the *stats* flag, some statistics (coverage percentage) are calculated and displayed above the
        matrix. The plugin counts the number of items having a target item in the target-column (=covered or allocated),
        and the number of items having no target in the target-column (=not covered or allocated). And calculates a
        coverage/allocation percentage from these counts. If the *stats* flag is not given, this percentage is not
        displayed.
        
        Optionally, the *class* attribute can be specified to customize table output, especially useful when rendering to
        LaTeX. Normally the *longtable* class is used when the number of rows is greater than 30 which allows long tables to
        span multiple pages. By setting *class* to *longtable* manually, you can force the use of this environment.
        
        .. _traceability_usage_2d_matrix:
        
        2D-matrix of documentation items
        ================================
        
        A 2D-matrix of documentation items can be generated using:
        
        .. code-block:: rest
        
            .. item-2d-matrix:: Requirements to test case description traceability
                :source: SWRQT
                :target: [IU]TEST
                :status: Appr
                :hit: x
                :miss:
                :type: validated_by
        
        where the *source* and *target* arguments can be replaced by any Python regular expression.
        
        where *status* can be replaced by any configured attribute, and *Appr* can be replaced by any Python regular
        expression. Only documentation items where the *status* attribute matches the given regular expression end up in
        the *source* part of the matrix. The attribute value is **not** used as a filter on the *target* part.
        
        The *type* argument is a space-separated list of relationships that should be matched in the matrix.
        
        Documentation items matching their ID to the given *source* regular expression end up as columns of the
        generated table. Documentation items matching their ID to the given *target* regular expression end up as
        rows of the generated table. Where source and target items have a matching relationship (see *type* argument)
        an 'x' will be placed in the cell at co-ordinates of source/target.
        
        Captions for items in the 2D table are never shown, as it would give a too heavy loaded table.
        
        Optionally, the *class* attribute can be specified to customize table output, especially useful when rendering to
        LaTeX. Normally the *longtable* class is used when the number of rows is greater than 30 which allows long tables to
        span multiple pages. By setting *class* to *longtable* manually, you can force the use of this environment.
        
        .. _traceability_usage_item_tree:
        
        Documentation items tree-view
        =============================
        
        Note: this feature is not supported when building for latex/pdf.
        
        A tree-view of documentation items can be generated using:
        
        .. code-block:: rest
        
            .. item-tree:: Requirements tree view
                :top: SWRQT
                :top_relation_filter: depends_on
                :status: Appr
                :type: impacts_on validated_by
                :nocaptions:
        
        where the *top* argument can be replaced by any Python regular expression. The *top_relation_filter* and *type*
        arguments are space-separated lists of relationships.
        
        The directive generates an expandable tree of links to documentation items. A nested bullet list is generated
        with, at the top level, the top level documentation items. These are the ones matching their ID to the *top*
        regular expression and not having any relation of *top_relation_filter* kind to a documentation item matching the same
        *top* regular expression against its ID.
        
        The *status* can be replaced by any configured attribute, and *Appr* can be replaced by any Python regular
        expression. Only documentation items where the *status* attribute matches the given regular expression end up in
        the tree.
        
        Going deeper down this nested bullet list, the item's relationships are checked: if there is a *type*
        relationship (*type* is a space-separated list of relationships), it gets added as a one-level-deeper item in
        the nested bullet list. This action is repeated recursively.
        
        .. warning::
        
            The *type* is a list of relationships, which cannot hold the forward and reverse relationship of a pair.
            This would give endless repetition of the same nesting and endless recursion in Python. The plugin
            checks the *item-tree* directives for this mistake!
        
        By default, the caption for every item in the tree is shown. By providing the *nocaptions* flag, the
        caption can be omitted. This gives a smaller tree, but also less details.
        
        .. _traceability_usage_piechart:
        
        Pie chart of documentation items
        ================================
        
        A pie chart of documentation items can be generated using:
        
        .. code-block:: rest
        
            .. item-piechart:: Test coverage of requirements with report results
                :id_set: RQT TEST TEST_REP
                :label_set: uncovered, covered, executed
                :result: error, fail, pass
        
        where the *id_set* arguments can be replaced by any Python regular expression. The *label_set* and *result* arguments
        are comma-separated lists.
        
        The *id_set* is a list of item IDs with at least two and at most three item IDs. The first item ID is the source, the
        second item ID is the target, and the optional third item ID is the target of the second. Adding a third item ID splits
        up the items with an existing relationship between the first and second ID.
        
        The optional *label_set* holds the string labels for the pie chart. For source items without a relationship to a target
        item, the first label is used. For those with a relationship, but without a relationship between the second and third
        ID, the second label is used. The third label is used for items with both relationships covered. This attribute is
        optional. The labels in the example are the default values.
        
        The optional *result* can be replaced by any configured attribute of the third item ID. Its arguments are possible
        values of this attribute, ordered in priority from high to low. Using this option splits up the slice with the third
        label. In this example an RQT item with multiple TEST items, one with a *fail* and others a *pass* as *result* value in
        the TEST_REP item, will be added to the *fail* slice of the pie chart.
        
        
        Retrieving checklist values from GitLab/GitHub (advanced)
        =========================================================
        
        The plugin can add an additional attribute to a traceability item if its item ID exists in a checklist inside the
        description of a merge/pull request. Documentation items can be linked to a checklist by defining them with the
        *checklist-item* directive.
        
        .. code-block:: rest
        
            .. checklist-item:: PLAN-UNIT_TESTS Have you added unit tests for regression detection?
        
        This directive gets treated the same as the *item* directive, except that an additional attribute gets added when the
        item's ID exists in the checklist. The attribute's value depends on the status of the checkbox. The plugin queries the
        API of GitLab/GitHub for the description of the configured merge request.
        
        The configuration of this feature is stored in the configuration variable *traceability_checklist*.
        
        .. code-block:: python
        
            traceability_checklist = {
                'private_token': config('PRIVATE_TOKEN'),
                'api_host_name': config('API_HOST_NAME'),
                'project_id': config('PROJECT_ID'),
                'merge_request_id': config('MERGE_REQUEST_ID'),
                'attribute_name': config('TARGET_ATTRIBUTE_NAME'),
                'attribute_to_str': config('TARGET_ATTRIBUTE_TO_STRING'),
                'attribute_values': config('TARGET_ATTRIBUTE_VALUES'),
            }
        
        In this default configuration the variables are fetched from the environment, e.g. by using a ``.env`` file.
        
        .. code-block:: bash
        
            # copy example .env to your .env
            cp doc/.env.example .env
        
            # add env variables by adjusting the template values in .env
        
        - *ATTRIBUTE_NAME* is the identifier of the attribute to be added, e.g. *checked*.
        - *ATTRIBUTE_TO_STRING* is the string representation (as to be rendered in html) of the attribute name, e.g. *Answer*.
        - *ATTRIBUTE_VALUES* are two comma-separated attribute values, e.g. *yes,no*. The first value is used when the checkbox is checked and the second value when unchecked.
        
        A query is sent to the GitLab/GitHub API to retrieve the status of every checkbox in the description of the merge/pull
        request. The traceability item's ID is expected to follow the checkbox directly.
        Example of a valid checklist in Markdown:
        
        .. code-block:: rest
        
            - [x] PLAN-UNIT_TESTS Have you added unit tests for regression detection?
            - [ ] PLAN-PACKAGE_TEST Have you tested the package?
        
        GitLab
        ------
        
        - *PRIVATE_TOKEN* is your personal access token that has API access.
        - *API_HOST_NAME* is the host name of the API, e.g. *https://gitlab.example.com/api/v4*.
        - *PROJECT_ID* is the ID of the project.
        - *MERGE_REQUEST_ID* is the internal ID of the merge request.
        
        GitHub
        ------
        
        - *PRIVATE_TOKEN* is not needed for public repositories. Otherwise, it must be a `personal access token`_ with the access to the targeted scope.
        - *API_HOST_NAME* is the host name of the GitHub REST API v3: *https://api.github.com*.
        - *PROJECT_ID* defines the repository by specifying *owner* and *repo* separated by a forward slash, e.g. *melexis/sphinx-traceability-extension*.
        - *MERGE_REQUEST_ID* is the pull request number.
        
        .. _`personal access token`: https://github.blog/2013-05-16-personal-api-tokens/
        
        .. _traceability_process:
        
        -------
        Process
        -------
        
        The Melexis.SWCC process has a Guideline for documenting in Restructured Text (RST). It holds guidelines for using
        the traceability plugin with naming conventions, templates, etc.
        
        
Keywords: traceability,requirements engineering,requirements management,software engineering,systems engineering,sphinx,requirements,ASPICE,ISO26262,ASIL
Platform: any
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Environment :: Web Environment
Classifier: Framework :: Sphinx :: Extension
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3.4
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Topic :: Documentation
Classifier: Topic :: Documentation :: Sphinx
Classifier: Topic :: Utilities
