From d706368d645e606a11167e462ba00b1976f9e190 Mon Sep 17 00:00:00 2001 From: Colin Marquardt Date: Wed, 28 May 2025 23:48:28 +0200 Subject: [PATCH 1/4] Add SPHINX_AUTOBUILD_DEBUG to aid debugging Currently, changed paths and the ignore expressions are shown. Closes #188 --- README.rst | 8 ++++++++ sphinx_autobuild/filter.py | 6 ++++++ 2 files changed, 14 insertions(+) diff --git a/README.rst b/README.rst index 4aeaa72..9d542ac 100644 --- a/README.rst +++ b/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 ================ diff --git a/sphinx_autobuild/filter.py b/sphinx_autobuild/filter.py index eb46dbe..b260c9d 100644 --- a/sphinx_autobuild/filter.py +++ b/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 From 28928dc670cea4eb045440c9249d342c81abcc18 Mon Sep 17 00:00:00 2001 From: Colin Marquardt Date: Sun, 24 Aug 2025 17:56:05 +0200 Subject: [PATCH 2/4] Add test for SPHINX_AUTOBUILD_DEBUG --- README.rst | 1 + tests/test_ignore.py | 20 ++++++++++++++++++++ 2 files changed, 21 insertions(+) diff --git a/README.rst b/README.rst index 9d542ac..33c2020 100644 --- a/README.rst +++ b/README.rst @@ -171,6 +171,7 @@ Debugging ========= If the ``SPHINX_AUTOBUILD_DEBUG`` environment variable is present +(regardless of its value) 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. diff --git a/tests/test_ignore.py b/tests/test_ignore.py index fa6b0bd..064df03 100644 --- a/tests/test_ignore.py +++ b/tests/test_ignore.py @@ -1,3 +1,7 @@ +import os + +import pytest + from sphinx_autobuild.filter import IgnoreFilter @@ -72,3 +76,19 @@ def test_multiple_both(): assert ignored("foo/random.txt") assert ignored("foo/module.pyc") assert ignored("bar/__pycache__/file.pyc") + + +@pytest.mark.parametrize("is_debug", [True, False]) +def test_debug(is_debug, capfd): + if is_debug: + # also "0" is considered to mean "print debug output": + os.environ["SPHINX_AUTOBUILD_DEBUG"] = "0" + else: + del os.environ["SPHINX_AUTOBUILD_DEBUG"] + ignore_handler = IgnoreFilter([], []) + ignore_handler("dummyfile") + captured = capfd.readouterr() + if is_debug: + assert "SPHINX_AUTOBUILD_DEBUG" in captured.out + else: + assert "SPHINX_AUTOBUILD_DEBUG" not in captured.out From 08c18b7818d288b0d8584f64fc58b7756e2ffddb Mon Sep 17 00:00:00 2001 From: Colin Marquardt Date: Mon, 25 Aug 2025 17:10:01 +0200 Subject: [PATCH 3/4] Consider SPHINX_AUTOBUILD_DEBUG falsy with empty string and 0 --- README.rst | 4 ++-- sphinx_autobuild/filter.py | 2 +- tests/test_ignore.py | 13 +++++-------- 3 files changed, 8 insertions(+), 11 deletions(-) diff --git a/README.rst b/README.rst index 33c2020..190b9a1 100644 --- a/README.rst +++ b/README.rst @@ -170,8 +170,8 @@ __ https://github.com/sphinx-doc/sphinx-autobuild/issues/34 Debugging ========= -If the ``SPHINX_AUTOBUILD_DEBUG`` environment variable is present -(regardless of its value) +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. diff --git a/sphinx_autobuild/filter.py b/sphinx_autobuild/filter.py index b260c9d..1df0808 100644 --- a/sphinx_autobuild/filter.py +++ b/sphinx_autobuild/filter.py @@ -24,7 +24,7 @@ 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: + if os.getenv("SPHINX_AUTOBUILD_DEBUG") not in (None, "", "0"): print( f"SPHINX_AUTOBUILD_DEBUG: {normalised_path!r} has changed; " f"ignores are {self}" diff --git a/tests/test_ignore.py b/tests/test_ignore.py index 064df03..49a8571 100644 --- a/tests/test_ignore.py +++ b/tests/test_ignore.py @@ -78,17 +78,14 @@ def test_multiple_both(): assert ignored("bar/__pycache__/file.pyc") -@pytest.mark.parametrize("is_debug", [True, False]) -def test_debug(is_debug, capfd): - if is_debug: - # also "0" is considered to mean "print debug output": - os.environ["SPHINX_AUTOBUILD_DEBUG"] = "0" - else: - del os.environ["SPHINX_AUTOBUILD_DEBUG"] +@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 is_debug: + if val in ("y", "1", "whatever"): assert "SPHINX_AUTOBUILD_DEBUG" in captured.out else: assert "SPHINX_AUTOBUILD_DEBUG" not in captured.out From 5e18308b7617d11981742ec147e3772b4552f654 Mon Sep 17 00:00:00 2001 From: Adam Turner <9087854+AA-Turner@users.noreply.github.com> Date: Mon, 25 Aug 2025 16:37:00 +0100 Subject: [PATCH 4/4] Update sphinx_autobuild/filter.py --- sphinx_autobuild/filter.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sphinx_autobuild/filter.py b/sphinx_autobuild/filter.py index 1df0808..2a84b71 100644 --- a/sphinx_autobuild/filter.py +++ b/sphinx_autobuild/filter.py @@ -24,7 +24,7 @@ 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"): + if os.getenv("SPHINX_AUTOBUILD_DEBUG") not in {None, "", "0"}: print( f"SPHINX_AUTOBUILD_DEBUG: {normalised_path!r} has changed; " f"ignores are {self}"