doc: develop: sca: Update CodeChecker configuration options

Put CodeChecker configuration parameters in tables for a clear overview
of all the options.

Signed-off-by: Pieter De Gendt <pieter.degendt@basalte.be>

doc/develop/sca/codechecker.rst

@@ -19,8 +19,8 @@ CodeChecker itself is a python package available on `pypi <https://pypi.org/proj
 
     pip install codechecker
 
-Running with CodeChecker
-************************
+Building with CodeChecker
+*************************
 
 To run CodeChecker, :ref:`west build <west-building>` should be
 called with a ``-DZEPHYR_SCA_VARIANT=codechecker`` parameter, e.g.
@@ -33,56 +33,63 @@ called with a ``-DZEPHYR_SCA_VARIANT=codechecker`` parameter, e.g.
 Configuring CodeChecker
 ***********************
 
-To configure CodeChecker or analyzers used, arguments can be passed using the
-``CODECHECKER_ANALYZE_OPTS`` parameter, e.g.
+CodeChecker uses different command steps, each with their respective configuration
+parameters. The following table lists all these options.
 
-.. code-block:: shell
+.. list-table::
+   :header-rows: 1
 
-    west build -b mimxrt1064_evk samples/basic/blinky -- -DZEPHYR_SCA_VARIANT=codechecker \
-    -DCODECHECKER_ANALYZE_OPTS="--config;$CODECHECKER_CONFIG_FILE;--timeout;60"
+   * - Parameter
+     - Description
+   * - ``CODECHECKER_ANALYZE_JOBS``
+     - The number of threads to use in analysis. (default: <CPU count>)
+   * - ``CODECHECKER_ANALYZE_OPTS``
+     - Arguments passed to the ``analyze`` command directly. (e.g. ``--timeout;360``)
+   * - ``CODECHECKER_CLEANUP``
+     - Perform a cleanup after parsing/storing. This will remove all ``plist`` files.
+   * - ``CODECHECKER_CONFIG_FILE``
+     - A JSON or YAML file with configuration options passed to all commands.
+   * - ``CODECHECKER_EXPORT``
+     - A comma separated list of report types. Allowed types are:
+       ``html,json,codeclimate,gerrit,baseline``.
+   * - ``CODECHECKER_NAME``
+     - The CodeChecker run metadata name. (default: ``zephyr``)
+   * - ``CODECHECKER_PARSE_EXIT_STATUS``
+     - By default, CodeChecker identified issues will not fail the build, set this option to fail
+       during analysis.
+   * - ``CODECHECKER_PARSE_OPTS``
+     - Arguments passed to the ``parse`` command directly. (e.g. ``--verbose;debug``)
+   * - ``CODECHECKER_PARSE_SKIP``
+     - Skip parsing the analysis, useful if you simply want to store the results.
+   * - ``CODECHECKER_STORE``
+     - Run the ``store`` command after analysis.
+   * - ``CODECHECKER_STORE_OPTS``
+     - Arguments passed to the ``store`` command directly. Implies ``CODECHECKER_STORE``.
+       (e.g. ``--url;localhost:8001/Default``)
+   * - ``CODECHECKER_STORE_TAG``
+     - Pass an identifier ``--tag`` to the ``store`` command.
+   * - ``CODECHECKER_TRIM_PATH_PREFIX``
+     - Trim the defined path from the analysis results, e.g. ``/home/user/zephyrproject``.
+       The value from ``west topdir`` is added by default.
+
+These parameters can be passed on the command line, or be set as environment variables.
 
 
-Storing CodeChecker results
-***************************
+Running twister with CodeChecker
+********************************
 
-If a CodeChecker server is active the results can be uploaded and stored for tracking purposes.
-Storing is done using the optional ``CODECHECKER_STORE=y`` or ``CODECHECKER_STORE_OPTS="arg;list"``
-parameters, e.g.
+When running CodeChecker as part of ``twister`` some default options are set as following:
 
-.. code-block:: shell
+.. list-table::
+   :header-rows: 1
 
-    west build -b mimxrt1064_evk samples/basic/blinky -- -DZEPHYR_SCA_VARIANT=codechecker \
-    -DCODECHECKER_STORE_OPTS="--name;build;--url;localhost:8001/Default"
+   * - Parameter
+     - Value
+   * - ``CODECHECKER_ANALYZE_JOBS``
+     - ``1``
+   * - ``CODECHECKER_NAME``
+     - ``<board target>:<testsuite name>``
+   * - ``CODECHECKER_STORE_TAG``
+     - The value from ``git describe`` in the application source directory.
 
-.. note::
-
-    If ``--name`` isn't passed to either ``CODECHECKER_ANALYZE_OPTS`` or ``CODECHECKER_STORE_OPTS``,
-    the default ``zephyr`` is used.
-
-
-Exporting CodeChecker reports
-*****************************
-
-Optional reports can be generated using the CodeChecker results, when passing a
-``-DCODECHECKER_EXPORT=<type>`` parameter. Allowed types are: ``html,json,codeclimate,gerrit,baseline``.
-Multiple types can be passed as comma-separated arguments.
-
-Optional parser configuration arguments can be passed using the
-``CODECHECKER_PARSE_OPTS`` parameter, e.g.
-
-.. code-block:: shell
-
-    west build -b mimxrt1064_evk samples/basic/blinky -- -DZEPHYR_SCA_VARIANT=codechecker \
-    -DCODECHECKER_EXPORT=html,json -DCODECHECKER_PARSE_OPTS="--trim-path-prefix;$PWD"
-
-Failing the build on CodeChecker issues
-***************************************
-
-By default, CodeChecker identified issues will not fail the build, only generate
-a report. To fail the build if any issues are found (for example, for use in
-CI), pass the ``CODECHECKER_PARSE_EXIT_STATUS=y`` parameter, e.g.
-
-.. code-block:: shell
-
-    west build -b mimxrt1064_evk samples/basic/blinky -- -DZEPHYR_SCA_VARIANT=codechecker \
-    -DCODECHECKER_PARSE_EXIT_STATUS=y
+To override these values, set an environment variable or pass them as extra arguments.