fix(docs): gate gallery example execution on TTTRLIB_DOCS_EXECUTE_EXAMPLES

The committed conf.py hard-coded sphinx_gallery_conf['plot_gallery']=True,
so the 'Build Documentation' CI job executed every gallery example even
though it sets TTTRLIB_DOCS_EXECUTE_EXAMPLES=0 and only provisions a
minimal test-data set. Examples whose data is absent hit their
'raise SystemExit(0)' guards; SystemExit derives from BaseException, so
sphinx-gallery (which only catches Exception) let it propagate and
terminate sphinx-build with exit 0 before the HTML write phase. The job
then failed in check_docs_pages.py with 'No HTML pages found'.

Gate plot_gallery on TTTRLIB_DOCS_EXECUTE_EXAMPLES (default off), matching
the passing rattler docs recipe. With execution off, examples render as
source-only gallery pages, the build completes, and the coverage/page
checks pass. Also carries the source_suffix/notebook-exclude and theme
tweaks staged alongside it.

Author: tpeulen

doc/conf.py

@@ -60,14 +60,6 @@
 root_doc = "index"
 master_doc = "index"
 
-# Accept both .rst and .ipynb as source files
-# --- Make sure notebooks are parsed as notebooks ---
-# Sphinx 4–7: either form is fine; this one is explicit and robust
-source_suffix = {
-    ".rst": "restructuredtext"
-}
-print("[conf] source_suffix   :", source_suffix)
-
 templates_path = ["_templates"] if (HERE / "_templates").exists() else []
 
 # Exclusions (keep minimal at tier 0)
@@ -163,6 +155,18 @@ def _try_import(modname: str) -> bool:
     for e in NB_EXTS:
         if _try_import(e):
             extensions.append(e)
+    if "nbsphinx" in extensions:
+        source_suffix = {
+            ".rst": "restructuredtext",
+            ".ipynb": "jupyter_notebook",
+        }
+        # Sphinx-Gallery writes notebooks for download. They should not become
+        # independent source documents because each gallery example already has
+        # a generated .rst page.
+        exclude_patterns += [
+            "auto_examples/**/*.ipynb",
+            "auto_examples/*.ipynb",
+        ]
     # Conservative notebook settings
     nbsphinx_execute = "never"
     nbsphinx_allow_errors = True
@@ -174,6 +178,12 @@ def _try_import(modname: str) -> bool:
 print("[conf] exclude_patterns:", exclude_patterns)
 print("[conf] extensions", extensions)
 
+if "source_suffix" not in globals():
+    source_suffix = {
+        ".rst": "restructuredtext",
+    }
+print("[conf] source_suffix   :", source_suffix)
+
 if BUILD_TIER >= 4:
     # Headless + no-op show (helps avoid hanger)
     os.environ.setdefault("MPLBACKEND", "Agg")
@@ -230,7 +240,7 @@ def _try_import(modname: str) -> bool:
             "gallery_dirs": ["auto_examples"],
             "filename_pattern": r"plot_.*\.py$",
             "ignore_pattern": ignore_pat,     # <-- blacklist in effect
-            "plot_gallery": True,
+            "plot_gallery": os.environ.get("TTTRLIB_DOCS_EXECUTE_EXAMPLES", "0").lower() in {"1", "true", "yes", "on"},
             "image_scrapers": ("matplotlib",),
             "reset_modules": ("matplotlib",),
             "remove_config_comments": True,
@@ -275,11 +285,9 @@ def _first_available_theme(candidates):
 html_domain_indices = False
 html_use_index = False
 
-# Theme options kept minimal to reduce breakage
-html_theme_options = {
-    "navigation_depth": 3,
-    "show_toc_level": 2,
-}
+html_theme_options = {"navigation_depth": 3}
+if html_theme == "pydata_sphinx_theme":
+    html_theme_options["show_toc_level"] = 2
 
 # Optional sidebars only if the theme ships them
 html_sidebars = {