General: Generating notebook tests

These instructions assume you have a notebook called Tutorial.ipynb which may either be a new notebook or an existing notebook that has been changed and needs to be tested. This notebook is assumed to live in doc/Tutorials:

• First put your new tutorial notebook in doc/Tutorials. Make sure you have cleared the output first before saving the notebook using the notebook toolbar:

  Cell -> All Output -> Clear
  

• Make sure to commit the new notebook to the /doc directory:

  $ cd doc/Tutorials
  $ git add Tutorial.ipynb
  $ git commit -m "Added Tutorial notebook"
  

• To be safe, make sure the reference data is using the right branch for your project:

  $ cd ../reference_data
  $ git branch
  

  The branch should be marked as dataviews-data or topo-data or similar. If not, make sure to git checkout the appropriate branch.

• Now check that you have the latest reference data:

  $ git pull
  

• Next move to the nbpublisher folder. For a notebook Tutorial.ipynb in Topographica you can now regenerate the test data:

  $ cd ../nbpublisher
  $ ./test_notebooks.py topographica -p ../Tutorials/Tutorial.ipynb -r
  

  The syntax for regeneration is ./test_notebooks.py <project> -p <notebook path> -r where -r indicates that the data is to be regenerated. Without -r the notebook will be tested instead against the existing reference data. The project may be one of dataviews, imagen, featuremapper or topoographica.

• Wait for the test data to be regenerated. Once it is complete, move back to the reference_data directory and see if the data has been updated:

  $ cd ../reference_data
  $ git status
  

  You should see that new files have been added or existing files have been modified.

• Now git add the appropriate files, create a commit and push the updated reference data:

  $ git add *  # Make sure to only add the correct files!
  $ git commit -m "Updated the reference data for Tutorial notebook"
  $ git push
  

• Finally, update the submodule reference so that everyone else can use your freshly generated reference data:

  $ cd ..   # Make sure you are in the project repository and not in the reference data!
  $ git add reference_data
  $ git commit -m "Update reference data submodule reference."