MAINT - Add env variable to control test-them build location. (#1800)

* Add env variable to control test-them build location.

I needed this to debug some things, so why not send it as a PR.

See #1798, maybe this should be folded in #1759 ?

* Update tests/conftest.py

Co-authored-by: Daniel McCloy <dan@mccloy.info>

---------

Co-authored-by: Daniel McCloy <dan@mccloy.info>

tests/README.md

@@ -26,3 +26,18 @@ This directory contains the Python tests for the theme. These tests are built wi
 The ["Kitchen Sink" examples](https://pydata-sphinx-theme.readthedocs.io/en/stable/examples/kitchen-sink/index.html)
 are taken from [sphinx-themes.org](https://sphinx-themes.org/) and showcase
 components of the PyData Sphinx Theme, such as admonitions, lists, and headings.
+
+## visually debugging the test pages
+
+It can be useful to build and inspect the test pages in the browser.
+
+By default `nox -s test` will build the html in a temporary directory.
+You can change this by using the `PST_TEST_HTML_DIR` environment variable.
+
+For example:
+
+```
+$ PST_TEST_HTML_DIR=./debug-test-theme/ nox -s test
+```
+
+Will save all the generated html in the folders `./debug-test-theme/<test-name>/<site-name>`

tests/conftest.py

@@ -1,6 +1,7 @@
 """Configuration of the pytest session."""
 
 import re
+from os import environ
 from pathlib import Path
 from shutil import copytree
 from typing import Callable
@@ -65,11 +66,15 @@ def html_tree(self, *path) -> str:
 
 
 @pytest.fixture()
-def sphinx_build_factory(make_app: Callable, tmp_path: Path) -> Callable:
+def sphinx_build_factory(make_app: Callable, tmp_path: Path, request) -> Callable:
     """Return a factory builder pointing to the tmp directory."""
 
-    def _func(src_folder: Path, **kwargs) -> SphinxBuild:
+    def _func(src_folder: str, **kwargs) -> SphinxBuild:
         """Create the Sphinxbuild from the source folder."""
+        no_temp = environ.get("PST_TEST_HTML_DIR")
+        nonlocal tmp_path
+        if no_temp is not None:
+            tmp_path = Path(no_temp) / request.node.name / str(src_folder)
         srcdir = tmp_path / src_folder
         if sphinx.version_info < (7, 2):
             from sphinx.testing.path import path as sphinx_path