major changes to docs and ipynb