New Jupyter Notebooks Section: MPAS Plot with Datashader and Geoviews (…

…#425)

* conda_environment modified

* conf.py modified to use nbsphinx

* index.rst modified to include Notebook gallery

* Added the first notebook example - MPAS datashader

* Added NSF logo

* Add dynamic resizing for docs pages and fix pre-commit

* precommit fix

* precommit fix

* Rephrased the comment under Load data cell

* Rendered the Jupyter notebook to make it publication ready

* precommit fix

* A few typo and comment correction

* A few modifications to docstrings

* Added notebook download links as nbsphinx prolog config

* precommit fix

* Renamed /Plots to /Gallery and updated INSTALLATION .md and rst files to reflect Notebook gallery

.gitignore

@@ -1,7 +1,7 @@
 /docs/_build/
 /docs/gallery/
 /docs/gallery-geocat-comp/
-/Plots/CSV/*.csv
+/Gallery/CSV/*.csv
 *.ncl
 .vscode/
 .idea/

CONTRIBUTING.md

@@ -9,7 +9,7 @@ following contribution guidelines:
 1. Please check the followings to ensure that the example you are about to work on has not been ported yet:
 
     - [GeoCAT-Examples Gallery](https://geocat-examples.readthedocs.io/en/latest/) or
-    the `Plots` as well as `GeoCAT-comp-examples` directories of this repo,
+    the `Gallery` as well as `GeoCAT-comp-examples` directories of this repo,
 
     - The list of [Issues](https://github.com/NCAR/GeoCAT-examples/issues) for this repo to see if any of
     the existing to-do items are something you might be interested in working on.

INSTALLATION.md

@@ -5,16 +5,31 @@ Please refer to [GeoCAT Contributor's Guide](https://geocat.ucar.edu/pages/contr
 the whole GeoCAT project.
 
 
-## Installing GeoCAT-examples
+## Building GeoCAT-examples
 
-GeoCAT-examples is not distributed as a conda package; thus, there is no conda installation for it.
+GeoCAT-examples is a collection of standalone visualization examples, and it is not distributed
+as a conda package; thus, there is no installation for it (via conda or other package management systems).
 
-The easiest way to access GeoCAT-examples is cloning the repo and then using a
-[Conda](http://conda.pydata.org/docs/) environment, building file of which is provided in this repo, as follows:
+The easiest way to access GeoCAT-examples scripts as a whole is by cloning the repo and then using a
+[Conda](http://conda.pydata.org/docs/) environment.
 
-### How to create a GeoCAT-examples Conda environment
+### Creating a Conda environment
+
+The GeoCAT-examples repository has two different types of implementation for visualization examples:
+
+1. Python scripts (`.py`) under the "Gallery" and "GeoCAT-comp-examples" directories
+2. Jupyter notebooks under the "docs/gallery-notebooks" directory
+
+This repository provides a Conda environment file that can be used to create an evironment to build
+both (1) and (2). However, each of Jupyter notebooks under (2) will require their own additional
+dependencies that are written in the beginning of them and needs to be installed into the active
+Conda environment. Furthermore, users with advanced Conda knowledge will see that the Conda environment
+file provided in this repo contains much more dependencies than the base Conda environment reuqires (i.e.
+essentially a Jupyter technology such as Jupyter Lab to execute notebooks) to build (2).
+
+In order to create a Conda environment using the file provided by this repo, from the root directory of
+the cloned geocat-examples directory, run the following commands:
 
-From the root directory of the cloned geocat-examples repository, run the following commands:
 ```
     conda env create -f conda_environment.yml -n geocat-examples
     conda activate geocat-examples
@@ -25,12 +40,15 @@ dependencies of GeoCAT-examples listed under `conda_environment.yml` file (such
 `geocat-datafiles`, `cartopy`, `matplotlib`, `netcdf4`, etc.); therefore, there is no need for
 explicitly installing those packages.
 
-If you somewhat need to make use of other software packages with GeoCAT-examples, you may wish
-to install them into your `geocat-examples` environment at anytime with a command as in the
+If you somewhat need to make use of other software packages with GeoCAT-examples or are interested in
+running the Jupyter notebooks under (2) mentioned above, you may wish/need to install them into your
+`geocat-examples` environment at anytime with a command as in the
 following example (assuming your `geocat-examples` environment is already activated):
 
     conda install -c bokeh bokeh
 
+or in the way that is suggested by each Jupyter notebook under (2).
+
 If you are interested in learning more about how Conda environments work, please visit
 the [managing environments](https://docs.conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html)
 page of the Conda documentation.

conda_environment.yml

@@ -13,10 +13,12 @@ dependencies:
   - cartopy
   - geographiclib
   - jupyter
+  - jupyterlab
   - make
   - matplotlib=3.3.0
   - metpy
   - mock
+  - nbsphinx
   - netcdf4
   - pillow
   - pip

docs/_static/theme_overrides.css

@@ -0,0 +1,4 @@
+/* delete margin from side of content */
+.wy-nav-content {
+    max-width: none !important;
+}

docs/conf.py

@@ -4,18 +4,23 @@
 # list see the documentation:
 # https://www.sphinx-doc.org/en/master/usage/configuration.html
 
+import os
+
+import logging
+
+# the following lines suppress INFO messages when files are downloaded using geocat.datafiles
+import geocat.datafiles
+import pooch
+
+logger = pooch.get_logger()
+logger.setLevel(logging.WARNING)
+geocat.datafiles.get("registry.txt")
+
 # -- Path setup --------------------------------------------------------------
 
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
-#
-import importlib
-import os
-import warnings
-
-# import sys
-# sys.path.insert(0, os.path.abspath('.'))
 
 # -- Project information -----------------------------------------------------
 
@@ -35,8 +40,16 @@
 # ones.
 extensions = [
     'sphinx_gallery.gen_gallery',
+    'nbsphinx',
+    'sphinx_gallery.load_style',
 ]
 
+# Define what extensions will parse which kind of source file
+source_suffix = {
+    '.md': 'sphinx_gallery',
+    '.rst': 'restructuredtext',
+}
+
 image_scrapers = ('matplotlib',)
 
 # Add any paths that contain templates here, relative to this directory.
@@ -79,22 +92,35 @@
 import sphinx_rtd_theme
 
 html_theme = 'sphinx_rtd_theme'
-html_style = None
 html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
+html_static_path = ['_static']
+html_logo = '_static/images/nsf.png'
+html_style = None
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ['_static']
 
+html_theme_options = {
+    'navigation_depth': 2,
+}
+
 # Specify master_doc (see https://github.com/readthedocs/readthedocs.org/issues/2569#issuecomment-485117471)
 master_doc = 'index'
 
+
+# Allow for changes to be made to the css in the theme_overrides file
+# This is used for dynamically adjusting page width in this repo
+def setup(app):
+    app.add_css_file('theme_overrides.css')
+
+
 # Configure sphinx-gallery plugin
 from sphinx_gallery.sorting import ExampleTitleSortKey
 
 sphinx_gallery_conf = {
-    'examples_dirs': ['../Plots', '../GeoCAT-comp-examples'
+    'examples_dirs': ['../Gallery', '../GeoCAT-comp-examples'
                      ],  # path to your example scripts
     'filename_pattern': '^((?!sgskip).)*$',
     'gallery_dirs': ['gallery', 'gallery-geocat-comp'
@@ -103,16 +129,10 @@
     'matplotlib_animations': True,
 }
 
-html_theme_options = {
-    'navigation_depth': 2,
-}
-
-import logging
-
-# the following lines suppress INFO messages when files are downloaded using geocat.datafiles
-import geocat.datafiles
-import pooch
+# Configure nbsphinx
+nbsphinx_prolog = """
+Download notebook (Right click and save):
+https://github.com/NCAR/GeoCAT-examples/raw/main/docs/{{ env.doc2path(env.docname, base=None) }}
 
-logger = pooch.get_logger()
-logger.setLevel(logging.WARNING)
-geocat.datafiles.get("registry.txt")
+----
+"""

docs/gallery_nb.rst

@@ -0,0 +1,24 @@
+Notebook Gallery
+================
+
+This gallery contains visualization examples that are solely implemented in the
+Jupyter notebook format (i.e. no `.py` script). Most, if not all, of these
+notebooks are interactive  (i.e. the rendered images can be panned, zoomed,
+etc). However, these notebooks are currently pre-rendered only, i.e. the
+gallery only shows static renderings of the notebooks (Notebooks won't actually
+show any greater resolution when the user zooms a plot; the user can zoom in all
+they like, but the data is never re-rendered). To fully experience
+the power of interactive exploration within a notebook, it will need to be
+downloaded and executed locally as described below.
+
+If the reader would like to execute these notebooks in their local setup, they
+will need to have a conda environment that includes a Jupyter technology of
+preference (e.g. Jupyter Lab, etc.). For further details about how to create
+such an environment, please refer to the `Installation document
+<https://github.com/NCAR/GeoCAT-examples/blob/main/INSTALLATION.md>`_ of this repo.
+
+In addition to the above environment, each notebook
+example lists its own dependencies that should be installed as well.
+
+.. nbgallery::
+   ./gallery-notebooks/Datashader/MPAS_Datashader_Trimesh

docs/index.rst

@@ -30,11 +30,13 @@ download Python script and/or Jupyter notebook.
 
    ./gallery/index
    ./gallery-geocat-comp/index
+   ./gallery_nb
    ./install
    ./citation
    ./support
 
 
+
 Indices and tables
 ==================
 

docs/install.rst

@@ -2,36 +2,14 @@ Installation
 ============
 
 This installation guide includes only the GeoCAT-examples installation instructions.
-Please refer to `GeoCAT Contributor's Guide <https://geocat.ucar.edu/pages/contributing.html>`_ for installation of
-the whole GeoCAT project.
+Please refer to `GeoCAT Contributor's Guide <https://geocat.ucar.edu/pages/contributing.html>`_
+for installation of the whole GeoCAT project.
 
-Create a GeoCAT-examples Conda environment
-------------------------------------------
-GeoCAT-examples is not distributed as a conda package; thus, there is no conda installation for it.
+Installing GeoCAT-examples
+--------------------------
 
-The easiest way to access GeoCAT-examples is by cloning the repo and then using a `Conda <http://conda.pydata.org/docs/>`_
-environment and then building file of which is provided in this repo as follows:
-
-From the root directory of the cloned geocat-examples repository, run the following commands:
-
-.. code-block:: bash
-
-   $ conda env create -f conda_environment.yml -n geocat-examples
-   $ conda activate geocat-examples
-
-Note that the Conda package manager automatically installs all the required
-dependencies of GeoCAT-examples listed under ``conda_environment.yml`` file (such as ``geocat-comp``,
-``geocat-datafiles``, ``cartopy``, ``matplotlib``, ``netcdf4``, etc.); therefore, there is no need to
-explicitly install those packages.
-
-If you need to make use of other software packages with GeoCAT-examples, you may wish
-to install them into your ``geocat-examples`` environment at anytime with a command as in the
-following example (assuming your ``geocat-examples`` environment is already activated):
-
-.. code-block:: bash
-
-   $ conda install -c bokeh bokeh
-
-If you are interested in learning more about how Conda environments work, please visit
-the `managing environments <https://docs.conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html>`_
-page of the Conda documentation.
+GeoCAT-examples is a collection of standalone visualization examples, and it is not distributed
+as a conda package; thus, there is no installation for it (via conda or other package management
+systems). Because of this, this sections refers to building GeoCAT-examples, and it can be followed
+better through the `Installation document on Github repository
+<https://github.com/NCAR/GeoCAT-examples/blob/main/INSTALLATION.md>`_.