Updated by
Modified
README.md- Ignore whitespace
-1. Using PySide as the desktop GUI backend. Because it is a wrapper around Qt, it can be difficult to get consistently-linked versions without using a package manager. Furthermore, the pyside devs can't currently support windows for python3.5 and greater [link](https://github.com/pyside/PySide/issues/132), so they do not provide python3.5-and-greater packages for any OS. We could make plato backend-agnostic ([link to proposal](https://docs.google.com/document/d/1nUzkUD0PsiXYHvZY7HtNRX0hGkbWXfxrHpEUEbMjeZY)) to work around needing pyside, so let Matthew know if you're interested in helping fix this!
-2. Using jupyter notebooks. The python packages `notebook` (jupyter notebook server library), `ipywidgets` (python-side notebook widgets code), and `widgetsnbextension` (browser-side notebook widgets code) need to have consistent versions installed simultaneously. This difficulty is somewhat increased by jupyter's extension interface using global state inside your home directory.
-In this document we'll try to keep living walkthrough-style guides using particular working versions of packages. If something doesn't work, please edit it to update or create an issue [here](https://bitbucket.org/glotzer/plato/issues/new). Some more general (non version-specific) troubleshooting-type information can be found [in the documentation](https://glotzerlab.engin.umich.edu/plato/troubleshooting.html).
+Sometimes it can be difficult to get an entire working stack of vispy and its dependencies, especially with jupyter and friends involved. In this document we'll try to keep living walkthrough-style guides using particular working versions of packages. If something doesn't work, please edit it to update or create an issue [here](https://bitbucket.org/glotzer/plato/issues/new).
-This will at least work for jupyter notebooks; pyside installation depends on having installed Qt using another method. Set up the environment:
+If We **strongly** encourage the use of virtual environments with plato as opposed to installing into your home directory (`python setup.py install --user` or `pip install -e`). This is because of how easy it is to mix inconsistent versions of jupyter kernels, ipywidgets, the notebook extension, and vispy if you have cruft from other installations lying around. This method will use the system site-packages directory as a base, in case you want to use versions of (for example) `pyside`, `numpy`, `tensorflow`, or other packages that are installed by your package manager. First set up the environment:
+Install jupyter and its dependencies, forcing it to be installed within the environment (an externally-installed jupyter may not have the kernel set up to work inside the virtual environment, for example); note that vispy doesn't currently work with ipywidgets 7 or greater:
-pip install ipywidgets==5.2.2 notebook==4.4.1 widgetsnbextension==1.2.6 ipykernel git+https://github.com/vispy/vispy.git git+https://bitbucket.org/glotzer/peact.git@master git+https://bitbucket.org/glotzer/plato.git@master
-pip install ipywidgets==5.2.2 notebook==4.4.1 widgetsnbextension==1.2.6 ipykernel git+https://github.com/vispy/vispy.git git+ssh://git@bitbucket.org/glotzer/peact.git@master git+ssh://git@bitbucket.org/glotzer/plato.git@master