add notebooks to docs

[7yl4r]

Is there a way to include the jupyter notebooks in the docs? A rendered output would be nice, but a list of links & short descriptions would be good too.

[ocefpaf]

This is how I do it but I believe there are easier ways out there:

1. add nbsphinx to the dev requirements
2. have a directory with the notebooks outside of the docs
3. in the CI that builds the docs I run the notebooks with nbconverter and move them into the docs/source directory
4. list them in the index.rst file so sphinx can find them

The reason why I keep the notebooks in a separate folder is so we can commit them without the outputs for cleaner diffs and slimmer repos. Also, the nbconvert step becomes a test for them, if the notebooks fails to run the doc build will fail.