update docs to reflect the new widgets

[satra]

it would be nice to update the documents to reflect the new widgets. if we use nbconvert and embed widgets we could also be able to generate interactive docs to demonstrate. see the ipywidgets docs for an example.

[janfreyberg]

Sounds good. Last time I tried this, I couldn't get the widgets to be embedded in HTML conversions because they were custom widgets. I don't know if this has been fixed, but will check it out.

[janfreyberg]

I've just tried to get this to work - it looks like this should be a lot easier, but even though the widget controls show (check the current front page of the documentation), the actual output does not.

I'm not entirely sure why. I followed the way it's done in the ipyvolume docs (see here for an example), and it looks like using the sphinx ipywidget-display directive does the heavy lifting: https://raw.githubusercontent.com/maartenbreddels/ipyvolume/master/docs/source/index.rst

But for some reason when I do this it doesn't work. Any ideas why? Is it maybe a difference between gh-pages hosting and readthedocs hosting?

I've edited the Makefile and the index.rst files on this branch: https://github.com/nipy/niwidgets/tree/interactive-docs so if you'd like to try...