Start use of sphinx-gallery : minigallery in docstring

Author: AntSimi

.gitignore

@@ -70,6 +70,7 @@ instance/
 
 # Sphinx documentation
 docs/_build/
+doc/gen_modules/
 
 # PyBuilder
 target/

doc/conf.py

@@ -46,6 +46,8 @@
     "examples_dirs": "../examples",  # path to your example scripts
     "gallery_dirs": "python_module",
     "capture_repr": ("_repr_html_",),
+    "backreferences_dir": "gen_modules/backreferences",
+    "doc_module": ("py_eddy_tracker",),
     "line_numbers": False,
     "filename_pattern": "/pet",
     "binder": {

examples/08_tracking_manipulation/pet_display_track.py

@@ -9,15 +9,20 @@
 import py_eddy_tracker_sample
 
 # %%
-# Load experimental atlas, and keep only eddies longer than 20 weeks
+# Load experimental atlas
 a = TrackEddiesObservations.load_file(
     py_eddy_tracker_sample.get_path("eddies_med_adt_allsat_dt2018/Anticyclonic.zarr")
 )
 c = TrackEddiesObservations.load_file(
     py_eddy_tracker_sample.get_path("eddies_med_adt_allsat_dt2018/Cyclonic.zarr")
 )
+print(a)
+
+# %%
+# keep only eddies longer than 20 weeks, use -1 to have no upper limit
 a = a.extract_with_length((7 * 20, -1))
 c = c.extract_with_length((7 * 20, -1))
+print(a)
 
 # %%
 # Position filtering for nice display

notebooks/python_module/08_tracking_manipulation/pet_display_track.ipynb

@@ -15,7 +15,7 @@
       "cell_type": "markdown",
       "metadata": {},
       "source": [
-        "\nDisplay Tracks\n======================\n"
+        "\n# Display Tracks\n"
       ]
     },
     {
@@ -33,7 +33,7 @@
       "cell_type": "markdown",
       "metadata": {},
       "source": [
-        "Load experimental atlas, and keep only eddies longer than 20 weeks\n\n"
+        "Load experimental atlas\n\n"
       ]
     },
     {
@@ -44,7 +44,25 @@
       },
       "outputs": [],
       "source": [
-        "a = TrackEddiesObservations.load_file(\n    py_eddy_tracker_sample.get_path(\"eddies_med_adt_allsat_dt2018/Anticyclonic.zarr\")\n)\nc = TrackEddiesObservations.load_file(\n    py_eddy_tracker_sample.get_path(\"eddies_med_adt_allsat_dt2018/Cyclonic.zarr\")\n)\na = a.extract_with_length((7 * 20, -1))\nc = c.extract_with_length((7 * 20, -1))"
+        "a = TrackEddiesObservations.load_file(\n    py_eddy_tracker_sample.get_path(\"eddies_med_adt_allsat_dt2018/Anticyclonic.zarr\")\n)\nc = TrackEddiesObservations.load_file(\n    py_eddy_tracker_sample.get_path(\"eddies_med_adt_allsat_dt2018/Cyclonic.zarr\")\n)\nprint(a)"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "keep only eddies longer than 20 weeks\n\n"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "collapsed": false
+      },
+      "outputs": [],
+      "source": [
+        "a = a.extract_with_length((7 * 20, -1))\nc = c.extract_with_length((7 * 20, -1))\nprint(a)"
       ]
     },
     {

src/py_eddy_tracker/observations/tracking.py

@@ -233,7 +233,11 @@ def extract_with_area(self, area, **kwargs):
         Extract with a bounding box
 
         :param dict area: 4 coordinates in a dictionary to specify bounding box (lower left corner and upper right corner)
+        :param dict kwargs: look at :py:meth:`__extract_with_mask`
+        :return: Return all eddy tracks which are in bounds
+        :rtype: TrackEddiesObservations
 
+        .. minigallery:: py_eddy_tracker.observations.tracking.TrackEddiesObservations.extract_with_area
         """
         mask = (self.latitude > area["llcrnrlat"]) * (self.latitude < area["urcrnrlat"])
         lon0 = area["llcrnrlon"]
@@ -246,8 +250,11 @@ def extract_with_period(self, period, **kwargs):
         Extract with a period
 
         :param (datetime.datetime,datetime.datetime) period: two date to define period, must be specify from 1/1/1950
+        :param dict kwargs: look at :py:meth:`__extract_with_mask`
+        :return: Return all eddy tracks which are in bounds
+        :rtype: TrackEddiesObservations
 
-        :return: same object with selected data
+        .. minigallery:: py_eddy_tracker.observations.tracking.TrackEddiesObservations.extract_with_period
         """
         dataset_period = self.period
         p_min, p_max = period
@@ -324,6 +331,13 @@ def extract_in_direction(self, direction, value=0):
         return self.__extract_with_mask(mask)
 
     def extract_with_length(self, bounds):
+        """
+        :param (int,int) bounds: length min and max of selected eddies, if use of -1 this bound is not used
+        :return: Return all eddy tracks which have length between bounds
+        :rtype: TrackEddiesObservations
+
+        .. minigallery:: py_eddy_tracker.observations.tracking.TrackEddiesObservations.extract_with_length
+        """
         b0, b1 = bounds
         if b0 >= 0 and b1 >= 0:
             track_mask = (self.nb_obs_by_track >= b0) * (self.nb_obs_by_track <= b1)