Add Binder badge/button to readme (#1628)

* Adds Binder badge/button to the readme file.
* Adds a separate "call to action" paragraph to highlight Binder rather than putting it among other badges.
* Uses JupyterLab.
* Adds content to the basic example, so it is clear how to start using the standard grass.script API.

README.md

@@ -15,6 +15,11 @@ a Geographic Information System used for geospatial data management and
 analysis, image processing, graphics/map production, spatial modeling, and
 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/master?urlpath=lab%2Ftree%2Fdoc%2Fnotebooks%2Fexample_notebook.ipynb)
+
+
 ## How to get write access here
 
 In general: you don't really need write access as you can simply open

doc/notebooks/example_notebook.ipynb

@@ -18,11 +18,114 @@
  "nbformat_minor": 2,
  "cells": [
   {
+   "source": [
+    "# Try GRASS GIS in Jupyter Notebook with Python\n",
+    "\n",
+    "[<img src=\"../../man/grass_logo.png\" alt=\"GRASS GIS\" style=\"width:200px;\"/>](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",
+    "\n",
+    "Examples here are using a sample GRASS GIS dataset for North Carolina, USA. The dataset is included in this environment.\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."
+   ],
+   "cell_type": "markdown",
+   "metadata": {}
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Import Python standard library and IPython packages we need.\n",
+    "import os\n",
+    "import sys\n",
+    "import subprocess\n",
+    "from IPython.display import Image\n",
+    "\n",
+    "# Ask GRASS GIS where its Python packages are.\n",
+    "gisbase = subprocess.check_output([\"grass\", \"--config\", \"path\"], text=True).strip()\n",
+    "os.environ['GISBASE'] = gisbase\n",
+    "sys.path.append(os.path.join(gisbase, \"etc\", \"python\"))\n",
+    "\n",
+    "# Import the GRASS GIS packages we need.\n",
+    "import grass.script as gs\n",
+    "import grass.script.setup as gsetup\n",
+    "\n",
+    "# Create a GRASS GIS session.\n",
+    "rcfile = gsetup.init(gisbase, \"../../data/grassdata\", \"nc_basic_spm_grass7\", \"user1\")\n",
+    "\n",
+    "# We want functions to raise exceptions and see standard output of the modules in the notebook.\n",
+    "gs.set_raise_on_error(True)\n",
+    "gs.set_capture_stderr(True)\n",
+    "# Simply overwrite existing maps like we overwrite Python variable values.\n",
+    "os.environ['GRASS_OVERWRITE'] = '1'\n",
+    "# Enable map rendering in a notebook.\n",
+    "os.environ['GRASS_FONT'] = 'sans'\n",
+    "# Set display modules to render into a file (named map.png by default)\n",
+    "os.environ['GRASS_RENDER_IMMEDIATE'] = 'cairo'\n",
+    "os.environ['GRASS_RENDER_FILE_READ'] = 'TRUE'\n",
+    "os.environ['GRASS_LEGEND_FILE'] = 'legend.txt'"
+   ]
+  },
+  {
+   "source": [
+    "## Raster buffer\n",
+    "\n",
+    "Set computational region and create multiple buffers in given distances\n",
+    "around lakes represented as raster:"
+   ],
+   "cell_type": "markdown",
+   "metadata": {}
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "gs.parse_command('g.region', raster=\"lakes\", flags='pg')\n",
+    "gs.run_command('r.buffer', input=\"lakes\", output=\"lakes_buff\", distances=[60, 120, 240, 500])\n",
+    "gs.run_command('d.erase')\n",
+    "gs.run_command('d.rast', map=\"lakes_buff\")\n",
+    "gs.run_command('d.legend', raster=\"lakes_buff\", range=(2, 5), at=(80, 100, 2, 10))\n",
+    "Image(filename=\"map.png\")"
+   ]
+  },
+  {
+   "source": [
+    "## Vector buffer\n",
+    "\n",
+    "Create a negative buffer around state boundary represented as a vector.\n",
+    "Vector modules typically don't follow computational region,\n",
+    "but we set it to inform display modules about our area of interest."
+   ],
+   "cell_type": "markdown",
+   "metadata": {}
+  },
+  {
    "cell_type": "code",
    "execution_count": null,
    "metadata": {},
    "outputs": [],
-   "source": []
+   "source": [
+    "gs.run_command('v.buffer', input=\"boundary_state\", output=\"buffer\", distance=-10000)\n",
+    "gs.parse_command('g.region', vector=\"boundary_state\", flags='pg')\n",
+    "gs.run_command('d.erase')  # erase the display before drawing again\n",
+    "!rm -f $GRASS_LEGEND_FILE  # and remove the legend file\n",
+    "gs.run_command('d.vect', map=\"boundary_state\", fill_color=\"#5A91ED\", legend_label=\"State boundary\")\n",
+    "gs.run_command('d.vect', map=\"buffer\", fill_color=\"#F8766D\", legend_label=\"Inner portion\")\n",
+    "gs.run_command('d.legend.vect', at=(10, 35))\n",
+    "Image(filename=\"map.png\")"
+   ]
   }
  ]
-}
+}