Document COVERAGE_RCFILE

Closes #3574.

docs/source/building.rst

@@ -38,7 +38,7 @@ Of the environment variables, only :envvar:`MODULE` is mandatory to be set
 (typically done in a makefile or run script), all others are optional.
 
 ..
-  If you edit the following sections, please also update the "helpmsg" text in src/cocotb_tools/config.py
+  If you edit the following sections, please also update the "helpmsg" text in ../../src/cocotb_tools/config.py
 
 Cocotb
 ------
@@ -167,10 +167,26 @@ Regression Manager
 
 .. envvar:: COVERAGE
 
-    Enable to report Python coverage data. For some simulators, this will also report :term:`HDL` coverage.
+    Enable to collect Python coverage data for user code.
+    For some simulators, this will also report :term:`HDL` coverage.
+    If :envvar:`COVERAGE_RCFILE` is not set,
+    branch coverage is collected
+    and files in the cocotb package directory are excluded.
 
     This needs the :mod:`coverage` Python module to be installed.
 
+.. envvar:: COVERAGE_RCFILE
+
+    Location of a configuration file for coverage collection of Python user code
+    using the the :mod:`coverage` module.
+    See https://coverage.readthedocs.io/en/latest/config.html for documentation of this file.
+
+    If this environment variable is set,
+    cocotb will *not* apply its own default coverage collection settings,
+    like enabling branch coverage and excluding files in the cocotb package directory.
+
+    .. versionadded:: 1.7
+
 .. envvar:: COCOTB_PDB_ON_EXCEPTION
 
    If defined, cocotb will drop into the Python debugger (:mod:`pdb`) if a test fails with an exception.

src/cocotb_tools/config.py

@@ -74,7 +74,7 @@ def help_vars_text() -> str:
     else:
         doclink = f"https://docs.cocotb.org/en/v{get_version()}/building.html"
 
-    # NOTE: make sure to keep "helpmsg" aligned with documentation/source/building.rst
+    # NOTE: make sure to keep "helpmsg" aligned with ../../docs/source/building.rst
     # Also keep it at 80 chars.
     helpmsg = textwrap.dedent(
         """\
@@ -99,7 +99,8 @@ def help_vars_text() -> str:
     MODULE                    Modules to search for test functions (comma-separated)
     TESTCASE                  Test function(s) to run (comma-separated list)
     COCOTB_RESULTS_FILE       File name for xUnit XML tests results
-    COVERAGE                  Report Python coverage (also HDL for some simulators)
+    COVERAGE                  Collect Python user coverage (HDL for some simulators)
+    COVERAGE_RCFILE           Configuration for user code coverage
 
     GPI
     ---