Move docs from ReadTheDocs to Github pages

We’ve discussed this before and I think there is agreement on the change, but I didn’t find an issue and wanted to take notes.

I’m moving the docs from ReadTheDocs (RTD) to Github Pages (GHP).

The problems with RTD are:

• Currently build times out -> no easy way to get it to work
• The RTD build has been hard to maintain - every few months there’s build failures and they are often hard to debug

This isn’t trivial to set up in a good way, and I’m not sure yet about the best way. I’ll document it after I have something that works.

For now, I’ll try doing everything in a separate repo gammapy/gammapy-docs, probably via a make.py script there that has sub-commands to build and deploy the current as well as older versions of the docs. I don’t know yet if I’ll also have time to add a scripted env way to set up execution environments for different versions of the docs, or if I do this manually for now for v0.6 and see if I can get it built.

For now, docs are built and deployed manually, and then if we want we can add a docs build and deploy in addition on travis-ci or Jenkins. Probably that’s only needed for the master branch and there it’s easy to do using e.g. https://github.com/Syntaf/travis-sphinx and maybe https://github.com/davisp/ghp-import .

Later we can try adding the multi-version selection on the docs. For now the only thing I could find was https://robpol86.github.io/sphinxcontrib-versioning/ and it seems unmaintained. But probably the RTD version chooser is also open source or maybe there is something else or it’s not too hard to roll our own.

[Bultako]

@cdeil nice ! as a final touch it would be good to have the very last version published, there are still many places with references to RTDs.

i.e. http://docs.gammapy.org/dev/notebooks/first_steps.html http://docs.gammapy.org/dev/development/setup.html#docs-gammapy-org

[cdeil]

This is working now, the switch is done:

• http://docs.gammapy.org/dev/
• http://docs.gammapy.org/0.6/
• http://docs.gammapy.org -> http://docs.gammapy.org/dev/
• http://docs.gammapy.org/stable/ -> http://docs.gammapy.org/0.6/

I’ve also updated the links to docs.gammapy.org from gammapy.org just now: https://github.com/gammapy/gammapy-webpage/commit/bbe0c87619cf4759867a75550a284f367ed141ea

I’m keep this issue open as a reminder for me to improve this later, and for further discussion.

At the very least:

• Automate the build and deploy for the dev branch, triggered by commits to gammapy master
• Automate a few things in https://github.com/gammapy/gammapy-docs/blob/master/make.py, e.g. introduce an info.json that contains the latest stable version, and propagate that to here.
• Set up Google analytics to get some insight into which docs are being used.
• Document how things work at http://docs.gammapy.org/dev/development/setup.html#docs-gammapy-org and what steps are necessary concerning a new docs version on http://docs.gammapy.org/dev/development/release.html

There’s also other possible improvements, like the docs version chooser feature as discussed with @Bultako above.