test gallery

docs/conf.py

@@ -46,12 +46,21 @@
     'sphinx.ext.viewcode',
     'IPython.sphinxext.ipython_directive',
     'IPython.sphinxext.ipython_console_highlighting',
+    'sphinx_gallery.gen_gallery',
 ]
 
 extlinks = {'issue': ('https://github.com/fmaussion/salem/issues/%s', 'GH'),
             'pull': ('https://github.com/fmaussion/salem/pull/%s', 'PR'),
             }
 
+sphinx_gallery_conf = {
+    # path to your examples scripts
+    'examples_dirs': 'examples',
+    # path where to save gallery generated examples
+    'gallery_dirs': 'auto_examples'
+}
+
+
 autosummary_generate = True
 
 numpydoc_class_members_toctree = True

docs/environment.yml

@@ -22,3 +22,4 @@ dependencies:
   - sphinx=1.2.3  # pin to avoid https://github.com/sphinx-doc/sphinx/issues/1822
   - pip:
     - git+https://github.com/fmaussion/motionless.git
+    - sphinx-gallery

docs/examples/README.txt

@@ -0,0 +1,9 @@
+.. _recipes:
+
+Recipes
+=======
+
+Plot examples
+-------------
+
+General-purpose examples

docs/examples/plot_topo_shading.py

@@ -0,0 +1,24 @@
+# -*- coding: utf-8 -*-
+"""
+==============
+Add topography
+==============
+
+Here we add topography to the plot.
+
+"""
+
+from salem import mercator_grid, Map, get_demo_file
+import matplotlib.pyplot as plt
+
+grid = mercator_grid(center_ll=(10.76, 46.798444),
+                     extent=(10000, 7000))
+c = Map(grid, countries=False)
+c.set_lonlat_contours(interval=10)
+c.set_shapefile(get_demo_file('Hintereisferner_UTM.shp'))
+c.set_topography(get_demo_file('hef_srtm.tif'))
+
+fig, ax = plt.subplots(1, 1)
+c.visualize(ax=ax, addcbar=False, title='Default: spline deg 3')
+plt.tight_layout()
+plt.show()

docs/index.rst

@@ -39,8 +39,10 @@ Documentation
     gis
     plotting
     wrf
+    auto_examples/index
     api
 
+
 Get in touch
 ------------
 

salem/sio.py

@@ -395,7 +395,7 @@ def __init__(self, xarray_obj):
         dim = utils.str_in_list(dn, utils.valid_names['z_dim'])
         self.z_dim = dim[0] if dim else None
 
-    def subset(self, margin=0, **kwargs):
+    def subset(self, margin=0, ds=None, **kwargs):
         """subset(self, margin=0, shape=None, geometry=None, grid=None,
                   corners=None, crs=wgs84, roi=None)
 
@@ -405,6 +405,8 @@ def subset(self, margin=0, **kwargs):
 
         Parameters
         ----------
+        ds : Dataset or DataArray
+            form the ROI from the extent of the Dataset or DataArray
         shape : str
             path to a shapefile
         geometry : geometry
@@ -424,6 +426,10 @@ def subset(self, margin=0, **kwargs):
             five pixels from each boundary of the dataset.
         """
 
+        if ds is not None:
+            grid = ds.salem.grid
+            kwargs.setdefault('grid', grid)
+
         mask = self.grid.region_of_interest(**kwargs)
         if not kwargs:
             # user just wants a margin