.. 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.coverity.svg
:target: https://badge.fury.io/py/mlx.coverity
:alt: Pypi packaged release
.. image:: https://github.com/melexis/sphinx-coverity-extension/actions/workflows/python-package.yml/badge.svg?branch=master
:target: https://github.com/melexis/sphinx-coverity-extension/actions/workflows/python-package.yml
:alt: Build status
.. image:: https://img.shields.io/badge/Documentation-published-brightgreen.svg
:target: https://melexis.github.io/sphinx-coverity-extension/
:alt: Documentation
.. image:: https://codecov.io/gh/melexis/sphinx-coverity-extension/branch/master/graph/badge.svg
:target: https://codecov.io/gh/melexis/sphinx-coverity-extension
:alt: Code Coverage
.. image:: https://codeclimate.com/github/melexis/sphinx-coverity-extension/badges/gpa.svg
:target: https://codeclimate.com/github/melexis/sphinx-coverity-extension
:alt: Code Climate Status
.. image:: https://codeclimate.com/github/melexis/sphinx-coverity-extension/badges/issue_count.svg
:target: https://codeclimate.com/github/melexis/sphinx-coverity-extension
:alt: Issue Count
.. image:: https://img.shields.io/badge/contributions-welcome-brightgreen.svg?style=flat
:target: https://github.com/melexis/sphinx-coverity-extension/issues
:alt: Contributions welcome
======================
Sphinx Coverity plugin
======================
Publish Coverity report along your documentation - up-to-date at every build. Include comments and other special data
in the same table and draw some nice graphs to showcase the quality.
----
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.
.. _coverity_installing:
----------
Installing
----------
.. code-block::
pip install mlx.coverity
.. _coverity_config:
-------------
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:
.. code-block::
extensions = [
'mlx.coverity',
...
]
.. _coverity_credentials:
Credentials
===========
Python variable *coverity_credentials* should be defined in order to override the default configuration of the Coverity
plugin.
Example of custom credentials for the plugin:
.. code-block:: python
coverity_credentials = {
'hostname': 'scan.coverity.com',
'username': 'myusername',
'password': 'mypassword',
'stream': 'some_coverity_stream',
'snapshot': '1',
}
Snapshot is optional. When an empty string is given, the last snapshot is used.
Link to traceability items
==========================
The plugin can be linked to `Traceability extension`_. This means that this plugin can link to traceability items in the
description of Coverity defects by creating a reference in the docnode. Python variable *TRACEABILITY_ITEM_ID_REGEX*
should be defined in order to override the default regular expression below. An empty string as regex will disable this
feature.
.. code-block:: python
TRACEABILITY_ITEM_ID_REGEX = r"([A-Z_]+-[A-Z0-9_]+)"
Alter links to traceability items
=================================
If the item ID matched by *TRACEABILITY_ITEM_ID_REGEX* is incorrect, e.g. it does not exist in the collection of
traceability items, you can configure the plugin to link to the desired item ID instead.
Add the item ID returned by Coverity as a key to the Python dictionary *TRACEABILITY_ITEM_ID_REGEX* and the desired
item ID as value.
.. code-block:: python
TRACEABILITY_ITEM_RELINK = {
"STATIC_DEVIATE-MISRA_RULE_1_0": "STATIC_DEVIATE-MISRA_1_0",
}
Default config
==============
The plugin itself holds a default config that can be used for any Coverity project:
.. code-block:: python
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 = {}
This default configuration, which is built into the plugin, can be overridden through the *conf.py* of your project.
-----
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:
.. code-block:: python
.. 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:
.. code-block:: python
.. 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.
Options of coverity-list
========================
The directive `coverity-list` is configurable with several options to provide better granularity and filtering of the
displayed information. They are all optional.
All option names shall be encapsulated by a colon and almost all option values shall be in CSV format
(comma-separated without any spaces). All options are documented below, starting with the display options and followed
by the filter options:
Display options
---------------
By default, the Coverity defects are listed in a table, of which the columns can be configured with the `col` option.
If the `chart` option is used and the `col` option is not, only a pie chart is generated.
:col: *multiple arguments (CSV format)*
Specify column names of the table. The default value is `CID,Classification,Action,Comment`.
They should match the columns inside Coverity. Possible Keywords are (but not limited, since Coverity has the
option to create custom names):
- `CID`: Coverity defect ID
- `Location`: Coverity defect location consisting of file path and line number
- `Classification`: Coverity defect Classification column
- `Action`: Coverity defect Action information
- `Checker`: Coverity defect Checker
- `Status`: Coverity defect Triage status
- `Comment`: Coverity defect last Comment
- `Reference`: Coverity defect external references
- ...
:widths: *multiple arguments (space-separated)*
Column widths as a percentage value (integer). This could come in handy to fit the table on a PDF page.
The LaTeX package `longtable` provides nice table continuation across multiple pages.
:chart: *optional*
This optional, second display option draws a pie chart that visualizes the amount of defects for each allowed
`<<attribute>>` option. Firstly, the attribute can be specified, followed by a colon. The default attribute is
`classification`. Secondly, you have two options. Either you specify a list of attribute values, comma-separated,
or even plus-sign-separated for a merge into the same slice.
Else, you define the minimum threshold amount of defects with the same attribute value that needs to be reached
for them to be grouped together into a slice. All other defects get labeled as "Other".
The example below results in a pie chart that visualizes the most prevalent MISRA violations with a grouping
threshold of 50 items:
.. code-block:: python
.. coverity-list:: Chart of the most prevalent MISRA violations
:chart: checker:50
:checker: MISRA
Filter options
--------------
All filter options accept *multiple arguments (CSV format)*.
:classification:
Filtering by classification based on the text following the attribute. The text can be anything you desire, but the
default list includes:
- `Unclassified`
- `Pending`
- `False Positive`
- `Intentional`
- `Bug`
:checker:
Filtering by checker based on the text following the attribute. The text can be anything you desire. Regular expressions
work for this attribute, e.g. `MISRA`.
:impact:
Filter for only these impacts.
:kind:
Filter for only these kinds.
:classification:
Filter for only these classifications.
:action:
Filter for only these actions.
:component:
Filter for only these components.
:cwe:
Filter for only these CWE ratings.
:cid:
Filter only these CIDs.
-------------
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_.
.. code-block:: bash
# 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_.
.. code-block:: bash
# 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
.. _`Traceability extension`: https://github.com/melexis/sphinx-traceability-extension/
.. _tox: https://tox.wiki/
.. _help: https://pypi.org/project/python-decouple/#where-is-the-settings-data-stored
Raw data
{
"_id": null,
"home_page": "https://github.com/melexis/sphinx-coverity-extension",
"name": "mlx.coverity",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "coverity, reporting, reStructuredText coverity report, sphinx, ASPICE, ISO26262, ASIL",
"author": "Crt Mori",
"author_email": "cmo@melexis.com",
"download_url": "https://files.pythonhosted.org/packages/20/f1/996b0f3f5c4483d193889e03176a3c87219af6cb484e9ba8b63687809b34/mlx_coverity-2.0.3.tar.gz",
"platform": "any",
"description": ".. image:: https://img.shields.io/badge/License-GPL%20v3-blue.svg\n :target: https://www.gnu.org/licenses/gpl-3.0\n :alt: GPL3 License\n\n.. image:: https://badge.fury.io/py/mlx.coverity.svg\n :target: https://badge.fury.io/py/mlx.coverity\n :alt: Pypi packaged release\n\n.. image:: https://github.com/melexis/sphinx-coverity-extension/actions/workflows/python-package.yml/badge.svg?branch=master\n :target: https://github.com/melexis/sphinx-coverity-extension/actions/workflows/python-package.yml\n :alt: Build status\n\n.. image:: https://img.shields.io/badge/Documentation-published-brightgreen.svg\n :target: https://melexis.github.io/sphinx-coverity-extension/\n :alt: Documentation\n\n.. image:: https://codecov.io/gh/melexis/sphinx-coverity-extension/branch/master/graph/badge.svg\n :target: https://codecov.io/gh/melexis/sphinx-coverity-extension\n :alt: Code Coverage\n\n.. image:: https://codeclimate.com/github/melexis/sphinx-coverity-extension/badges/gpa.svg\n :target: https://codeclimate.com/github/melexis/sphinx-coverity-extension\n :alt: Code Climate Status\n\n.. image:: https://codeclimate.com/github/melexis/sphinx-coverity-extension/badges/issue_count.svg\n :target: https://codeclimate.com/github/melexis/sphinx-coverity-extension\n :alt: Issue Count\n\n.. image:: https://img.shields.io/badge/contributions-welcome-brightgreen.svg?style=flat\n :target: https://github.com/melexis/sphinx-coverity-extension/issues\n :alt: Contributions welcome\n\n======================\nSphinx Coverity plugin\n======================\n\nPublish Coverity report along your documentation - up-to-date at every build. Include comments and other special data\nin the same table and draw some nice graphs to showcase the quality.\n\n----\nGoal\n----\n\nCoverity's reporting capabilities enable you to export data into separate documentation. While this might be preferred,\nit is also detached from your software documentation. Another lack is that it does not include comments or any\nother special fields. That means you can end up with a huge amount of intentionally triaged defects, without any\nexplanation why they are intentional. Because of that, you cannot link your explanations for actions to that report and\nnumbers could mean just anything. This plugin should enable simple and seamless Coverity reporting integration into\nexisting Sphinx documentation. Generating a reStructuredText table of defects was one option, but that allows changing\nbefore it is rendered, so to provide a more trustworthy path, this plugin retrieves the data through Coverity API and\ngenerates/renders documentation via Sphinx without intermediate (editable) artifacts.\n\n.. _coverity_installing:\n\n----------\nInstalling\n----------\n\n.. code-block::\n\n pip install mlx.coverity\n\n.. _coverity_config:\n\n-------------\nConfiguration\n-------------\n\nThe *conf.py* file contains the documentation configuration for your project. This file needs to be equipped in order\nto configure the Coverity plugin.\n\nFirst, the plugin needs to be enabled in the *extensions* variable:\n\n.. code-block::\n\n extensions = [\n 'mlx.coverity',\n ...\n ]\n\n.. _coverity_credentials:\n\nCredentials\n===========\n\nPython variable *coverity_credentials* should be defined in order to override the default configuration of the Coverity\nplugin.\n\nExample of custom credentials for the plugin:\n\n.. code-block:: python\n\n coverity_credentials = {\n 'hostname': 'scan.coverity.com',\n 'username': 'myusername',\n 'password': 'mypassword',\n 'stream': 'some_coverity_stream',\n 'snapshot': '1',\n }\n\nSnapshot is optional. When an empty string is given, the last snapshot is used.\n\nLink to traceability items\n==========================\n\nThe plugin can be linked to `Traceability extension`_. This means that this plugin can link to traceability items in the\ndescription of Coverity defects by creating a reference in the docnode. Python variable *TRACEABILITY_ITEM_ID_REGEX*\nshould be defined in order to override the default regular expression below. An empty string as regex will disable this\nfeature.\n\n.. code-block:: python\n\n TRACEABILITY_ITEM_ID_REGEX = r\"([A-Z_]+-[A-Z0-9_]+)\"\n\nAlter links to traceability items\n=================================\n\nIf the item ID matched by *TRACEABILITY_ITEM_ID_REGEX* is incorrect, e.g. it does not exist in the collection of\ntraceability items, you can configure the plugin to link to the desired item ID instead.\nAdd the item ID returned by Coverity as a key to the Python dictionary *TRACEABILITY_ITEM_ID_REGEX* and the desired\nitem ID as value.\n\n.. code-block:: python\n\n TRACEABILITY_ITEM_RELINK = {\n \"STATIC_DEVIATE-MISRA_RULE_1_0\": \"STATIC_DEVIATE-MISRA_1_0\",\n }\n\nDefault config\n==============\n\nThe plugin itself holds a default config that can be used for any Coverity project:\n\n.. code-block:: python\n\n coverity_credentials = {\n 'hostname': 'scan.coverity.com',\n 'username': 'reporter',\n 'password': 'coverity',\n 'stream': 'some_coverity_stream',\n }\n\n TRACEABILITY_ITEM_ID_REGEX = r\"([A-Z_]+-[A-Z0-9_]+)\"\n TRACEABILITY_ITEM_RELINK = {}\n\nThis default configuration, which is built into the plugin, can be overridden through the *conf.py* of your project.\n\n\n-----\nUsage\n-----\n\nInside your reStructuredText file you can call a block `.. coverity-list:`, which will generate the table\nwith title and defined columns. For example, to display CID, Classification, Action and Comment columns, while\nfiltering classification items with value `Bug`, you should use the following snippet:\n\n.. code-block:: python\n\n .. coverity-list:: Custom table title\n :col: CID,Classification,Action,Comment\n :widths: 10 20 20 50\n :classification: Bug\n\nThe plugin will then automatically replace this block with the table queried from the Coverity server.\n\nYou can also call this block `.. coverity-list:` to generate a pie chart. For example, to label the amount of items\nclassified as Intentional and the amount of items classified as Pending or Unclassified, while filtering classification\nitems, you should use the following snippet:\n\n.. code-block:: python\n\n .. coverity-list:: Custom chart title\n :chart: classification:Intentional,Pending+Unclassified\n :classification: Bug,Intentional,Pending,Unclassified\n\nThe plugin allows the use of both display options, `col`and `chart`, at the same time as well. In that case, they share\nall filtering options.\n\nOptions of coverity-list\n========================\n\nThe directive `coverity-list` is configurable with several options to provide better granularity and filtering of the\ndisplayed information. They are all optional.\nAll option names shall be encapsulated by a colon and almost all option values shall be in CSV format\n(comma-separated without any spaces). All options are documented below, starting with the display options and followed\nby the filter options:\n\nDisplay options\n---------------\n\nBy default, the Coverity defects are listed in a table, of which the columns can be configured with the `col` option.\nIf the `chart` option is used and the `col` option is not, only a pie chart is generated.\n\n:col: *multiple arguments (CSV format)*\n\n Specify column names of the table. The default value is `CID,Classification,Action,Comment`.\n They should match the columns inside Coverity. Possible Keywords are (but not limited, since Coverity has the\n option to create custom names):\n\n - `CID`: Coverity defect ID\n - `Location`: Coverity defect location consisting of file path and line number\n - `Classification`: Coverity defect Classification column\n - `Action`: Coverity defect Action information\n - `Checker`: Coverity defect Checker\n - `Status`: Coverity defect Triage status\n - `Comment`: Coverity defect last Comment\n - `Reference`: Coverity defect external references\n - ...\n\n:widths: *multiple arguments (space-separated)*\n\n Column widths as a percentage value (integer). This could come in handy to fit the table on a PDF page.\n The LaTeX package `longtable` provides nice table continuation across multiple pages.\n\n:chart: *optional*\n\n This optional, second display option draws a pie chart that visualizes the amount of defects for each allowed\n `<<attribute>>` option. Firstly, the attribute can be specified, followed by a colon. The default attribute is\n `classification`. Secondly, you have two options. Either you specify a list of attribute values, comma-separated,\n or even plus-sign-separated for a merge into the same slice.\n Else, you define the minimum threshold amount of defects with the same attribute value that needs to be reached\n for them to be grouped together into a slice. All other defects get labeled as \"Other\".\n The example below results in a pie chart that visualizes the most prevalent MISRA violations with a grouping\n threshold of 50 items:\n\n .. code-block:: python\n\n .. coverity-list:: Chart of the most prevalent MISRA violations\n :chart: checker:50\n :checker: MISRA\n\nFilter options\n--------------\n\nAll filter options accept *multiple arguments (CSV format)*.\n\n:classification:\n\n Filtering by classification based on the text following the attribute. The text can be anything you desire, but the\n default list includes:\n\n - `Unclassified`\n - `Pending`\n - `False Positive`\n - `Intentional`\n - `Bug`\n\n:checker:\n\n Filtering by checker based on the text following the attribute. The text can be anything you desire. Regular expressions\n work for this attribute, e.g. `MISRA`.\n\n:impact:\n\n Filter for only these impacts.\n\n:kind:\n\n Filter for only these kinds.\n\n:classification:\n\n Filter for only these classifications.\n\n:action:\n\n Filter for only these actions.\n\n:component:\n\n Filter for only these components.\n\n:cwe:\n\n Filter for only these CWE ratings.\n\n:cid:\n\n Filter only these CIDs.\n\n-------------\nContributions\n-------------\n\nWe welcome any contributions to this plugin. Do not be shy and open a pull request. We will try to do our best to help\nyou include your contribution to our repository. Keep in mind that reporting a bug or requesting a feature is also a\nnice gesture and considered as contribution, even if you do not have development skills to implement it.\n\n-----------------\nDevelopment setup\n-----------------\n\nTo contribute to the code or documentation, you may want to run tests and build the documentation. Firstly, clone\nthe repository.\n\nTo run tests and checks we use tox_.\n\n.. code-block:: bash\n\n # to install tox\n pip3 install tox\n\n # to run tests\n tox\n\nTo build the example documentation locally, you will need to install the package and set your environment, see help_.\n\n.. code-block:: bash\n\n # install current package locally and its dependencies\n pip3 install --editable .\n\n # define environment variables, needed by example/conf.py\n # or store them in a .env file for a more permanent solution\n export COVERITY_USERNAME='yourusername'\n export COVERITY_PASSWORD='yourpassword'\n export COVERITY_STREAM='yourstream'\n export COVERITY_SNAPSHOT=''\n\n # build documentation with Sphinx in a Tox environment\n tox -e html\n\n.. _`Traceability extension`: https://github.com/melexis/sphinx-traceability-extension/\n.. _tox: https://tox.wiki/\n.. _help: https://pypi.org/project/python-decouple/#where-is-the-settings-data-stored\n",
"bugtrack_url": null,
"license": "GNU General Public License v3 (GPLv3)",
"summary": "Sphinx coverity extension from Melexis",
"version": "2.0.3",
"project_urls": {
"Homepage": "https://github.com/melexis/sphinx-coverity-extension"
},
"split_keywords": [
"coverity",
" reporting",
" restructuredtext coverity report",
" sphinx",
" aspice",
" iso26262",
" asil"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "e9e4d5f521ead22ecd0c7a530769391815ca780d9a7bf7ddb432b2b3ac20f9ac",
"md5": "9bfbec7e60620966a70bee5f9d92fe4b",
"sha256": "d8e2fa7a7cfa19dad549d6561f300b589551ca36b1e569d95471a0a0a53e47c8"
},
"downloads": -1,
"filename": "mlx.coverity-2.0.3-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "9bfbec7e60620966a70bee5f9d92fe4b",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": ">=3.8",
"size": 32594,
"upload_time": "2024-11-14T12:20:13",
"upload_time_iso_8601": "2024-11-14T12:20:13.192727Z",
"url": "https://files.pythonhosted.org/packages/e9/e4/d5f521ead22ecd0c7a530769391815ca780d9a7bf7ddb432b2b3ac20f9ac/mlx.coverity-2.0.3-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "20f1996b0f3f5c4483d193889e03176a3c87219af6cb484e9ba8b63687809b34",
"md5": "e2f73dd30e7d3b32d08a6777f36c473e",
"sha256": "f08f5649244ef5ee5431bf4436518a58fea9e62a641f932557ed2f3370292fe2"
},
"downloads": -1,
"filename": "mlx_coverity-2.0.3.tar.gz",
"has_sig": false,
"md5_digest": "e2f73dd30e7d3b32d08a6777f36c473e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 34120,
"upload_time": "2024-11-14T12:20:14",
"upload_time_iso_8601": "2024-11-14T12:20:14.953043Z",
"url": "https://files.pythonhosted.org/packages/20/f1/996b0f3f5c4483d193889e03176a3c87219af6cb484e9ba8b63687809b34/mlx_coverity-2.0.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-14 12:20:14",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "melexis",
"github_project": "sphinx-coverity-extension",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "mlx.coverity"
}
JSON
