#585: Added instructions how to ignore sonar issues to the User Guide

doc/changes/unreleased.md

@@ -1,3 +1,7 @@
 # Unreleased
 
 ## Summary
+
+## Documentation
+
+* #585: Added instructions how to ignore sonar issues to the User Guide

doc/user_guide/features/metrics/collecting_metrics.rst

@@ -10,6 +10,7 @@ regarding Coverage, Security, and Static Code Analysis.
 
    project_report
    sonar
+   ignore_findings
 
 .. _generated_metrics:
 

doc/user_guide/features/metrics/ignore_findings.rst

@@ -0,0 +1,47 @@
+.. _ignore_findings:
+
+Ignoring Sonar Findings
+=======================
+
+In rare cases, Sonar might report a finding, you cannot fix or on which you
+can agree with your reviewers to accept or ignore it.  Please only choose this
+approach as a last resort.
+
+As Sonar reports only findings generated by other tools there are often
+multiple IDs you can use for referring to a particular issue.  E.g. security
+findings can be reported by ``bandit`` and hence for such a finding there is a
+bandit ID as well as a Sonar ID.
+
+Example
+-------
+
+For ``subprocess.run(args)``, Sonar could for example report *subprocess
+call - check for execution of untrusted input*. In the Sonar UI, when clicking
+on "Why is this an issue?", you will find references like
+
+* *B603: Test for use of subprocess with shell equals true
+  external_bandit:B603*
+* *See description of Bandit rule B603 at the*
+  `Bandit <https://bandit.readthedocs.io/en/latest/plugins/b603_subprocess_without_shell_equals_true.html>`__
+  *website*.
+
+In this case, the bandit error code is ``B603``, which you can ignore via a
+comment in the source code or, alternatively, accept in the Sonar UI.
+
+
+Ignoring a Finding Via a Source Code Comment
+--------------------------------------------
+
+The recommended way of ignoring such a finding is to append a comment to the
+relevant line of code:
+
+.. code-block:: python
+
+    subprocess.run(args)  # nosec: B603 - risk of untrusted input is accepted
+
+
+Alternatively, you could also accept a finding in the Sonar UI:
+
+.. image:: accept_finding_in_sonar_ui.png
+   :width: 400px
+   :alt: Accepting a Finding Via Sonar UI

doc/user_guide/troubleshooting.rst

@@ -0,0 +1,9 @@
+.. _ptb_troubleshooting:
+
+Troubleshooting
+===============
+
+.. toctree::
+   :maxdepth: 1
+
+   features/metrics/ignore_findings

doc/user_guide/user_guide.rst

@@ -10,5 +10,6 @@
     getting_started
     configuration
     features/index
+    troubleshooting
     customization
     migrating