grass.jupyter: Center notebooks around the package (#2408)

Previously, the primary notebook was the one without grass.jupyter. Now the shorter grass.jupyter is the primary one and the original notebook is for scripting use cases only. The notebooks are still similar, so one can compare the differences, but there is no need to keep this for future versions as the aim of having the comparison is valid only for introduction of grass.jupyter, i.e., for 8.0 and 8.2. The text now reflects that grass.jupyter is officially released. Some additional info is included, e.g., about the mini grant which will become less relevant in the next versions and may be removed or significantly revised. Other files, such as readme, now point to the notebook which is using grass.jupyter.
OSGeo · May 31, 2022 · 19a846c · 19a846c
1 parent c735686
commit 19a846c
Show file tree

Hide file tree

Showing 6 changed files with 20 additions and 21 deletions.
diff --git a/README.md b/README.md
@@ -18,7 +18,7 @@ visualization.
 
 Launch this repository in Binder and experiment with GRASS's Python API in Jupyter Notebooks by clicking the button below:
 
-[![Binder](https://camo.githubusercontent.com/581c077bdbc6ca6899c86d0acc6145ae85e9d80e6f805a1071793dbe48917982/68747470733a2f2f6d7962696e6465722e6f72672f62616467655f6c6f676f2e737667)](https://mybinder.org/v2/gh/OSGeo/grass/main?urlpath=lab%2Ftree%2Fdoc%2Fnotebooks%2Fbasic_example.ipynb)
+[![Binder](https://camo.githubusercontent.com/581c077bdbc6ca6899c86d0acc6145ae85e9d80e6f805a1071793dbe48917982/68747470733a2f2f6d7962696e6465722e6f72672f62616467655f6c6f676f2e737667)](https://mybinder.org/v2/gh/OSGeo/grass/main?urlpath=lab%2Ftree%2Fdoc%2Fnotebooks%2Fjupyter_example.ipynb)
 
 
 ## How to get write access here

diff --git a/...tebooks/basic_example_grass_jupyter.ipynb → doc/notebooks/jupyter_example.ipynb b/...tebooks/basic_example_grass_jupyter.ipynb → doc/notebooks/jupyter_example.ipynb
@@ -4,25 +4,23 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "# Try GRASS GIS in Jupyter Notebook with Python and grass.jupyter\n",
+    "# GRASS GIS in Jupyter Notebook with Python and grass.jupyter\n",
     "\n",
     "[<img src=\"../../gui/images/splash_screen.png\" alt=\"GRASS GIS\" style=\"height: 20ex;\"/>](https://grass.osgeo.org/)\n",
     "\n",
-    "This is a quick introduction to *GRASS GIS* in a *Jupyter Notebook* using the `grass.jupyter` package and the *Python* scripting language. The `grass.jupyter` package shortens the launch of *GRASS GIS* in *Jupyter Notebook* and provides several useful classes for creating, displaying and saving *GRASS GIS* maps. This notebook can be directly compared with [basic_example.ipynb](basic_example.ipynb) to see how the package improves the integration of *GRASS GIS* and *Jupyter Notebooks*.\n",
+    "This is a quick introduction to *GRASS GIS* in a *Jupyter Notebook* using the [_grass.jupyter_](https://grass.osgeo.org/grass82/manuals/libpython/grass.jupyter.html) package and the *Python* scripting language. The _grass.jupyter_ package simplifies the launch of *GRASS GIS* in *Jupyter Notebook* and provides several useful classes for creating, displaying, and saving *GRASS GIS* maps.\n",
     "\n",
+    "The _grass.jupyter_ package was initially written as part of Google Summer of Code in 2021 by Caitlin Haedrich and was experimentally included in version 8.0.0. Caitlin further improved it thanks to the GRASS Mini Grant 2022. The package was officially released for the first time as part of version 8.2.0. If you are curious about how the package improves the integration of *GRASS GIS* and *Jupyter Notebooks*, compare it with [scripting_example.ipynb](scripting_example.ipynb). More features of the _grass.jupyter_ package are presented in [jupyter_tutorial.ipynb](jupyter_tutorial.ipynb).\n",
     "\n",
-    "The `grass.jupyter` package was written as part of Google Summer of Code in 2021 and is experimentally included in version 8.0. For more information, visit the [wiki page](https://trac.osgeo.org/grass/wiki/GSoC/2021/JupyterAndGRASS).\n",
-    "\n",
-    "\n",
-    "Examples here are using a sample GRASS GIS dataset for North Carolina, USA. The dataset is included in this environment.\n",
+    "Examples here are using a sample GRASS GIS dataset for North Carolina, USA. The interactive notebook is available online thanks to the [*Binder*](https://mybinder.org/) service. If you are using the notebook in this environment, the dataset is already included.\n",
     "\n",
     "## Usage\n",
     "\n",
     "To run the selected part which is called a cell, hit `Shift + Enter`.\n",
     "\n",
     "## Start\n",
     "\n",
-    "There are several ways to use GRASS GIS. When using Python in a notebook, we usually find GRASS GIS Python packages first, import them, initialize GRASS GIS session, and set several variables useful for using GRASS GIS in a notebook."
+    "When using _GRASS GIS_ through Python in a notebook, we usually find GRASS GIS Python packages first, import them, and then initialize GRASS GIS session:"
    ]
   },
   {
@@ -46,7 +44,7 @@
     "import grass.jupyter as gj\n",
     "\n",
     "# Start GRASS Session\n",
-    "session = gj.init(\"../../data/grassdata\", \"nc_basic_spm_grass7\", \"user1\")"
+    "session = gj.init(\"~/data/grassdata/nc_basic_spm_grass7/user1\")"
    ]
   },
   {

diff --git a/doc/notebooks/grass_jupyter.ipynb → doc/notebooks/jupyter_tutorial.ipynb b/doc/notebooks/grass_jupyter.ipynb → doc/notebooks/jupyter_tutorial.ipynb
@@ -4,13 +4,15 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "# Improved Integration of GRASS and Jupyter\n",
+    "# The grass.jupyter Package\n",
     "\n",
-    "As part of Google Summer of Code 2021, we've been working to shorten and simplify the launch of GRASS in Jupyter and imporve the map displays. It is experimentally included in version 8.0 as a preview and will be officially available in version 8.2. You can find out more about the project and follow the progress on the [GRASS wiki page](https://trac.osgeo.org/grass/wiki/GSoC/2021/JupyterAndGRASS).\n",
+    "This notebook introduces the [_grass.jupyter_](https://grass.osgeo.org/grass82/manuals/libpython/grass.jupyter.html) package which simplifies the usage of *GRASS GIS* in *Jupyter Notebook*.\n",
     "\n",
-    "In addition to simplifying the launch of *GRASS GIS* with `init()`, `grass.jupyter` has two main dislay classes, `Map` and `InteractiveMap`. Using the *GRASS* rendering engine in the background, `Map` creates maps as PNG images. `InteractiveMap` displays *GRASS GIS* rasters and vectors with [*folium*](http://python-visualization.github.io/folium/), a [*leaflet*](https://leafletjs.com/) library for *Python*.\n",
+    "The _grass.jupyter_ package was initially written as part of [Google Summer of Code in 2021](https://trac.osgeo.org/grass/wiki/GSoC/2021/JupyterAndGRASS) by Caitlin Haedrich and was experimentally included in version 8.0.0. Caitlin further improved it thanks to the [GRASS Mini Grant 2022](https://trac.osgeo.org/grass/wiki/GSoC/2021/JupyterAndGRASS/MiniGrant2022). The package was officially released for the first time as part of version 8.2.0. Credits for mentoring and additional development go to Vaclav Petras, Helena Mitasova, Stefan Blumentrath, and Anna Petrasova as well as to many members of the GRASS community who provided important feedback.\n",
     "\n",
-    "This interactive notebook is available online thanks to the [https://mybinder.org](Binder) service. To run the select part (called a *cell*), hit `Shift + Enter`."
+    "In addition to simplifying the launch of *GRASS GIS* with a dedicated _init_ function, _grass.jupyter_ has two main display classes, _Map_ and _InteractiveMap_. Using the GRASS rendering engine in the background, _Map_ creates maps as PNG images. _InteractiveMap_ displays GRASS rasters and vectors with [*folium*](http://python-visualization.github.io/folium/), a [*leaflet*](https://leafletjs.com/) library for Python. The package includes also _Map3D_ and [_TimeSeriesMap_](temporal.ipynb).\n",
+    "\n",
+    "This interactive notebook is available online thanks to the [Binder](https://mybinder.org) service. To run the select part (called a *cell*), hit `Shift + Enter`."
    ]
   },
   {
@@ -40,7 +42,7 @@
     "import grass.jupyter as gj\n",
     "\n",
     "# Start GRASS Session\n",
-    "session = gj.init(\"../../data/grassdata\", \"nc_basic_spm_grass7\", \"user1\")\n",
+    "session = gj.init(\"~/data/grassdata\", \"nc_basic_spm_grass7\", \"user1\")\n",
     "\n",
     "# Set computational region to the elevation raster.\n",
     "gs.run_command(\"g.region\", raster=\"elevation\")"

diff --git a/doc/notebooks/basic_example.ipynb → doc/notebooks/scripting_example.ipynb b/doc/notebooks/basic_example.ipynb → doc/notebooks/scripting_example.ipynb
@@ -4,14 +4,13 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "# Try GRASS GIS in Jupyter Notebook with Python\n",
+    "# GRASS GIS Scripting with Python\n",
     "\n",
     "[<img src=\"../../gui/images/splash_screen.png\" alt=\"GRASS GIS\" style=\"height: 20ex;\"/>](https://grass.osgeo.org/)\n",
     "\n",
-    "This is a quick introduction to *GRASS GIS* in a *Jupyter Notebook* using the *Python* scripting language.\n",
-    "The interactive notebook is available online thanks to the [*Binder*](https://mybinder.org/) service.\n",
+    "This is an introduction to using *GRASS GIS* in the *Python* scripting language. This document is a *Jupyter Notebook*, but unlike the [jupyter_example.ipynb](jupyter_example.ipynb) notebook, the examples in this notebook are meant to be used primarily outside of a notebook.\n",
     "\n",
-    "Examples here are using a sample GRASS GIS dataset for North Carolina, USA. The dataset is included in this environment.\n",
+    "Examples here are using a sample GRASS GIS dataset for North Carolina, USA. The dataset is included in this environment. The interactive notebook is available online thanks to the [*Binder*](https://mybinder.org/) service.\n",
     "\n",
     "## Usage\n",
     "\n",

diff --git a/python/grass/jupyter/__init__.py b/python/grass/jupyter/__init__.py
@@ -64,7 +64,7 @@
 
 .. image:: https://mybinder.org/badge_logo.svg
     :target:
-        https://mybinder.org/v2/gh/OSGeo/grass/main?urlpath=lab%2Ftree%2Fdoc%2Fnotebooks%2Fbasic_example.ipynb
+        https://mybinder.org/v2/gh/OSGeo/grass/main?urlpath=lab%2Ftree%2Fdoc%2Fnotebooks%2Fjupyter_example.ipynb
 
 There are also internal classes and functions which are not guaranteed to have
 as stable API, although they are available through their specific submodules.
@@ -95,7 +95,7 @@
 
 .. _Jupyter: https://jupyter.org/
 .. _wiki: https://grasswiki.osgeo.org/wiki/GRASS_GIS_Jupyter_notebooks
-.. _GitHub: https://github.com/OSGeo/grass/blob/main/doc/notebooks/basic_example.ipynb
+.. _GitHub: https://github.com/OSGeo/grass/blob/main/doc/notebooks/jupyter_example.ipynb
 """
 
 from .interactivemap import InteractiveMap, Raster, Vector

diff --git a/utils/generate_release_notes.py b/utils/generate_release_notes.py
@@ -87,7 +87,7 @@ def print_by_category(changes, categories, file=None):
 def binder_badge(tag):
     """Get mybinder Binder badge from a given tag, hash, or branch"""
     binder_image_url = "https://camo.githubusercontent.com/581c077bdbc6ca6899c86d0acc6145ae85e9d80e6f805a1071793dbe48917982/68747470733a2f2f6d7962696e6465722e6f72672f62616467655f6c6f676f2e737667"  # noqa
-    binder_url = f"https://mybinder.org/v2/gh/OSGeo/grass/{tag}?urlpath=lab%2Ftree%2Fdoc%2Fnotebooks%2Fbasic_example.ipynb"  # noqa
+    binder_url = f"https://mybinder.org/v2/gh/OSGeo/grass/{tag}?urlpath=lab%2Ftree%2Fdoc%2Fnotebooks%2Fjupyter_example.ipynb"  # noqa
     return f"[![Binder]({binder_image_url})]({binder_url})"