From 4715581e11b4c0cbdd4074e04744f33fd85413c5 Mon Sep 17 00:00:00 2001
From: Leonardo Uieda <leo@uieda.com>
Date: Tue, 18 Feb 2025 18:14:55 -0300
Subject: [PATCH] Add a gallery plot and API entrance

---
 doc/api/index.rst                         |  1 +
 doc/conf.py                               |  3 +-
 doc/gallery_src/morroco_speleothem_qdm.py | 50 +++++++++++++++++++++++
 ensaio/_fetchers.py                       |  2 +-
 4 files changed, 54 insertions(+), 2 deletions(-)
 create mode 100644 doc/gallery_src/morroco_speleothem_qdm.py

diff --git a/doc/api/index.rst b/doc/api/index.rst
index 9f2bb35b..14c8a2c0 100644
--- a/doc/api/index.rst
+++ b/doc/api/index.rst
@@ -18,6 +18,7 @@ List of functions and classes (API)
     ensaio.fetch_earth_gravity
     ensaio.fetch_earth_topography
     ensaio.fetch_lightning_creek_magnetic
+    ensaio.fetch_morroco_speleothem_qdm
     ensaio.fetch_osborne_magnetic
     ensaio.fetch_sierra_negra_topography
     ensaio.fetch_southern_africa_gravity
diff --git a/doc/conf.py b/doc/conf.py
index 1de5b6de..844c7a6e 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -47,6 +47,7 @@
     "xarray": ("https://docs.xarray.dev/en/stable/", None),
     "pooch": ("https://www.fatiando.org/pooch/latest/", None),
     "pygmt": ("https://www.pygmt.org/latest/", None),
+    "magali": ("https://www.fatiando.org/magali/latest/", None),
 }
 
 # Autosummary pages will be generated by sphinx-autogen instead of sphinx-build
@@ -89,7 +90,7 @@
     # Insert links to documentation of objects in the examples
     "reference_url": {"ensaio": None},
     # Use the PyGMT image scraper
-    "image_scrapers": (pygmt.sphinx_gallery.PyGMTScraper(),),
+    "image_scrapers": (pygmt.sphinx_gallery.PyGMTScraper(), "matplotlib"),
 }
 
 # HTML output configuration
diff --git a/doc/gallery_src/morroco_speleothem_qdm.py b/doc/gallery_src/morroco_speleothem_qdm.py
new file mode 100644
index 00000000..62fb704c
--- /dev/null
+++ b/doc/gallery_src/morroco_speleothem_qdm.py
@@ -0,0 +1,50 @@
+# Copyright (c) 2021 The Ensaio Developers.
+# Distributed under the terms of the BSD 3-Clause License.
+# SPDX-License-Identifier: BSD-3-Clause
+#
+# This code is part of the Fatiando a Terra project (https://www.fatiando.org)
+#
+"""
+QDM magnetic microscopy dataset of a speleothem from Morocco
+------------------------------------------------------------
+
+High-resolution magnetic map of a stalagmite sample from Wintimdouine Cave,
+Morocco, created using Quantum Diamond Microscope (QDM) measurements at Harvard
+University. The data were collected to explore the magnetic remanence
+properties of hematite and magnetite within the sample, providing insight into
+past geomagnetic field variations recorded in cave deposits.
+
+**Original source:** Carmo, Janine; Fu, Roger; Trindade, Ricardo; Piascik,
+Samuel (2023). QDM magnetic microscopy dataset of a speleothem from
+Morocco. figshare. Dataset.
+`10.6084/m9.figshare.22965200.v1 <https://doi.org/10.6084/m9.figshare.22965200.v1>`__
+
+**Pre-processing:** `Source code for preparation of the original dataset for
+redistribution in Ensaio
+<https://github.com/fatiando-data/morroco-speleothem-qdm>`__
+
+"""
+import matplotlib.pyplot as plt
+import xarray as xr
+
+import ensaio
+
+###############################################################################
+# Download and cache the data and return the path to it on disk. We'll use the
+# netCDF version because it's smaller and can be loaded with xarray easily.
+fname = ensaio.fetch_morroco_speleothem_qdm(version=1, format="netcdf")
+print(fname)
+
+###############################################################################
+# Load the netCDF grid with xarray
+data = xr.load_dataarray(fname)
+data
+
+###############################################################################
+# Make a pseudo-color map of the magnetic microscopy data and adjust the scale
+# because of some very strong sources.
+fig, ax = plt.subplots(1, 1, figsize=(9, 4.8), layout="constrained")
+scale = 2500
+data.plot.imshow(ax=ax, cmap="RdBu_r", vmin=-scale, vmax=scale)
+ax.set_aspect("equal")
+plt.show()
diff --git a/ensaio/_fetchers.py b/ensaio/_fetchers.py
index 72c9817b..280e7f36 100644
--- a/ensaio/_fetchers.py
+++ b/ensaio/_fetchers.py
@@ -709,7 +709,7 @@ def fetch_morroco_speleothem_qdm(version, format):
 
     **Load with:** :func:`xarray.load_dataarray` (for netCDF; requires the `netcdf4
     <https://github.com/Unidata/netcdf4-python>`__ library) or
-    :func:`magali.read_harvard_qdm` (for Matlab format)
+    :func:`magali.read_qdm_harvard` (for Matlab format)
 
     **Original source:** Carmo, Janine; Fu, Roger; Trindade, Ricardo; Piascik,
     Samuel (2023). QDM magnetic microscopy dataset of a speleothem from