grass.jupyter: Generate API doc for Jupyter package (OSGeo#2284)

- Updates documentation intro to reflect that it will be officially included in v8.2.
- Adds grass.jupyter to the libpython index TOC.
- Reduces depth of the TOC to make it more clear.
- Updates copyright year for generated files.
- Generates API doc for all grass.jupyter.
- Adds Sphix documentation build to Pylint check.
- Adds all authors to init file.

The Pylint check builds the code which Sphinx needs and there is already the pytest-based Pylint check so it could potentially do some pytest-related Sphinx tasks.

The API doc is now generated for all parts of the grass package. This make it possible for the doc to say grass.jupyter rather than just jupyter. This duplicates the generated doc for grass.script and others, but in the future this should replace the per-subpackage generated doc.

.github/workflows/pylint.yml

@@ -85,3 +85,17 @@ jobs:
           export PYTHONPATH=`grass --config python_path`:$PYTHONPATH
           export LD_LIBRARY_PATH=$HOME/install/grass81/lib:$LD_LIBRARY_PATH
           pytest --pylint -m pylint --pylint-rcfile=.pylintrc --pylint-jobs=$(nproc) --pylint-ignore-patterns="python/.*,gui/wxpython/.*,doc/.*,man/.*,utils/.*,locale/.*,raster/.*,imagery/.*,scripts/r.in.wms/wms_drv.py,scripts/g.extension/g.extension.py,temporal/t.rast.accdetect/t.rast.accdetect.py,temporal/t.rast.accumulate/t.rast.accumulate.py,scripts/d.rast.edit/d.rast.edit.py"
+
+      - name: Run Sphinx to check API documentation build
+        run: |
+          pip install sphinx
+          make sphinxdoclib
+          ARCH=$(cat include/Make/Platform.make | grep ^ARCH | cut -d'=' -f2 | xargs)
+          cp -rp dist.$ARCH/docs/html/libpython sphinx-grass
+
+      - name: Make Sphinx documentation available
+        uses: actions/upload-artifact@v3
+        with:
+          name: sphinx-grass
+          path: sphinx-grass
+          retention-days: 3

python/grass/docs/Makefile

@@ -56,6 +56,7 @@ libpythonclean:
 	-rm -f src/pygrass.*rst
 	-rm -f src/script.rst
 	-rm -f src/temporal.rst
+	-rm -f src/grass*.rst
 
 libpythonapidoc:
 	@echo "SPHINXBUILD: Using <$(SPHINXBUILD)>"
@@ -66,6 +67,7 @@ libpythonapidoc:
 	$(call run_grass,$(SPHINXAPIDOC) -T -f -o src/ ../pygrass/)
 	$(call run_grass,$(SPHINXAPIDOC) -T -f -o src/ ../script/)
 	$(call run_grass,$(SPHINXAPIDOC) -T -f -o src/ ../temporal/)
+	$(call run_grass,$(SPHINXAPIDOC) --module-first -T -f -o src/ ../../grass)
 
 libpythonhtml: checksphinx
 	@echo "SPHINXBUILD: Using <$(SPHINXBUILD)>"

python/grass/docs/conf.py

@@ -124,7 +124,7 @@
 
 # General information about the project.
 project = "Python library documentation"
-copyright = "2014, GRASS Development Team"
+copyright = "2022, GRASS Development Team"
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
@@ -359,7 +359,7 @@
 epub_title = "PythonLib"
 epub_author = "GRASS Development Team"
 epub_publisher = "GRASS Development Team"
-epub_copyright = "2014, GRASS Development Team"
+epub_copyright = "2022, GRASS Development Team"
 
 # The basename for the epub file. It defaults to the project name.
 # epub_basename = u'wxGUI'

python/grass/docs/src/index.rst

@@ -27,11 +27,12 @@ at various levels:
 Contents:
 
 .. toctree::
-   :maxdepth: 3
+   :maxdepth: 2
 
    script_intro
    pygrass_index
    temporal_framework
+   grass.jupyter
    exceptions
    imaging
    gunittest_testing

python/grass/jupyter/__init__.py

@@ -1,24 +1,44 @@
 # MODULE:    grass.jupyter
 #
 # AUTHOR(S): Caitlin Haedrich <caitlin DOT haedrich AT gmail>
+#            Vaclav Petras <wenzeslaus gmail com>
+#            Anna Petrasova <kratochanna gmail com>
 #
 # PURPOSE:   Display classes and setup functions for running GRASS GIS
 #            in Jupyter Notebooks
 #
-# COPYRIGHT: (C) 2021 Caitlin Haedrich, and by the GRASS Development Team
+# COPYRIGHT: (C) 2021-2022 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
+and experimental version was included in GRASS GIS 8.0. Since then, much more
+development happened adding better session handling and rendering of additional data
+types.
 
-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
+For standard usage, simply import the top level package with a convenient alias, e.g.,::
+
+>>> import grass.jupyter as gj
+
+The objects in submodules and names of submodules may change in the future.
+
+.. note::
+    To import the package, you need to tell Python where the GRASS GIS Python package
+    is. Please, refer to example notebooks for an example of the full workflow.
+
+.. note::
+    Although most of the functionality is general, the defaults, resource management,
+    and other behavior assumes usage in an interactive notebook, so using the
+    functionality in other contexts (e.g. a script) may result in unexpected behavior.
+    Consult the documentation or mailing list if in doubt. Suggest generalized
+    functionality using issues and pull requests.
+
+.. versionadded:: 8.2
 """
 
 from .display import *