Add Example Gallery

.readthedocs.yml

@@ -3,16 +3,21 @@
 version: 2
 
 sphinx:
-    configuration: docs/source/conf.py
+  configuration: docs/source/conf.py
 
 build:
   os: ubuntu-22.04
   tools:
     python: "3.10"
+  jobs:
+    pre_build:
+      # Install core dependencies first
+      - pip install --upgrade pip setuptools wheel
+      - python scripts/generate_gallery.py
 
 python:
-   install:
-   - method: pip
-     path: .
-     extra_requirements:
-       - docs
+  install:
+    - method: pip
+      path: .
+      extra_requirements:
+        - docs

Makefile

@@ -37,6 +37,7 @@ test:  ## Install test dependencies and run tests
 
 html: ## Install documentation dependencies and build HTML docs
 	pip install .[docs]
+	python scripts/generate_gallery.py
 	sphinx-build docs/source docs/build -b html
 
 cleandocs: ## Clean the documentation build directories

docs/source/gallery/README.md

@@ -0,0 +1,29 @@
+# PyMC-Marketing Example Gallery
+
+This directory contains the gallery view for the PyMC-Marketing example notebooks.
+
+## Gallery Structure
+
+The gallery displays thumbnails and links to all example notebooks, organized by category.
+
+## Adding New Examples to the Gallery
+
+When adding new example notebooks:
+
+1. Add the notebook to the appropriate directory in `docs/source/notebooks/`
+2. Update the gallery entry in `gallery.md`
+3. Create a thumbnail image for the notebook (ideally a screenshot of a key visualization from the notebook) and place it in the `images/` directory
+4. Run `python create_gallery_images.py` to generate a placeholder thumbnail if you don't have a specific image
+
+## Gallery Images
+
+The gallery uses thumbnail images to provide visual navigation. For best results:
+
+- Images should be in PNG format
+- Images should have a 4:3 aspect ratio
+- Size should be approximately 600x450 pixels
+- Names should match the notebook filename
+
+## Updating the Gallery
+
+The gallery is structured using the Sphinx Design extension's grid layout. See the [Sphinx Design documentation](https://sphinx-design.readthedocs.io/en/latest/grids.html) for more information on customizing the grid layout.

docs/source/gallery/gallery.md

@@ -0,0 +1,196 @@
+# Example Gallery
+
+```{toctree}
+:hidden:
+```
+
+## Introduction
+
+Welcome to the PyMC-Marketing example gallery! This gallery provides visual navigation to all of our example notebooks to help you quickly find the techniques and models relevant to your marketing analytics needs.
+
+## Marketing Mix Models (MMM)
+
+### Fundamentals
+
+::::{grid} 1 2 3 3
+:gutter: 3
+
+:::{grid-item-card} MMM Example Notebook
+:img-top: ../gallery/images/mmm_example.png
+:link: ../notebooks/mmm/mmm_example.html
+:::
+
+:::{grid-item-card} Custom Models with MMM components
+:img-top: ../gallery/images/mmm_components.png
+:link: ../notebooks/mmm/mmm_components.html
+:::
+
+:::{grid-item-card} MMM Multidimensional Example Notebook (e.g. Geo-MMM)
+:img-top: ../gallery/images/mmm_multidimensional_example.png
+:link: ../notebooks/mmm/mmm_multidimensional_example.html
+:::
+::::
+
+### Budget Allocation
+
+::::{grid} 1 2 3 3
+:gutter: 3
+
+:::{grid-item-card} Budget Allocation Example
+:img-top: ../gallery/images/mmm_budget_allocation_example.png
+:link: ../notebooks/mmm/mmm_budget_allocation_example.html
+:::
+
+:::{grid-item-card} Budget Allocation Risk Assessment
+:img-top: ../gallery/images/mmm_allocation_assessment.png
+:link: ../notebooks/mmm/mmm_allocation_assessment.html
+:::
+::::
+
+### Lift Test Calibration
+
+::::{grid} 1 2 3 3
+:gutter: 3
+
+:::{grid-item-card} Lift Test Analysis
+:img-top: ../gallery/images/mmm_lift_test.png
+:link: ../notebooks/mmm/mmm_lift_test.html
+:::
+
+:::{grid-item-card} Case Study: Unobserved Confounders, ROAS and Lift Tests
+:img-top: ../gallery/images/mmm_roas.png
+:link: ../notebooks/mmm/mmm_roas.html
+:::
+::::
+
+### Time-Varying Parameters
+
+::::{grid} 1 2 3 3
+:gutter: 3
+
+:::{grid-item-card} MMM with time-varying parameters
+:img-top: ../gallery/images/mmm_tvp_example.png
+:link: ../notebooks/mmm/mmm_tvp_example.html
+:::
+
+:::{grid-item-card} MMM with time-varying media baseline
+:img-top: ../gallery/images/mmm_time_varying_media_example.png
+:link: ../notebooks/mmm/mmm_time_varying_media_example.html
+:::
+::::
+
+### Model Evaluation
+
+::::{grid} 1 2 3 3
+:gutter: 3
+
+:::{grid-item-card} Cross-Validation
+:img-top: ../gallery/images/mmm_time_slice_cross_validation.png
+:link: ../notebooks/mmm/mmm_time_slice_cross_validation.html
+:::
+
+:::{grid-item-card} Model Evaluation
+:img-top: ../gallery/images/mmm_evaluation.png
+:link: ../notebooks/mmm/mmm_evaluation.html
+:::
+::::
+
+### Causal Inference
+
+::::{grid} 1 2 3 3
+:gutter: 3
+
+:::{grid-item-card} Causal Identification
+:img-top: ../gallery/images/mmm_causal_identification.png
+:link: ../notebooks/mmm/mmm_causal_identification.html
+:::
+
+:::{grid-item-card} MMMs and Pearl's ladder of causal inference
+:img-top: ../gallery/images/mmm_counterfactuals.png
+:link: ../notebooks/mmm/mmm_counterfactuals.html
+:::
+::::
+
+### Case Studies
+
+::::{grid} 1 2 3 3
+:gutter: 3
+
+:::{grid-item-card} MMM Case Study
+:img-top: ../gallery/images/mmm_case_study.png
+:link: ../notebooks/mmm/mmm_case_study.html
+:::
+::::
+
+## Customer Lifetime Value (CLV) Models
+
+::::{grid} 1 2 3 3
+:gutter: 3
+
+:::{grid-item-card} CLV Quickstart
+:img-top: ../gallery/images/clv_quickstart.png
+:link: ../notebooks/clv/clv_quickstart.html
+:::
+
+:::{grid-item-card} BG/NBD Model
+:img-top: ../gallery/images/bg_nbd.png
+:link: ../notebooks/clv/bg_nbd.html
+:::
+
+:::{grid-item-card} MBG/NBD Model
+:img-top: ../gallery/images/mbg_nbd.png
+:link: ../notebooks/clv/mbg_nbd.html
+:::
+
+:::{grid-item-card} Pareto/NBD Model
+:img-top: ../gallery/images/pareto_nbd.png
+:link: ../notebooks/clv/pareto_nbd.html
+:::
+
+:::{grid-item-card} Gamma-Gamma Model
+:img-top: ../gallery/images/gamma_gamma.png
+:link: ../notebooks/clv/gamma_gamma.html
+:::
+
+:::{grid-item-card} sBG Model
+:img-top: ../gallery/images/sBG.png
+:link: ../notebooks/clv/sBG.html
+:::
+::::
+
+## Customer Choice Models
+
+::::{grid} 1 2 3 3
+:gutter: 3
+
+:::{grid-item-card} MV-ITS Saturated
+:img-top: ../gallery/images/mv_its_saturated.png
+:link: ../notebooks/customer_choice/mv_its_saturated.html
+:::
+
+:::{grid-item-card} MV-ITS Unsaturated
+:img-top: ../gallery/images/mv_its_unsaturated.png
+:link: ../notebooks/customer_choice/mv_its_unsaturated.html
+:::
+::::
+
+## General Tutorials
+
+::::{grid} 1 2 3 3
+:gutter: 3
+
+:::{grid-item-card} Model Configuration
+:img-top: ../gallery/images/model_configuration.png
+:link: ../notebooks/general/model_configuration.html
+:::
+
+:::{grid-item-card} Prior Predictive Checks
+:img-top: ../gallery/images/prior_predictive.png
+:link: ../notebooks/general/prior_predictive.html
+:::
+
+:::{grid-item-card} NUTS Samplers
+:img-top: ../gallery/images/other_nuts_samplers.png
+:link: ../notebooks/general/other_nuts_samplers.html
+:::
+::::

docs/source/index.md

@@ -55,9 +55,33 @@ We provide the following professional services:
 
 ## Quick links
 
-:::::{grid} 1 1 2 2
+:::::{grid} 1 1 2 3
 :gutter: 2
 
+::::{grid-item-card} Example Gallery
+:class-header: sd-text-center no-border
+:class-title: sd-text-center
+:class-footer: no-border
+
+{material-outlined}`photo_library;5em`
+^^^^^^^^^^^^^^^
+
+Browse our visual gallery of example notebooks to quickly
+find the techniques and models relevant to your
+marketing analytics needs.
+
++++
+
+:::{button-ref} gallery/gallery
+:expand:
+:color: secondary
+:click-parent:
+:ref-type: doc
+
+To the example gallery
+:::
+::::
+
 ::::{grid-item-card} Example notebooks
 :class-header: sd-text-center no-border
 :class-title: sd-text-center
@@ -110,7 +134,7 @@ To the reference guide
 
 ## Bayesian Marketing Mix Modeling (MMM) in PyMC
 
-Leverage our Bayesian MMM API to tailor your marketing strategies effectively. Leveraging on top of the research article [Jin, Yuxue, et al. “Bayesian methods for media mix modeling with carryover and shape effects.” (2017)](https://research.google/pubs/pub46001/),  and extending it by integrating the expertise from core PyMC developers, our API provides:
+Leverage our Bayesian MMM API to tailor your marketing strategies effectively. Leveraging on top of the research article [Jin, Yuxue, et al. "Bayesian methods for media mix modeling with carryover and shape effects." (2017)](https://research.google/pubs/pub46001/),  and extending it by integrating the expertise from core PyMC developers, our API provides:
 
 | Feature                                    | Benefit                                                                                                                                                                                                                                                                                                                                                                                 |
 | ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -207,5 +231,6 @@ getting_started/index
 contributing/index
 guide/index
 api/index
+gallery/gallery
 notebooks/index
 :::

pyproject.toml

@@ -41,11 +41,7 @@ dependencies = [
 ]
 
 [project.optional-dependencies]
-dag = [
-    "dowhy",
-    "networkx",
-    "osqp<1.0.0,>=0.6.2",
-]
+dag = ["dowhy", "networkx", "osqp<1.0.0,>=0.6.2"]
 docs = [
     "blackjax",
     "fastprogress",