chore: Add sphinx-gallery.

.gitignore

@@ -111,3 +111,5 @@ venv.bak/
 # Generated files
 src/python/pyfes/version.py
 include/fes/version.hpp
+docs/source/auto_examples
+docs/source/sg_execution_times.rst

conda/environment.yml

@@ -16,3 +16,4 @@ dependencies:
   - gtest
   - sphinx
   - sphinx-book-theme
+  - sphinx-gallery

docs/source/conf.py

@@ -40,17 +40,19 @@ def push_front_syspath():
 try:
     release = importlib.metadata.version(project)
 except importlib.metadata.PackageNotFoundError:
-    import setuptools_scm
     try:
-        release = setuptools_scm.get_version()
-    except LookupError:
+        import pyfes
+        release = pyfes.__version__
+        release = '.'.join(release.split('.')[:3])
+    except ImportError:
         release = '0.0.0'
 version = '.'.join(release.split('.')[:2])
 
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
 
 extensions = [
+    'sphinx_gallery.gen_gallery',
     'sphinx.ext.autodoc',
     'sphinx.ext.autosummary',
     'sphinx.ext.mathjax',
@@ -75,6 +77,21 @@ def push_front_syspath():
     'MatrixComplex128': 'MatrixComplex128',
 }
 
+sphinx_gallery_conf = {
+    'examples_dirs': [HERE.parent.parent.joinpath('examples')],
+    'filename_pattern': r'[\\\/]ex_',
+    'pypandoc': False,
+    # 'binder': {
+    #     'org': 'CNES',
+    #     'repo': 'aviso-fes',
+    #     'branch': 'main',
+    #     'binderhub_url': 'https://mybinder.org',
+    #     'dependencies':
+    #     [HERE.joinpath('..', '..', 'binder', 'environment.yml')],
+    #     'use_jupyter_lab': True,
+    # }
+}
+
 exclude_patterns = []
 
 # -- Options for HTML output -------------------------------------------------

docs/source/index.rst

@@ -6,6 +6,7 @@ PyFES documentation
    :caption: Contents:
 
    setup
+   auto_examples/index.rst
    pyfes
    api
    core

examples/README.rst

@@ -0,0 +1,5 @@
+Example Gallery
+===============
+
+This gallery of examples shows a variety of relatively small snippets or
+examples of tasks that can be done with this package.

examples/lgp_interpolation.py → examples/ex_interpolation.py

@@ -23,8 +23,8 @@
 import pyfes
 
 # %%
-MODEL = str(pathlib.Path().absolute().parent / 'tests' / 'python' / 'dataset' /
-            'fes_2014.nc')
+MODEL = str(pathlib.Path().absolute().parent / 'src' / 'python' / 'pyfes' /
+            'tests' / 'dataset' / 'fes_2014.nc')
 
 
 # %%
@@ -101,7 +101,16 @@ def load_model(
 ax = fig.add_subplot(1, 1, 1, projection=ccrs.PlateCarree())
 ax.set_extent([-5.0, 10.0, 40.0, 55.0], crs=ccrs.PlateCarree())
 ax.coastlines()
-ax.contourf(lon, lat, grid, 100, transform=ccrs.PlateCarree())
+levels = np.arange(0, 400, 10)
+contour = ax.contourf(lon,
+                      lat,
+                      grid,
+                      100,
+                      transform=ccrs.PlateCarree(),
+                      levels=levels,
+                      cmap='terrain')
+cbar = plt.colorbar(contour, ax=ax, orientation='vertical')
+cbar.set_label('Amplitude (cm)')
 plt.show()
 
 # %%
@@ -128,6 +137,14 @@ def load_model(
 ax = fig.add_subplot(1, 1, 1, projection=ccrs.PlateCarree())
 ax.set_extent([-5.0, 10.0, 40.0, 55.0], crs=ccrs.PlateCarree())
 ax.coastlines()
-ax.contourf(lon, lat, grid, 100, transform=ccrs.PlateCarree())
+contour = ax.contourf(lon,
+                      lat,
+                      grid,
+                      100,
+                      transform=ccrs.PlateCarree(),
+                      levels=levels,
+                      cmap='terrain')
+cbar = plt.colorbar(contour, ax=ax, orientation='vertical')
+cbar.set_label('Amplitude (cm)')
 plt.show()
 # %%

examples/fes_mapping.py → examples/ex_mapping.py

@@ -1,7 +1,7 @@
 """
-******************
+********************
 Tide mapping example
-******************
+********************
 
 In this example, we will use the model to predict the tidal elevation on a
 global grid. The model used is an old FES tidel-atlas model. Do not use it for
@@ -23,8 +23,8 @@
 
 # %%
 # First we create an environment variable to store the path to the model file.
-os.environ['DATASET_DIR'] = str(pathlib.Path().absolute() / 'src' / 'python' /
-                                'pyfes' / 'tests' / 'dataset')
+os.environ['DATASET_DIR'] = str(pathlib.Path().absolute().parent / 'src' /
+                                'python' / 'pyfes' / 'tests' / 'dataset')
 
 # %%
 # Now we need to create the instances of the model used to calculate the ocean
@@ -33,7 +33,7 @@
 # documented in the :ref:`documentation <confguration_file>`.
 handlers: dict[str, pyfes.core.AbstractTidalModelComplex128
                | pyfes.core.AbstractTidalModelComplex64]
-handlers = pyfes.load_config(pathlib.Path(__file__).parent / 'fes_slev.yml')
+handlers = pyfes.load_config(pathlib.Path().absolute() / 'fes_slev.yml')
 
 # %%
 # ``handlers`` is a dictionary that contains the handlers to the ocean and
@@ -73,7 +73,7 @@
 
 # %%
 # We can now plot the result.
-fig = plt.figure(figsize=(22, 10))
+fig = plt.figure(figsize=(10, 5))
 ax = fig.add_subplot(1, 1, 1, projection=ccrs.PlateCarree())
 ax.coastlines()
 ax.set_global()

examples/fes_prediction.py → examples/ex_prediction.py

@@ -7,7 +7,7 @@
 specific location, like a tide gauge. The model used is an old FES tidel-atlas
 model. Do not use it for real applications. You can download the model from the
 AVISO `website
->https://www.aviso.altimetry.fr/en/data/products/auxiliary-products/global-tide-fes.html>`_.
+<https://www.aviso.altimetry.fr/en/data/products/auxiliary-products/global-tide-fes.html>`_.
 
 First, we import the required modules.
 """
@@ -22,15 +22,15 @@
 
 # %%
 # First we create an environment variable to store the path to the model file.
-os.environ['DATASET_DIR'] = str(pathlib.Path().absolute() / 'src' / 'python' /
-                                'pyfes' / 'tests' / 'dataset')
+os.environ['DATASET_DIR'] = str(pathlib.Path().absolute().parent / 'src' /
+                                'python' / 'pyfes' / 'tests' / 'dataset')
 
 # %%
 # Now we need to create the instances of the model used to calculate the ocean
 # tide and the radial tide. To do this, we need to create a YAML file that
 # describes the models and their parameters. The configuration file is fully
 # documented in the :ref:`documentation >confguration_file>`.
-handlers = pyfes.load_config(pathlib.Path(__file__).parent / 'fes_slev.yml')
+handlers = pyfes.load_config(pathlib.Path().absolute() / 'fes_slev.yml')
 
 # %%
 # ``handlers`` is a dictionary that contains the handlers to the ocean and
@@ -69,10 +69,11 @@
 cnes_julian_days = (dates - numpy.datetime64('1950-01-01T00:00:00')
                     ).astype('M8[s]').astype(float) / 86400
 hours = cnes_julian_days % 1 * 24
-print(f"{'JulDay':>6s} {'Hour':>5s} {'Latitude':>11s} {'Longitude':>11s} "
-      f"{'Short_tide':>11s} {'LP_tide':>11s} {'Pure_Tide':>11s} "
-      f"{'Geo_Tide':>11s} {'Rad_Tide':>11s}")
+print(f"{'JulDay':>6s} {'Hour':>5s} {'Latitude':>10s} {'Longitude':>10s} "
+      f"{'Short_tide':>10s} {'LP_tide':>10s} {'Pure_Tide':>10s} "
+      f"{'Geo_Tide':>10s} {'Rad_Tide':>10s}")
+print('=' * 89)
 for ix, jd in enumerate(cnes_julian_days):
-    print(f'{jd:>6.0f} {hours[ix]:>5.0f} {lats[ix]:>11.3f} {lons[ix]:>11.3f} '
-          f'{tide[ix]:>11.3f} {lp[ix]:>11.3f} {tide[ix] + lp[ix]:>11.3f} '
-          f'{tide[ix] + lp[ix] + load[ix]:>11.3f} {load[ix]:>11.3f}')
+    print(f'{jd:>6.0f} {hours[ix]:>5.0f} {lats[ix]:>10.3f} {lons[ix]:>10.3f} '
+          f'{tide[ix]:>10.3f} {lp[ix]:>10.3f} {tide[ix] + lp[ix]:>10.3f} '
+          f'{tide[ix] + lp[ix] + load[ix]:>10.3f} {load[ix]:>10.3f}')