Rework example gallery (#58)

* Add test reference to readme

* Add custom thumbnail support

* Rework example notebooks

* Add  name arg to gen_random

Author: Teschl

README.md

@@ -97,6 +97,10 @@ For any operating system, install the following:
 
 [work in progress]
 
+## Testing
+
+To find out how to run the tests of the pytopotoolbox, refer to the dedicated [readme](./test/README.md) in the /tests directory.
+
 ## Contributing
 
 If you would like to contribute to pytopotoolbox, check out the [Contribution Guidelines](./CONTRIBUTING.md).

docs/_static/thumbnails/placeholder.png

@@ -1,11 +1,3 @@
-# Configuration file for the Sphinx documentation builder.
-#
-# For the full list of built-in configuration values, see the documentation:
-# https://www.sphinx-doc.org/en/master/usage/configuration.html
-
-# -- Project information -----------------------------------------------------
-# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
-
 import os
 import sys
 
@@ -21,7 +13,6 @@
     'sphinx.ext.viewcode',
     'sphinx.ext.todo',
     'nbsphinx',
-    'myst_parser',
 ]
 
 project = 'TopoToolbox'
@@ -30,14 +21,11 @@
 release = '3.0.1'
 
 # -- General configuration ---------------------------------------------------
-# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
 
 templates_path = ['_templates']
 exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', 'README.md']
 
-
 # -- Options for HTML output -------------------------------------------------
-# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 
 html_theme = 'sphinx_book_theme'
 html_static_path = ['_static']
@@ -57,9 +45,17 @@
     'members': True,
     'undoc-members': True,
     'private-members': False,
-    'special-members': '__init__',
     'inherited-members': True,
     'show-inheritance': True,
 }
 
 autosummary_generate = True  # Enable autosummary to generate stub files
+
+# -- Options for nbgallery ---------------------------------------------------
+
+nbsphinx_thumbnails = {
+    '_temp/excesstopography': '_static/thumbnails/placeholder.png',
+    '_temp/magicfunctions': '_static/thumbnails/placeholder.png',
+    '_temp/plotting': '_static/thumbnails/placeholder.png',
+    '_temp/downloading': '_static/thumbnails/placeholder.png',
+}

docs/conf.py

@@ -2,9 +2,7 @@ Examples
 ========
 
 .. nbgallery::
-   /_temp/excesstopography.ipynb
-   /_temp/plotting.ipynb
-   /_temp/test_genGrid
-   /_temp/test_GridObject
-   /_temp/test_load_dem
-   /_temp/example_magic_funcs
+   /_temp/excesstopography
+   /_temp/magicfunctions
+   /_temp/plotting
+   /_temp/downloading

docs/examples.rst

@@ -1,5 +1,4 @@
 Sphinx==7.3.7
 sphinx-book-theme==1.1.2
 nbsphinx==0.9.4
-notebook==7.0.5
-myst_parser
+notebook==7.0.5

docs/requirements.txt

@@ -0,0 +1,75 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Loading an example GridObject\n",
+    "=============================\n",
+    "\n",
+    "The TopoToolbox provides a few example .tif files. These Files will get saved in a local cache. To delete these Files, run `topotoolbox.clear_cache()`."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 2,
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "['kedarnath', 'kunashiri', 'perfectworld', 'taalvolcano', 'taiwan', 'tibet']\n",
+      "\n",
+      "name: taiwan\n",
+      "path: /home/theo/.cache/topotoolbox/taiwan.tif\n",
+      "rows: 4181\n",
+      "cols: 2253\n",
+      "cellsize: 90.0\n",
+      "bounds: BoundingBox(left=197038.4533204764, bottom=2422805.9007333447, right=399808.4533204764, top=2799095.9007333447)\n",
+      "transform: | 90.00, 0.00, 197038.45|\n",
+      "| 0.00,-90.00, 2799095.90|\n",
+      "| 0.00, 0.00, 1.00|\n",
+      "crs: EPSG:32651\n",
+      "\n",
+      "['kunashiri.tif', 'perfectworld.tif', 'tibet.tif', 'taiwan.tif', 'kedarnath.tif']\n"
+     ]
+    }
+   ],
+   "source": [
+    "import topotoolbox as topo\n",
+    "\n",
+    "# Print all available example files\n",
+    "print(f\"{topo.get_dem_names()}\\n\")\n",
+    "\n",
+    "# Download an example file\n",
+    "dem = topo.load_dem(\"taiwan\")\n",
+    "dem.info()\n",
+    "\n",
+    "# Print all files currently saved in your cache\n",
+    "print(f\"\\n{topo.get_cache_contents()}\")"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3 (ipykernel)",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.10.12"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 2
+}

examples/downloading.ipynb

@@ -51,7 +51,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "If some sections of the GridObject should be differently than others, use another GridObject or np.ndarray to add custom value for the threshold slopes. Make sure that the shape of your threshold matches the one of your GridObject."
+    "If some sections of the GridObject should be evaluated differently than others, use another GridObject or np.ndarray to add custom value for the threshold slopes. Make sure that the shape of your threshold matches the one of your GridObject."
    ]
   },
   {