Package: mlx.coverity
Sphinx Coverity pluginPublish 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.GoalCoverity’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.Installingpip install mlx.coverityConfigurationTheconf.pyfile 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 theextensionsvariable:extensions = [
    'mlx.coverity',
    ...
]CredentialsPython variablecoverity_credentialsshould be defined in order to override the default configuration of the Coverity
plugin.Example of custom credentials for the plugin:coverity_credentials={'hostname':'scan.coverity.com','port':'8080','transport':'http','username':'reporter','password':'coverity','stream':'some_coverity_stream',}Link to traceability itemsThe plugin can be linked toTraceability 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 variableTRACEABILITY_ITEM_ID_REGEXshould be defined in order to override the default regular expression below. An empty string as regex will disable this
feature.TRACEABILITY_ITEM_ID_REGEX=r"([A-Z_]+-[A-Z0-9_]+)"Alter links to traceability itemsIf the item ID matched byTRACEABILITY_ITEM_ID_REGEXis 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 dictionaryTRACEABILITY_ITEM_ID_REGEXand the desired
item ID as value.TRACEABILITY_ITEM_RELINK={"STATIC_DEVIATE-MISRA_RULE_1_0":"STATIC_DEVIATE-MISRA_1_0",}Default configThe plugin itself holds a default config that can be used for any Coverity project:coverity_credentials={'hostname':'scan.coverity.com','port':'8080','transport':'http','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 theconf.pyof your project.UsageInside 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 valueBug, you should use the following snippet:..coverity-list::Customtabletitle:col:CID,Classification,Action,Comment:widths:10202050:classification:BugThe 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::Customcharttitle:chart:classification:Intentional,Pending+Unclassified:classification:Bug,Intentional,Pending,UnclassifiedThe 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.Attributes to coverity-listBlockcoverity-listtakes below attributes to provide better granularity and filtering of the displayed information.
Keep in mind that all the attributes are to be encapsulated by:. Almost all parameters are passed in CSV format
(comma-separated without any spaces).colList column names of the table. They should match the columns inside Coverity. The list is comma-separated without
any spaces. Possible Keywords are (but not limited, since Coverity has option to create custom names):CID: Coverity defect IDLocation: Coverity defect location consisting of file path and line numberClassification: Coverity defect Classification columnAction: Coverity defect Action informationChecker: Coverity defect CheckerStatus: Coverity defect Triage statusComment: Coverity defect last CommentReference: Coverity defect external references…Thiscoloption is optional. If thechartoption is used, the table won’t be generated. If thechartoption is not
used, default columns are used to generate the table, i.e.CID,Classification,Action,Comment.widthsOptional attribute that provides possibility to set each column width to a predefined percentage. This makes it nicer
for the pdf builders that are able to fit the table to the printable page width and, because of longtable, also provide
nice table continuation through multiple pages. Its parameters must be a space-separated list of integers.classificationFiltering by classification based on the text following the attribute. The text can be anything you desire, but the
default list includes:UnclassifiedPendingFalse PositiveIntentionalBugcheckerFiltering 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.chartThis optional, second display option will draw a pie chart that visualizes the amount of results for each allowed<<attribute>>option. Firstly, the attribute can be specified, followed by a colon:. The default attribute isclassification. Secondly, you have two optoins. Either you specify a list of attribue values, comma-separated or even
plus-sign-separated for a merge into the same slice, or else you define the minimum threshold 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. For example, to visualize the most prevalent MISRA violations with a grouping threshold of 50 items, you should
use the following code snippet:..coverity-list::ChartofthemostprevalentMISRAviolations:chart:checker:50:checker:MISRAContributionsWe 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 setupTo run tests and checks we use tox.# to install toxpip3installtox# to run teststoxTo build example locally you will need to install some dependencies and set your environment.# install current package locally and its dependenciespip3install-e.# copy example .env to your .envcpexample/.env.example.env# add env variables, adjust the values in .env
# buildmake-Cexample/html