Should we build and host the documentation on read the docs?

[edoddridge]

The documentation is currently built on Travis and pushed to the gh-pages branch, whence it is served through GitHub pages.

This is functional, but has several drawbacks:

• Travis spends much more time running simulations whose outputs are used in the documentation (~14 mins) than it does actually running the test suite (less than one minute)
• If users wish to build a full set of the documentation locally they need to run many different simulations and scripts in order to produce the figures in the docs
• a previous experiment with read the docs currently ranks higher on the Google search results than the actual documentation

The current setup does have the advantage that many simulations are run every time a new commit is pushed. However, testing the code is what the test suite is for - if it isn't providing sufficient coverage, then it should be expanded. Expanding the test suite is a better long term solution than relying on time consuming simulations that are being run primarily for the documentation.

Advantages of switching to read the docs and checking in the figures for the documentation:

• faster tests on Travis
• users could build the documentation locally after cloning the repo (minor)
• the highest ranked search engine results will no longer be the remnants of a past experiment
• we can include the outputs of much more expensive simulations in the documentation - this will likely be very important for documenting n-layer reproductions which are unlikely to fit within the Travis runtime restrictions (this is almost certain to force our hand in the future, but is currently manageable)
• a pdf version of the docs will be automatically built and available for download
• read the docs will host two versions - the latest build and the most recent release

Disadvantages of switching to read the docs:

• outputs will need to be checked in to the repo alongside the scripts that produced them