documentation issues

[basnijholt]

• documentation of stable is broken
• the page loads very slowly, see Documentation is loaded very slowly readthedocs/readthedocs.org#5515
• we need to be able to display the documentation before merging, see add building of test documentation of RTD #169
• when an error occurs the documentation shouldn't finish the build, see Exception control jupyter/jupyter-sphinx#25

[basnijholt]

I don't think this can be fixed without releasing a new version.

[akhmerov]

We should also somehow set it to refuse to build whenever an error is raised.

[basnijholt]

We should also somehow set it to refuse to build whenever an error is raised.

I am not sure if this is possible because in the documentation we raise an error somewhere to show how to debug.

I propose an alternative in #169.

[akhmerov]

We can incorporate this on the jupyter-sphinx side, see jupyter/jupyter-sphinx#25

[basnijholt]

Yes, I agree that that would be a good solution, but not the full solution.

The reason why the docs were broken most recently (#168) wasn't because of an error but because of the fact that some javascript libs were loaded differently.

So I still think it is a good idea to be able to preview the docs somehow before merging.

[akhmerov]

Right, absolutely. Both are important.