jupyter: Improve docstrings (#1800)

* Note this is currently experimental (for 8.0).
* Various improvements to the docstrings in grass.jupyter
* Format parameters, **kwargs, notes using Sphinx syntax.

python/grass/jupyter/__init__.py

@@ -1,3 +1,26 @@
+# MODULE:    grass.jupyter
+#
+# AUTHOR(S): Caitlin Haedrich <caitlin DOT haedrich AT gmail>
+#
+# PURPOSE:   Display classes and setup functions for running GRASS GIS
+#            in Jupyter Notebooks
+#
+# COPYRIGHT: (C) 2021 Caitlin Haedrich, and by the GRASS Development Team
+#
+#            This program is free software under the GNU General Public
+#            License (>=v2). Read the file COPYING that comes with GRASS
+#            for details.
+
+"""Display classes and setup functions for running GRASS GIS in Jupyter Notebooks
+
+This subpackage of the grass package is experimental and under development. The API
+can change at anytime.
+
+The grass.jupyter subpackage improves the integration of GRASS GIS and Jupyter
+Notebooks. The original version was written as part of Google Summer of Code in 2021.
+For more information, visit https://trac.osgeo.org/grass/wiki/GSoC/2021/JupyterAndGRASS
+"""
+
 from .setup import *
 from .interact_display import *
 from .display import *

python/grass/jupyter/display.py

@@ -91,7 +91,14 @@ class GrassRenderer:
         self._env["GRASS_LEGEND_FILE"] = str(self._legend_file)
 
     def run(self, module, **kwargs):
-        """Run modules from "d." GRASS library"""
+        """Run modules from the GRASS display family (modules starting with "d.").
+
+         This function passes arguments directly to grass.script.run_command()
+         so the syntax is the same.
+
+        :param str module: name of GRASS module
+        :param `**kwargs`: named arguments passed to run_command()"""
+
         # Check module is from display library then run
         if module[0] == "d":
             gs.run_command(module, env=self._env, **kwargs)
@@ -119,7 +126,7 @@ class GrassRenderer:
         return wrapper
 
     def show(self):
-        """Displays a PNG image of the map"""
+        """Displays a PNG image of map"""
         from IPython.display import Image
 
         return Image(self._filename)

python/grass/jupyter/interact_display.py

@@ -139,7 +139,15 @@ class InteractiveMap:
 
     def add_raster(self, name, opacity=0.8):
         """Imports raster into temporary WGS84 location,
-        exports as png and overlays on folium map
+        exports as png and overlays on folium map.
+
+        Color table for the raster can be modified with `r.colors` before calling
+        this function.
+
+        .. note:: This will only work if the raster is located in the current mapset.
+        To change the color table of a raster located outside the current mapset,
+        switch to that mapset with `g.mapset`, modify the color table with `r.color`
+        then switch back to the initial mapset and run this function.
 
         :param str name: name of raster to add to display; positional-only parameter
         :param float opacity: raster opacity, number between
@@ -209,7 +217,10 @@ class InteractiveMap:
         img.add_to(self.map)
 
     def add_layer_control(self, **kwargs):
-        """Add layer control to display"""
+        """Add layer control to display"
+
+        :param `**kwargs`: named arguments to be passed to folium.LayerControl()"""
+
         self.layer_control = True
         self.layer_control_object = self._folium.LayerControl(**kwargs)
 

python/grass/jupyter/setup.py

@@ -38,10 +38,9 @@ def init(path, location, mapset):
     This function initiates a GRASS session and sets GRASS
     environment variables.
 
-    Inputs:
-        path - path to grass databases
-        location - name of GRASS location
-        mapset - name of mapset within location
+    :param str path: path to grass databases
+    :param str location: name of GRASS location
+    :param str mapset: name of mapset within location
     """
     # Create a GRASS GIS session.
     gsetup.init(os.environ["GISBASE"], path, location, mapset)