Merge pull request planetlabs#63 from planetlabs/automate-notebooks-32

Create tools for automatically running notebooks, change notebooks so they run successfully automatically, cache data for slow running notebooks. planetlabs#32 planetlabs#36

Author: jreiberkyle

CONTRIBUTING.md

@@ -0,0 +1,25 @@
+# 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
+```
+
+or, optionally, run only notebooks in a subdirectory using
+```
+$> pytest tests/test_notebooks.py --path <subdirectory>
+```
+
+## 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 its path to 
+`tests/skip_notebooks`. 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.**

README.md

@@ -54,19 +54,20 @@ This will build and install the Docker image on your system, making it available
 time (between 10 and 20 minutes) depending on your network connection.
 
 ### Run the container
-To run the container (after building it), add your Planet API key below and issue the following command:
+To run the container (after building it), add your Planet API key below and issue the following command from the git repository root directory:
 ```bash
-docker run -it --rm -p 8888:8888 -v $PWD/jupyter-notebooks:/home/jovyan/work -e PL_API_KEY='[YOUR-API-KEY]' planet-notebooks
+docker run -it --rm -p 8888:8888 -v $PWD:/home/jovyan/work -e PL_API_KEY='[YOUR-API-KEY]' planet-notebooks
 ```
 
 This does several things:  
 
 1. Maps the docker container's ```8888``` port to your system's ```8888``` port.  This makes the 
 container available to your host systems web browser.
 
-1. Maps a host system path ```$PWD\jupyter-notebooks``` to the docker containers working 
-directory.  This ensures that the notebooks you create, edit, and save are available on your host system,
-and are not *destroyed* when the you exit the container.
+1. Maps a host system path ```$PWD``` to the docker containers working  directory.
+This ensures that the notebooks you create, edit, and save are available on your host system under the
+`jupyter-notebooks` sub-directory and are not *destroyed* when the you exit the container.
+This also allows for running tests in the `tests` sub-directory.
 
 1. Starts in an interactive terminal and is accessible through http://localhost:8888.