update docs workflow + proper Cosmology docs

[nickhand]

A few updates:

• api docs are generated with the builtin auto summary feature from a dynamically generated modules.rst file
• there is now a proper list of methods/attributes for Cosmology(), linking to classylss -- this is accomplished with a custom sphinx template passed to auto-summary
• This solves the issue of RTD timeouts (15 mins max) by using Jupyter notebooks instead of the ipython directive, which was taking up too much time when building the docs. Notebooks support RST raw cells, so we can do any modules that need code examples in notebooks instead
• fixes various deprecated syntaxes in notebooks

[nickhand]

The general workflow that I am using is doing:

make notebooks
make html

which executes all *ipynb files, and then builds the docs. Then, on RTD, the ipynb files are not re-executed, so we shouldn't bump up against the timeout limit

[rainwoodman]

Looks like magic, but as long as it works.

I slightly liked the .rst files better than notebooks, because they have better looking diff-sets.

[nickhand]

Yeah the notebook solution is not ideal (although it's only the docs with the IPython directive that get replaced), but I think it's the cleanest solution at the moment. I imagine issues like this are why projects like yt have a dedicated machine to build the docs, custom domain, etc

[rainwoodman]

Here is an issue -- get_pk occured twice.. usually the one from primordial is shadowed by the one from Spectra. I think we shall rename get_pk in primordial to get_pk_primordial to resolve this conflict. Is there a way to detect these conflicts in docs?

[nickhand]

ah yes, I noticed that and meant to fix that in the docs. I'll do that now

[rainwoodman]

Looks like it is less code if you keep the duplicates around, but issue a warning instead? The 'dir' method of a cosmology object does return every member it can find -- will it be useful to simplify the autosummary code? would it be useful if we implement dir on the class instead?

[nickhand]

I think we should avoid leaving duplicates in the docs list, since that could be confusing for the user.

For the auto summary list, I'm searching in the same manner as the Cosmology's getattr (not dir), so now it always links to the proper attribute that the user will get. This is also an issue for sigma8, where we overload the Spectra attribute in the Cosmology() class.

[nickhand]

FYI, I've built the docs with this update here:

http://nbodykit.readthedocs.io/en/cosmo-docs/index.html

[nickhand]

this addresses and closes #422