add automatic running of notebooks, describe in CONTRIBUTING file

Author: jreiberkyle

CONTRIBUTING.md

@@ -0,0 +1,20 @@
+# Contributing to Notebooks
+
+## Docker Image Validation
+
+The docker image must be able to run all notebooks. Whenever a change is made to
+the docker image, it must be validated. This can be accomplished by automatically
+running all of the notebooks using the supplied test script. From the root
+directory within the docker container, run:
+```
+$> pytest tests/test_notebooks.py
+```
+## Automated Running and Skipping
+
+To enable validation of the Docker image, every notebook should run successfully
+when run from the command line. For notebooks where that just is not possible, 
+the notebooks can be excluded from automated running by adding a file named
+`norun` to the notebook directory. Note that this results in the entire directory
+of notebooks being skipped. Excluding a notebook from automated running
+means that it is excluded from Docker Image validation. **If a notebook is
+skipped, it will not be guaranteed to be supported by the Docker image.**

planet-notebook-docker/requirements.txt

@@ -8,6 +8,7 @@ numpy==1.14.* # pinned because numpy 15.0 throws runtime warning
 opencv-python==3.3.0.10
 planet
 pyproj
+pytest
 rasterio==1.0a12
 scikit-image
 scikit-learn

tests/test_notebooks.py

@@ -0,0 +1,53 @@
+"""
+Run each notebook in the jupyter-notebooks directory.
+
+Notebooks are run using nbconvert.
+
+pytest runs each test as a unit test.
+"""
+import os
+import subprocess
+import tempfile
+
+import pytest
+
+NOTEBOOK_EXT = '.ipynb'
+ROOT_DIR = 'jupyter-notebooks'
+
+
+def find_notebooks(root_dir):
+    print('finding notebooks...')
+    notebooks = []
+    for (dirpath, dirnames, filenames) in os.walk(root_dir):
+        print('{}'.format(dirpath))
+
+        # look for 'norun' file, if present, do not look for notebooks in this dir
+        if 'norun' in filenames:
+            # do not look into subdirectories, modify in-place for walk()
+            dirnames[:] = []
+
+            # clear filenames
+            filenames = []
+
+        # modify in place to filter subdirectories in walk()
+        # https://stackoverflow.com/questions/19859840/excluding-directories-in-os-walk
+        dirnames[:] = [n for n in dirnames if n != '.ipynb_checkpoints']
+
+        for name in filenames:
+            ext = os.path.splitext(name)[1]
+            if ext == NOTEBOOK_EXT:
+                # convert to string so test displays the path
+                notebook_name = str(os.path.join(dirpath, name))
+                notebooks.append(notebook_name)
+    print('found {} notebooks'.format(len(notebooks)))
+    return notebooks
+
+
+@pytest.mark.parametrize("notebook", find_notebooks(ROOT_DIR))
+def test_run_notebooks(notebook):
+    with tempfile.NamedTemporaryFile(suffix=NOTEBOOK_EXT) as tmp_nb:
+        args = ["jupyter", "nbconvert", "--to", "notebook", "--execute",
+                "--ExecutePreprocessor.timeout=600",
+                notebook, "--output", tmp_nb.name]
+        print(' '.join(args))
+        subprocess.check_call(args)