Example Gallery

.gitignore

@@ -14,3 +14,5 @@ dist/
 docs/build/
 docs/jupyter_execute/
 docs/source/api/generated/
+docs/source/_static/thumbnails/
+# Note: thumbnails are generated during build (see .readthedocs.yaml)

Makefile

@@ -8,7 +8,7 @@ PACKAGE_DIR = causalpy
 # COMMANDS                                                                      #
 #################################################################################
 
-.PHONY: init lint check_lint test uml html cleandocs doctest help
+.PHONY: init lint check_lint test uml gallery html cleandocs doctest help
 
 init: ## Install the package in editable mode
 	python -m pip install -e . --no-deps
@@ -31,7 +31,10 @@ test: ## Run all tests with pytest
 uml: ## Generate UML diagrams from code
 	pyreverse -o png causalpy --output-directory docs/source/_static --ignore tests
 
-html: ## Build HTML documentation with Sphinx
+gallery: ## Generate example gallery from notebooks
+	python scripts/generate_gallery.py
+
+html: gallery ## Build HTML documentation with Sphinx
 	sphinx-build -b html docs/source docs/_build
 
 cleandocs: ## Clean the documentation build directories

docs/source/_static/gallery.css

@@ -0,0 +1,36 @@
+/* Custom CSS for uniform gallery card sizes - square-like cards */
+.sd-card {
+    height: 100%;
+    display: flex;
+    flex-direction: column;
+}
+
+.sd-card-body {
+    flex-grow: 1;
+    display: flex;
+    flex-direction: column;
+    padding: 0.5rem;
+}
+
+.sd-card-img-top {
+    width: 100%;
+    height: 250px;
+    object-fit: contain;
+    background-color: #f8f9fa;
+    padding: 8px;
+}
+
+.sd-card-header {
+    padding: 0.75rem 0.5rem;
+    line-height: 1.3;
+    min-height: auto;
+}
+
+.sd-grid-item {
+    display: flex;
+}
+
+/* Ensure grid items stretch to same height */
+.sd-grid {
+    align-items: stretch;
+}

docs/source/conf.py

@@ -11,11 +11,40 @@
 
 import os
 import sys
+from pathlib import Path
 
 from causalpy.version import __version__
 
 sys.path.insert(0, os.path.abspath("../"))
 
+
+# Generate gallery before building docs
+# This runs after dependencies are installed but before Sphinx processes files
+def generate_gallery():
+    """Generate example gallery from notebooks."""
+    try:
+        # Import here to avoid errors if dependencies aren't available
+        import subprocess
+
+        repo_root = Path(__file__).parent.parent.parent
+        script_path = repo_root / "scripts" / "generate_gallery.py"
+
+        if script_path.exists():
+            result = subprocess.run(
+                [sys.executable, str(script_path)],
+                cwd=str(repo_root),
+                capture_output=True,
+                text=True,
+            )
+            if result.returncode != 0:
+                print(f"Warning: Gallery generation failed: {result.stderr}")
+    except Exception as e:
+        print(f"Warning: Could not generate gallery: {e}")
+
+
+# Generate gallery during Sphinx setup
+generate_gallery()
+
 # autodoc_mock_imports
 # This avoids autodoc breaking when it can't find packages imported in the code.
 # https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#confval-autodoc_mock_imports # noqa: E501
@@ -81,6 +110,13 @@
 exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
 master_doc = "index"
 
+# Suppress warnings for notebooks linked from gallery (not in toctree)
+suppress_warnings = [
+    "toc.not_included",  # Notebooks are linked from gallery, not toctree
+    "bibtex.duplicate_label",  # BibTeX duplicate labels (less critical)
+    "bibtex.duplicate_citation",  # BibTeX duplicate citations (less critical)
+]
+
 # bibtex config
 bibtex_bibfiles = ["references.bib"]
 bibtex_default_style = "unsrt"
@@ -138,6 +174,7 @@
 html_theme = "labs_sphinx_theme"
 html_static_path = ["_static"]
 html_favicon = "_static/favicon_logo.png"
+html_css_files = ["gallery.css"]
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
 # documentation.