Switch tutorial infrastructure to use Sphinx

[adrn]

This is a major overhaul of the build/deploy machinery underlying the astropy tutorials site. The core idea is to move from our (custom, broken) scripts for running and deploying the tutorial content as static pages. This instead uses nbsphinx and the astropy sphinx template to build the tutorials into a website that looks more like the astropy documentation.

There is a rendered demo of this here.

cc @eteq @astrofrog @bsipocz @kelle

[bsipocz]

why do we need astropy_helpers here, is it only for the css?

[adrn]

Yea, AFAIK

[adrn]

OK, you should be able to check out my branch and run python setup.py build_docs and see the new site. See discussion items / questions listed above though

[bsipocz]

Would be python setup.py build_docs enough as a test in our CI? I guess we both want to test the content and whether it builds, don't we? Is setup.py test still works or it's now something else?

(I'm asking so that it's not dummy script that I put in the travis framework POC PR)

[adrn]

I think build_docs might be enough? have to think about it

[bsipocz]

In case of narrative docs it doesn't checks the content. Does it work that differently for notebooks?

[adrn]

I just found out about nbval - that might be the solution, and just use nbsphinx to build/display the tutorials?

[adrn]

As @eteq pointed out in a chat window, it looks like nbval operates by comparing pre-cached output to output generated from re-running the notebook. Currently, the notebooks stored in the repo have their output cleared, so we would have to change our routine if we went with this route...

But @bsipocz: I didn't follow your point

In case of narrative docs it doesn't checks the content.

[adrn]

Ugh, just noticed something else undesirable...

In many of our notebooks, we have links that are formatted like code, e.g., Quantity. These don't convert to rst because, apparently, rst doesn't support nested inline markup!!!!. To quote a comment from that link:

This is horrible. All sane markup languages support indefinite nesting of inline markup, because this is 2016. Context-free parsing has been trivially solved since 1959. (Chomsky: "On certain formal properties of grammars.") The inability of the reStructuredText parser to perform genuine context-free parsing is a crass, ugly blemish on an otherwise sterling facade. The well-defined and highly extensible syntax of reST deserves better.

A consequence of this is that links like:
[``Quantity``](docs.astropy.org/...)
become this in rendered html:
`Quantity <http://docs.astropy.org/en/stable/units/index.html>`__
see an example here: http://www.astro.princeton.edu/~adrn/astropy-tutorials/tutorials/Coordinates/Coordinates.html

Of course, #160 would solve this...but that requires some serious engineering...

[adrn]

Almost there. @eteq 's changes are merged and comments addressed, but still a few things to resolve. Travis and RTD both passing right now, here's the current version of the site: http://astropy-tutorials.readthedocs.io/en/latest/:

• The text width needs to be adjusted (too wide right now) - can we use the custom.css file?
• The notebook download links are broken because for some reason they aren't getting copied into _static
• We can remove (or decide whether to remove) the setup.cfg and setup.py files

[eteq]

OK, I've pushed some changes that remove the setup.* and replace with a Makefile in the root of the repository. So now the process is just cloning the repo, doing make html, reading the error about git submodule, doing it, and then make html again which will actually work 😉

One remaining task:

• update the dev docs (and readme) to reflect this new layout

will try to do that ASAP