Issues with automated docs building

[timlinux]

Currently we have two sites for docs:

• Staging : http://staging.docs.inasafe.org - based off the develop branch
• Production: http://docs.inasafe.org - based off the master branch

Yesterday in helping to @Charlotte-Morgan to prepare for an important demo we came across a number of issues. I ask those in CC to help to get these resolved ASAP please.

Merges from master to develop

It is an expectation that Pull Request initiators ensure that their work is mergeable without conflicts. There are a few good ways to ensure this:

• Make many small pull requests rather than one large one - we can update master incrementally as we improve things (e.g. a chapter at a time). I know this is not always possible, but it would be good to strive for.
• Test/do the merge in your own local environment regularly. Assuming your are in the develop branch you could do:

git fetch upstream
git merge upstream master
git commit -m "Merged any changes from master" -a
git push origin develop

When the time comes to merge your PR from develop to master, we should get no conflicts.

Nitpicky mode

@rduivenvoorde has enabled nitpicky mode which will ensure that a build will fail if there are any malformed parts to the document tree. We need to ensure that when an issue is found, travis or the local build / server build properly reports what the error is so that @Charlotte-Morgan and @adissadis know why their builds are failing.

Git updates for automated builds

@rduivenvoorde we need to ensure that whenever we build we are doing a git update and a git hard reset so that we can be sure the branch on the build server is matching the one in the code tree. Could you also add the git SHA (with a link back to github for double bonus points) to the footer of every page like you have done with the time stamp?

I have already added git update / reset commands for the staging build but this needs to be checked and replicated (but against master branch) on the live server.

Version number in conf needs to be updated

@adissadis this is for your info - its probably a good idea to update the version number in conf.py to match the version of InaSAFE the docs are targeting.

We should synchronise our scripts with those in QGIS docs

Originally QGIS docs were based on my / Werner's scripts and then there was some back and forth exchange between the two projects build systems. @rduivenvoorde it would be great if you could update the build system to be as close as possible in sync with that used by QGIS again.

Travis is not reporting failures properly

@rduivenvoorde Can we test that travis actually gives a red mark when the build fails? Part of the reason for the complications yesterday was that I though everything was passing when I suspect there may actually have been failures.