Goal

Coverity’s reporting capabilities enable you to export data into separate documentation. While this might be preferred, it is also detached from your software documentation. Another lack is that it does not include comments or any other special fields. That means you can end up with a huge amount of intentionally triaged defects, without any explanation why they are intentional. Because of that, you cannot link your explanations for actions to that report and numbers could mean just anything. This plugin should enable simple and seamless Coverity reporting integration into existing Sphinx documentation. Generating a reStructuredText table of defects was one option, but that allows changing before it is rendered, so to provide a more trustworthy path, this plugin retrieves the data through Coverity API and generates/renders documentation via Sphinx without intermediate (editable) artifacts.

Installing

pip install mlx.coverity

Configuration

The conf.py file contains the documentation configuration for your project. This file needs to be equipped in order to configure the Coverity plugin.

First, the plugin needs to be enabled in the extensions variable:

extensions = [
    'mlx.coverity',
    ...
]

coverity_credentials = {
    'hostname': 'scan.coverity.com',
    'username': 'myusername',
    'password': 'mypassword',
    'stream': 'some_coverity_stream',
    'snapshot': '1',
}

TRACEABILITY_ITEM_ID_REGEX = r"([A-Z_]+-[A-Z0-9_]+)"

TRACEABILITY_ITEM_RELINK = {
    "STATIC_DEVIATE-MISRA_RULE_1_0": "STATIC_DEVIATE-MISRA_1_0",
}

coverity_credentials = {
    'hostname': 'scan.coverity.com',
    'username': 'reporter',
    'password': 'coverity',
    'stream': 'some_coverity_stream',
}

TRACEABILITY_ITEM_ID_REGEX = r"([A-Z_]+-[A-Z0-9_]+)"
TRACEABILITY_ITEM_RELINK = {}

Usage

Inside your reStructuredText file you can call a block .. coverity-list:, which will generate the table with title and defined columns. For example, to display CID, Classification, Action and Comment columns, while filtering classification items with value Bug, you should use the following snippet:

.. coverity-list:: Custom table title
    :col: CID,Classification,Action,Comment
    :widths: 10 20 20 50
    :classification: Bug

The plugin will then automatically replace this block with the table queried from the Coverity server.

You can also call this block .. coverity-list: to generate a pie chart. For example, to label the amount of items classified as Intentional and the amount of items classified as Pending or Unclassified, while filtering classification items, you should use the following snippet:

.. coverity-list:: Custom chart title
    :chart: classification:Intentional,Pending+Unclassified
    :classification: Bug,Intentional,Pending,Unclassified

The plugin allows the use of both display options, col`and `chart, at the same time as well. In that case, they share all filtering options.

Contributions

We welcome any contributions to this plugin. Do not be shy and open a pull request. We will try to do our best to help you include your contribution to our repository. Keep in mind that reporting a bug or requesting a feature is also a nice gesture and considered as contribution, even if you do not have development skills to implement it.

Development setup

To contribute to the code or documentation, you may want to run tests and build the documentation. Firstly, clone the repository.

To run tests and checks we use tox.

# to install tox
pip3 install tox

# to run tests
tox

To build the example documentation locally, you will need to install the package and set your environment, see help.

# install current package locally and its dependencies
pip3 install --editable .

# define environment variables, needed by example/conf.py
# or store them in a .env file for a more permanent solution
export COVERITY_USERNAME='yourusername'
export COVERITY_PASSWORD='yourpassword'
export COVERITY_STREAM='yourstream'
export COVERITY_SNAPSHOT=''

# build documentation with Sphinx in a Tox environment
tox -e html