Metadata-Version: 1.1
Name: mlx.traceability
Version: 2.2.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)
Download-URL: https://github.com/melexis/sphinx-traceability-extension/tarball/2.2.0
Description-Content-Type: UNKNOWN
Description: .. image:: https://img.shields.io/badge/License-GPL%20v3-blue.svg
            :target: https://www.gnu.org/licenses/gpl-3.0
            :alt: GPL3 License
        
        .. image:: https://badge.fury.io/py/mlx.traceability.svg
            :target: https://badge.fury.io/py/mlx.traceability
            :alt: Pypi packaged release
        
        .. image:: https://travis-ci.org/melexis/sphinx-traceability-extension.svg?branch=master
            :target: https://travis-ci.org/melexis/sphinx-traceability-extension
            :alt: Build status
        
        .. image:: https://codecov.io/gh/melexis/sphinx-traceability-extension/branch/master/graph/badge.svg
            :target: https://codecov.io/gh/melexis/sphinx-traceability-extension
            :alt: Code Coverage
        
        .. image:: https://codeclimate.com/github/melexis/sphinx-traceability-extension/badges/gpa.svg
            :target: https://codeclimate.com/github/melexis/sphinx-traceability-extension
            :alt: Code Climate Status
        
        .. image:: https://codeclimate.com/github/melexis/sphinx-traceability-extension/badges/issue_count.svg
            :target: https://codeclimate.com/github/melexis/sphinx-traceability-extension
            :alt: Issue Count
        
        .. image:: https://requires.io/github/melexis/sphinx-traceability-extension/requirements.svg?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.svg?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.
        
        .. _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::
        
            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::
        
            extensions = [
                'mlx.traceability.traceability',
                ...
            ]
        
        Second the path to the static javascript assets needs to be added to the sphinx ``html_static_path``
        variable.
        
        .. code-block::
        
            import os
            import mlx.traceability
        
            html_static_path = [os.path.join(os.path.dirname(mlx.traceability.__file__), 'assets')]
        
        
        .. _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.
        
        Relationships with prefix *ext_* are threated 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
        
        .. _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.
        
        In some project this callback is used to assign a relation to an ASIL attribute (also a documentation
        object) to all of the requirements.
        
        Example of no callback per item:
        
        .. code-block:: python
        
            traceability_callback_per_item = None
        
        .. _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_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': 'Referento 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 build into the plugin, can be overriden 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_relationships
            from traceability_config import swcc_traceability_relationship_to_string
        
            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::
        
            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 documenation item
        - caption or short description of 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
                :validated_by: ITEST-MY_FIRST_INTEGRATION_TEST
                :ext_polarion_reference: project_x:workitem_y
        
                According to the Polarion reference, the software **shall** implement my first requirement.
        
        The relations to other documentation items can be specified as:
        
        - a space seperated 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
        
        .. _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
        
        where *SWRQT* (*filter* argument) can be replace by any python regular expression. Documentation items matching
        their ID to the given regular expression end up in the list.
        
        .. _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
                :sourcetitle: Software requirements
                :targettitle: Integration and unit test cases
                :type: validated_by
                :stats:
        
        where the *source* and *target* arguments can be replaced by any python regular expression. 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 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.
        
        .. _traceability_usage_item_tree:
        
        Documentation items tree-view
        =============================
        
        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
                :type: impacts_on validated_by
        
        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.
        
        Going deeper down this nested bullet list, the items relationships are checked: if there is a *type*
        relationship (*type* is a space seperated 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 an endless recursion in python. The plugin
            checks the *item-tree* directives for this mistake!
        
        .. _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 :: 2.6
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3.2
Classifier: Programming Language :: Python :: 3.3
Classifier: Programming Language :: Python :: 3.4
Classifier: Programming Language :: Python :: 3.5
Classifier: Topic :: Documentation
Classifier: Topic :: Documentation :: Sphinx
Classifier: Topic :: Utilities
