docs: warnings now link to docs about the warning

Author: nedbat

coverage/control.py

@@ -470,6 +470,8 @@ def _warn(self, msg: str, slug: str | None = None, once: bool = False) -> None:
         slug.)
 
         """
+        import coverage as covmod
+
         if not self._no_warn_slugs:
             self._no_warn_slugs = set(self.config.disable_warnings)
 
@@ -479,7 +481,11 @@ def _warn(self, msg: str, slug: str | None = None, once: bool = False) -> None:
 
         self._warnings.append(msg)
         if slug:
-            msg = f"{msg} ({slug})"
+            url = (
+                f"https://coverage.readthedocs.io/en/{covmod.__version__}"
+                + f"/messages.html#warning-{slug}"
+            )
+            msg = f"{msg} ({slug}); see {url}"
         if self._debug.should("pid"):
             msg = f"[{os.getpid()}] {msg}"
         warnings.warn(msg, category=CoverageWarning, stacklevel=2)

doc/messages.rst

@@ -24,32 +24,42 @@ measurement or reporting.
 .. _warnings:
 
 Warnings
-........
+--------
 
 Warnings are issued for possible problems but don't stop the measurement or
 reporting.  See below for the details of each warning, and how to suppress
 warnings you don't need to see.
 
+.. _warning_couldnt_parse:
+
 Couldn't parse Python file XXX (couldnt-parse)
   During reporting, a file was thought to be Python, but it couldn't be parsed
   as Python.
 
+.. _warning_trace_changed:
+
 Trace function changed, data is likely wrong: XXX (trace-changed)
   Coverage measurement depends on a Python setting called the trace function.
   Other Python code in your product might change that function, which will
   disrupt coverage.py's measurement.  This warning indicates that has happened.
   The XXX in the message is the new trace function value, which might provide
   a clue to the cause.
 
+.. _warning_module_not_python:
+
 Module XXX has no Python source (module-not-python)
   You asked coverage.py to measure module XXX, but once it was imported, it
   turned out not to have a corresponding .py file.  Without a .py file,
   coverage.py can't report on missing lines.
 
+.. _warning_module_not_imported:
+
 Module XXX was never imported (module-not-imported)
   You asked coverage.py to measure module XXX, but it was never imported by
   your program.
 
+.. _warning_no_data_collected:
+
 No data was collected (no-data-collected)
   Coverage.py ran your program, but didn't measure any lines as executed.
   This could be because you asked to measure only modules that never ran,
@@ -58,33 +68,45 @@ No data was collected (no-data-collected)
   To debug this problem, try using ``run --debug=trace`` to see the tracing
   decision made for each file.
 
+.. _warning_module_not_measured:
+
 Module XXX was previously imported, but not measured (module-not-measured)
   You asked coverage.py to measure module XXX, but it had already been imported
   when coverage started.  This meant coverage.py couldn't monitor its
   execution.
 
+.. _warning_already_imported:
+
 Already imported a file that will be measured: XXX (already-imported)
   File XXX had already been imported when coverage.py started measurement. Your
   setting for ``--source`` or ``--include`` indicates that you wanted to
   measure that file.  Lines will be missing from the coverage report since the
   execution during import hadn't been measured.
 
+.. _warning_include_ignored:
+
 \-\-include is ignored because \-\-source is set (include-ignored)
   Both ``--include`` and ``--source`` were specified while running code.  Both
   are meant to focus measurement on a particular part of your source code, so
   ``--include`` is ignored in favor of ``--source``.
 
+.. _warning_dynamic_conflict:
+
 Conflicting dynamic contexts (dynamic-conflict)
   The ``[run] dynamic_context`` option is set in the configuration file, but
   something (probably a test runner plugin) is also calling the
   :meth:`.Coverage.switch_context` function to change the context. Only one of
   these mechanisms should be in use at a time.
 
+.. _warning_no_ctracer:
+
 Couldn't import C tracer (no-ctracer)
   The core tracer implemented in C should have been used, but couldn't be
   imported.  The reason is included in the warning message.  The Python tracer
   will be used instead.
 
+.. _warning_no_sysmon:
+
 sys.monitoring isn't available in this version, using default core (no-sysmon)
   You requested to use the sys.monitoring measurement core, but are running on
   Python 3.11 or lower where it isn't available.  A default core will be used
@@ -100,6 +122,10 @@ sys.monitoring doesn't yet support dynamic contexts, using default core (no-sysm
   This isn't supported by coverage.py yet.  A default core will be used
   instead.
 
+
+Disabling warnings
+------------------
+
 Individual warnings can be disabled with the :ref:`disable_warnings
 <config_run_disable_warnings>` configuration setting.  It is a list of the
 short parenthetical nicknames in the warning messages.  For example, to silence

tests/helpers.py

@@ -23,6 +23,7 @@
 from typing import Any, Callable, NoReturn, TypeVar, cast
 from collections.abc import Iterable, Iterator
 
+import coverage
 from coverage import env
 from coverage.debug import DebugControl
 from coverage.exceptions import CoverageWarning
@@ -313,6 +314,13 @@ def assert_count_equal(
     assert collections.Counter(list(a)) == collections.Counter(list(b))
 
 
+def get_coverage_warnings(warns: Iterable[warnings.WarningMessage]) -> list[str]:
+    """Extract the text of CoverageWarnings."""
+    warns = [w for w in warns if issubclass(w.category, CoverageWarning)]
+    texts = [cast(Warning, w.message).args[0] for w in warns]
+    return texts
+
+
 def assert_coverage_warnings(
     warns: Iterable[warnings.WarningMessage],
     *msgs: str | re.Pattern[str],
@@ -323,15 +331,15 @@ def assert_coverage_warnings(
     Each msg can be a string compared for equality, or a compiled regex used to
     search the text.
     """
+    actuals = get_coverage_warnings(warns)
     assert msgs  # don't call this without some messages.
-    warns = [w for w in warns if issubclass(w.category, CoverageWarning)]
-    actuals = [cast(Warning, w.message).args[0] for w in warns]
     assert len(msgs) == len(actuals)
-    for expected, actual in zip(msgs, actuals):
+    for actual, expected in zip(actuals, msgs):
         if hasattr(expected, "search"):
             assert expected.search(actual), f"{actual!r} didn't match {expected!r}"
         else:
-            assert expected == actual
+            actual = actual.partition("; see ")[0]
+            assert actual == expected
 
 
 @contextlib.contextmanager

tests/test_api.py

@@ -30,8 +30,14 @@
 
 from tests import testenv
 from tests.coveragetest import CoverageTest, TESTS_DIR, UsingModulesMixin
-from tests.helpers import assert_count_equal, assert_coverage_warnings
-from tests.helpers import change_dir, nice_file, os_sep
+from tests.helpers import (
+    assert_count_equal,
+    assert_coverage_warnings,
+    change_dir,
+    get_coverage_warnings,
+    nice_file,
+    os_sep,
+)
 
 BAD_SQLITE_REGEX = r"file( is encrypted or)? is not a database"
 
@@ -619,6 +625,26 @@ def test_warn_once(self) -> None:
 
         assert_coverage_warnings(warns, "Warning, warning 1! (bot)")
         # No "Warning, warning 2!" in warns
+        assert len(warns) == 1
+
+    def test_warnings_with_urls(self) -> None:
+        with pytest.warns(Warning) as warns:
+            cov = coverage.Coverage()
+            cov.load()
+            cov._warn("Warning Will Robinson", slug="will-rob")
+            cov._warn("Warning, warning 2!", slug="second-one")
+        warnings = get_coverage_warnings(warns)
+
+        def url(slug):
+            return (
+                f"https://coverage.readthedocs.io/en/{coverage.__version__}"
+                + f"/messages.html#warning-{slug}"
+            )
+
+        assert warnings == [
+            f"Warning Will Robinson (will-rob); see {url('will-rob')}",
+            f"Warning, warning 2! (second-one); see {url('second-one')}",
+        ]
 
     def test_source_and_include_dont_conflict(self) -> None:
         # A bad fix made this case fail: https://github.com/nedbat/coveragepy/issues/541

tests/test_process.py

@@ -762,13 +762,14 @@ def foo():
         # Remove the file location and source line from the warning.
         out = re.sub(r"(?m)^[\\/\w.:~_-]+:\d+: CoverageWarning: ", "f:d: CoverageWarning: ", out)
         out = re.sub(r"(?m)^\s+self.warn.*$\n", "", out)
+        out = re.sub(r"; see https://.*$", "", out)
         expected = (
             "Run 1\n"
             + "Run 2\n"
             + "f:d: CoverageWarning: Module foo was previously imported, but not measured "
             + "(module-not-measured)\n"
         )
-        assert expected == out
+        assert out == expected
 
     def test_module_name(self) -> None:
         # https://github.com/nedbat/coveragepy/issues/478