Add SPHINX_AUTOBUILD_DEBUG to aid debugging

README.rst

@@ -167,6 +167,15 @@ or passing relevant ``filenames`` in addition to source and output directory in
 
 __ https://github.com/sphinx-doc/sphinx-autobuild/issues/34
 
+Debugging
+=========
+
+If the ``SPHINX_AUTOBUILD_DEBUG`` environment variable is present,
+is not ``""`` (the empty string) or ``0``,
+and a file change is detected,
+its path and the currently active ignore expressions are printed.
+This is to help setting up the ignore expressions correctly.
+
 Acknowledgements
 ================
 

sphinx_autobuild/filter.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import fnmatch
+import os
 import re
 from pathlib import Path
 
@@ -23,6 +24,11 @@ def __repr__(self):
     def __call__(self, filename: str, /):
         """Determine if 'path' should be ignored."""
         normalised_path = Path(filename).resolve().as_posix()
+        if os.getenv("SPHINX_AUTOBUILD_DEBUG") not in {None, "", "0"}:
+            print(
+                f"SPHINX_AUTOBUILD_DEBUG: {normalised_path!r} has changed; "
+                f"ignores are {self}"
+            )
         # Any regular pattern matches.
         for pattern in self.regular_patterns:
             # separators are normalised before creating the IgnoreFilter

tests/test_ignore.py

@@ -1,3 +1,7 @@
+import os
+
+import pytest
+
 from sphinx_autobuild.filter import IgnoreFilter
 
 
@@ -72,3 +76,16 @@ def test_multiple_both():
     assert ignored("foo/random.txt")
     assert ignored("foo/module.pyc")
     assert ignored("bar/__pycache__/file.pyc")
+
+
+@pytest.mark.parametrize("val", [None, "0", "", "y", "1", "whatever"])
+def test_debug(val, capfd):
+    if val is not None:
+        os.environ["SPHINX_AUTOBUILD_DEBUG"] = val
+    ignore_handler = IgnoreFilter([], [])
+    ignore_handler("dummyfile")
+    captured = capfd.readouterr()
+    if val in ("y", "1", "whatever"):
+        assert "SPHINX_AUTOBUILD_DEBUG" in captured.out
+    else:
+        assert "SPHINX_AUTOBUILD_DEBUG" not in captured.out