docs

Author: juanitorduz

AGENTS.md

@@ -31,6 +31,24 @@
 - **Build**: Use `make html` to build documentation
 - **Doctest**: Use `make doctest` to test that Python examples in doctests work
 
+### Adding new notebooks to the gallery
+
+When creating a new example notebook:
+
+1. **Place it** in `docs/source/notebooks/` with naming pattern `{method}_{model}.ipynb`
+2. **Include at least one plot** in the notebook outputs (the first PNG image will be used as the thumbnail)
+3. **Manually add it to `docs/source/notebooks/index.md`**:
+   - Find the appropriate category section or create a new one
+   - Add a `grid-item-card` entry with:
+     - `:img-top: ../_static/thumbnails/{notebook_name}.png` (thumbnail path)
+     - `:link: {notebook_name_without_extension}` (notebook name without `.ipynb`)
+     - `:link-type: doc`
+   - Cards are arranged in 3-column grids using `sphinx-design`
+4. **Thumbnails are generated automatically** during the build process by `scripts/generate_gallery.py` (runs via `conf.py` during Sphinx setup)
+5. **Test locally** with `make html` and check `docs/_build/html/notebooks/index.html`
+
+**Important**: The `index.md` file is manually maintained. The `generate_gallery.py` script only generates thumbnails; it does not modify `index.md`. Thumbnails are gitignored (`docs/source/_static/thumbnails/`) and generated on-demand during builds.
+
 ## Code structure and style
 
 - **Experiment classes**: All experiment classes inherit from `BaseExperiment` in `causalpy/experiments/`. Must declare `supports_ols` and `supports_bayes` class attributes. Only implement abstract methods for supported model types (e.g., if only Bayesian is supported, implement `_bayesian_plot()` and `get_plot_data_bayesian()`; if only OLS is supported, implement `_ols_plot()` and `get_plot_data_ols()`)

CONTRIBUTING.md

@@ -149,6 +149,43 @@ We recommend that your contribution complies with the following guidelines befor
 
 - When adding additional functionality, either edit an existing example, or create a new example (typically in the form of a Jupyter Notebook). Have a look at other examples for reference. Examples should demonstrate why the new functionality is useful in practice.
 
+### Adding a new example notebook
+
+When adding a new example notebook to the documentation gallery:
+
+1. **Place the notebook** in `docs/source/notebooks/` following the naming convention `{method}_{model}.ipynb` (e.g., `did_pymc.ipynb`, `rd_skl.ipynb`).
+
+2. **Ensure the notebook has at least one plot/figure** in its outputs. The gallery generation script (`scripts/generate_gallery.py`) will automatically extract the first PNG image from the notebook outputs to create a thumbnail. If the notebook has no outputs, the script will attempt to execute it to generate the thumbnail.
+
+3. **Add the notebook to the gallery** by manually editing `docs/source/notebooks/index.md`:
+   - Find the appropriate category section (e.g., "Difference in Differences", "Regression Discontinuity") or create a new one if needed
+   - Add a new `grid-item-card` entry within the category's grid, following this format:
+     ```markdown
+     :::{grid-item-card} Your Notebook Title
+     :class-card: sd-card-h-100
+     :img-top: ../_static/thumbnails/{notebook_name}.png
+     :link: {notebook_name_without_extension}
+     :link-type: doc
+     :::
+     ```
+   - The `:img-top:` path should reference `../_static/thumbnails/{notebook_name}.png` (the thumbnail will be generated automatically)
+   - The `:link:` should be the notebook name without the `.ipynb` extension
+   - Cards are arranged in a 3-column grid layout
+
+4. **Generate thumbnails locally** (optional, for testing):
+   ```bash
+   python scripts/generate_gallery.py
+   ```
+   Thumbnails are automatically generated during the documentation build process, so you don't need to commit them (the `docs/source/_static/thumbnails/` directory is gitignored).
+
+5. **Build and test the documentation** to verify the notebook appears correctly in the gallery:
+   ```bash
+   make html
+   ```
+   Then open `docs/_build/html/notebooks/index.html` in your browser to see the gallery.
+
+**Note**: The gallery generation script (`scripts/generate_gallery.py`) runs automatically during the Sphinx build process (configured in `docs/source/conf.py`), so thumbnails will be generated on Read the Docs builds without needing to commit them.
+
 - Documentation and high-coverage tests are necessary for enhancements to be accepted.
 
 - Documentation follows [NumPy style guide](https://numpydoc.readthedocs.io/en/latest/format.html)