Automatic documentation build

[tridelat]

So right now, the "new" documentation is on a separate repository (proteus-doc), and the process to push documentation is not automatic at all. There are 3 ways to do it:

• Manual: build the intended version of proteus; build doc locally to specific folder; add changed files, new files, and remove unused files; commit; push to gh-pages branch.
• readthedocs: can automatically document Proteus, fully externally. Ideal, but would require an install of Proteus for it to work properly, and readthedocs build time limit is around 900s, and I don't think there is a way to point at an existing build (not 100% sure about that).
• Travis: can automatically build doc and push it to gh-pages, but only when someone commits to specific branch (such as master).

The last 2 require the documentation to be in the main repository (proteus), and there is a way to bring changes to the documentation from proteus-doc to proteus without loosing commit authorship. I think the Travis solution might be the best one where a full installation of Proteus can be used for sphinx. This will make it very easy for anyone to add a page to the documentation and have it built as soon as it is committed to master.
The only issue I can see with that technique is that Travis could potentially time out when committing to master while it didn't on a PR because now it would also need to build the documentation.
Should we go that route?
@cekees

[cekees]

I think once we get the kinks worked out of the conda package (#1037), then readthedocs may work:
https://docs.readthedocs.io/en/stable/guides/conda.html#activating-conda
Agree that travis is probably the most flexible approach.