Add SPHINX_AUTOBUILD_DEBUG to aid debugging

Currently, changed paths and the ignore expressions are shown.

Closes #188

Author: cmarqu

README.rst

@@ -167,6 +167,14 @@ 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
+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 "SPHINX_AUTOBUILD_DEBUG" in os.environ:
+            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