Examples in documentation

[bdice]

The documentation would be vastly more useful with some example code snippets. @klarh I'd appreciate your thoughts on this:

• Do you want to include examples as a git submodule, as we've done for freud and fresnel (to keep the repo size reasonable)?
• Should examples be based on https://github.com/glotzerlab/plato-gallery (should that repo be expanded to include more simple figures)?
• What backends should we showcase for examples? Interactive vs. ray-traced?
• Should the notebooks be pre-rendered (requires a dev machine or Docker image that works with all/most backends) or rendered on ReadTheDocs (potentially time-intensive, hard to configure dependencies)?

Related: I was able to embed pythreejs widgets into freud's documentation: https://freud.readthedocs.io/en/stable/examples/examples/Visualization%20with%20plato.html

[klarh]

I think linking in plato-gallery would be great! I had some configuration for nbsphinx integration in the nbsphinx branch, but I ran into a problem with one of the backends and left it to solve later. Currently that branch just includes the test scenes and displays which primitives were used in each test scene, but having more intelligent/meaningful scenes in plato-gallery (perhaps expanding on the tutorial notebooks) would be useful.

I think showcasing all the backends (to the extent that we can) would be useful; obviously some things lend themselves to looking nicer when raytraced than others, so keeping that in mind when choosing would be great.

If they are in plato-gallery already, I think it's fine to have the notebooks be pre-rendered (especially since readthedocs times out builds pretty quickly, if I recall correctly). If you want a docker image, I think you should be able to use the plato-tests image or generate one with repo2docker on either the plato or plato-gallery repositories, since binder integration with both has been working for a while now...