Change tutorials site builder to nbsphinx

[eteq]

In #145 we discussed the idea of using sphinx plugins to generate the tutorials page instead of our custom (but hacky and fairly broken) tutorials generator. Making the tutorials in sphinx has a variety of advantages, including:

• We can integrate it with the same theme used in docs, for a more consistent user experience
• We can link more easily to other sphinx docs using intersphinx
• A custom build process isn't required because sphinx just does html natively

But we still want tutorials to be written as notebooks. With that in mind, @adrn pointed out nbsphinx, which we think will let us do what we need. So we need to explore using it to generate the docs.

[pllim]

FWIW in my past experience using nbconvert (is that related to nbsphinx?), while it worked fine in RTD, it broke Sphinx builds on Travis CI because it always emitted warnings. Maybe this has changed since I last used it, but just FYI.

[eteq]

Hmm, thanks @pllim - nbconvert is a separate development from nbsphinx - the latter is a sphinx extension and the former is a jupyter subcommand. but we really need to determine if what you're saying is the case for nbsphinx. I'm also realizing that we need to be surenbsphinx allows a "this cell failed, but it's expected to fail" option, as some of the notebooks intentionally do that pedagogically.

[adrn]

I guess @eteq isn't reading my messages :( - see #150

[eteq]

my bad, thanks @adrn. Apparently nbsphinx uses nbconvert, so @pllim's point is a potential serious issue then

[bsipocz]

@adrn - isn't your notifications are full like ours?

[pllim]

@eteq , maybe there is no reason to panic (and sorry to cause it) because now that I look at stginga tests, I recall that @saraogaz might have fixed it somehow.

For example, see https://travis-ci.org/spacetelescope/stginga/jobs/264491709 -- Even though there is a traceback about nbconvert.utils.pandoc.PandocMissing: Pandoc wasn't found (because it is checking right before Travis installs pandoc no, I actually don't know why), the build still passed.

[SaOgaz]

The problem I was running into was a Pygments warning/error (don't remember). The solution was to to grab ipython from the conda-source channel, It's super annoying... jupyter/nbconvert#528