Build notebooks into a gallery

.gitignore

@@ -131,3 +131,4 @@ dmypy.json
 .pyre/
 
 docs/generated/
+docs/notebooks-examples-gallery.txt

.pre-commit-config.yaml

@@ -59,3 +59,7 @@ repos:
     rev: v1.9.0
     hooks:
       - id: mypy
+        additional_dependencies: [
+            # Type stubs
+            types-PyYAML,
+          ]

ci/doc.yml

@@ -3,12 +3,39 @@ channels:
   - conda-forge
   - nodefaults
 dependencies:
-  - python=3.9
+  # Building docs
+  - python=3.10
   - pre-commit
   - pip
   - sphinx>=5.0
   - sphinx-book-theme >= 0.3.0
+  - sphinx-copybutton
+  - sphinx-design
   - numpydoc
   - myst-parser
+  - nbsphinx
+  # Running examples
+  - dask
+  - esmpy>=8.2.0
+  - mpich
+  - netcdf4
+  - numpy
+  - pooch
+  - pydantic>=1.10
+  - pyproj
+  - pyresample
+  - rasterio
+  - rioxarray
+  - s3fs
+  - scipy
+  - sparse>=0.13.0
+  - xarray
+  - xarray-datatree>=0.0.11
+  - xesmf
+  - zarr
+  - cf_xarray>=0.8.0
+  - fastparquet
+  - matplotlib
+  - ipykernel
   - pip:
-      - -e "..[xesmf]"
+      - -e ..

docs/conf.py

@@ -6,8 +6,15 @@
 # -- Project information -----------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
 
-
+import pathlib
 import sys
+from textwrap import dedent, indent
+
+import yaml
+from sphinx.application import Sphinx
+from sphinx.util import logging
+
+LOGGER = logging.getLogger('conf')
 
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
@@ -28,9 +35,14 @@
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
 
 extensions = [
+    'IPython.sphinxext.ipython_directive',
+    'IPython.sphinxext.ipython_console_highlighting',
     'myst_parser',
     'sphinx.ext.autodoc',
+    'sphinx_copybutton',
     'sphinx.ext.autosummary',
+    'sphinx_design',
+    'nbsphinx',
 ]
 
 autosummary_generate = True
@@ -59,3 +71,45 @@
 repository_url = 'https://github.com/carbonplan/ndpyramid'
 
 html_static_path = ['_static']
+
+
+def update_gallery(app: Sphinx):
+    """
+    Update the gallery page.
+
+    Copied from https://github.com/pydata/xarray/blob/56209bd9a3192e4f1e82c21e5ffcf4c3bacaaae3/doc/conf.py#L399-L430.
+    """
+
+    LOGGER.info('Updating gallery page...')
+
+    gallery = yaml.safe_load(pathlib.Path(app.srcdir, 'gallery.yml').read_bytes())
+
+    for key in gallery:
+        items = [
+            f"""
+         .. grid-item-card::
+            :text-align: center
+            :link: {item['path']}
+
+            .. image:: {item['thumbnail']}
+                :alt: {item['title']}
+            +++
+            {item['title']}
+            """
+            for item in gallery[key]
+        ]
+
+        items_md = indent(dedent('\n'.join(items)), prefix='    ')
+        markdown = f"""
+.. grid:: 1 2 2 2
+    :gutter: 2
+
+    {items_md}
+    """
+        pathlib.Path(app.srcdir, f'{key}-gallery.txt').write_text(markdown)
+        LOGGER.info(f'{key} gallery page updated.')
+    LOGGER.info('Gallery page updated.')
+
+
+def setup(app: Sphinx):
+    app.connect('builder-inited', update_gallery)