Automatically build (some of the) documentation

[edoddridge]

I've had a poke around, and it seems that Travis-CI can integrate with a number of services, including GitHub pages, to push content to a place where we can serve a website from.

This could give us a way to automatically display the results of benchmarking and other tests in the user facing documentation, once it's written per issue #61.

There are limits on the per-job runtime that we can use at Travis-CI, but they seem pretty generous.

[axch]

Under this general umbrella, we should eliminate Doxygen output from the git repository. Either abandon Doxygen entirely, or teach Travis to rebuild the docs and serve them somewhere.

[edoddridge]

I started using Doxygen because it could build documentation from Fortran source code.

Since we've decided to ship a Python package that just happens to use hidden Fortran for the heavy numerics, there is less need for the documentation generator to go poking through the Fortran. This gives us more options for building the documentation.

[edoddridge]

I've been trying to work out a way that we can get output generated by Travis-CI into the documentation. So far I've found:

• using github pages directly seems difficult. I think we'd need to have Travis-CI push directly into the master branch which feels dangerous, or we can have it push into a gh-pages branch, but then the GH pages website is hosted from the root directory of that branch, which means we can't keep a sensible folder structure.
• we can use read the docs to build documentation from a specific branch, or all branches, every time it is pushed. If we set it to build from the gh-pages branch we can easily make Travis-CI push everything to that branch when master is updated. This push can include graphics that are generated by scripts during the testing on Travis-CI. Read the docs is clever enough to look for a docs folder and build in there.
  • A downside to this is that we need to build the package on read the docs for it to automatically go through and document the python functions and classes. But, that's not particularly difficult to automate.

Neither of these feel optimal to me. There are too many steps where things could break. I'm currently leaning towards the second option of having read the docs build documentation from a branch that Travis-CI pushes things into.

A third option is to keep whatever graphics and model outputs we want in the documentation checked in to the master branch and rebuild them by hand when required. I dislike that this increases the maintenance burden of maintaining the documentation.

[axch]

So, if memory serves, the gh-pages branch is supposed not to share any history with master (and never to be merged), but rather to contain only the documentation, at the top level. That is, there is no expectation that master and gh-pages would have anything resembling a similar directory structure. I would expect Travis to deal with that correctly, if it is so set up.

[edoddridge]

Ah ok. That makes sense. In that case, using Travis-CI to push to the gh-pages branch seems like the best option. I've got it working and will open a PR now.