Refresh cookiecutter for more robust doc build

[tlvu]

Overview

This PR applies the cookiecutter PR https://github.com/bird-house/cookiecutter-birdhouse/pull/96 to ensure no silent ReadTheDocs build failure and for Travis-CI to also catch ReadTheDocs build failure before PR is merged.

Successful RtD generation: https://flyingpigeon.readthedocs.io/en/test-rtd-build/ and matching RtD build logs: https://readthedocs.org/api/v2/build/11548323.txt

Changes:

• Turn RtD warnings to build failure so they do not fail silently.

• Change Travis-CI build config to also build Epub and Latex doc format to catch RtD failure on Travis-CI before PR is merged.

• Various changes to remove all warnings in doc build since warnings will now fail the doc build.

  • For doc build only, to work-around warnings, use a new PYWPS release to support RST anonymous links, currently installing PYWPS from source since no release yet (PR https://github.com/geopython/pywps/pull/542)

  • Rename spatial_analogs.rst to spatial_analogs.rst.inc to work-around the warnings. That file was "included" in processes_des.rst and had no direct reference from the toctree so technically should not break anything. That said, the file used to exist standalone (https://flyingpigeon.readthedocs.io/en/latest/spatial_analogs.html) and as a copy in https://flyingpigeon.readthedocs.io/en/latest/processes_des.html#spatial-analogues. Now that file will only exist inside processes_des.html.

• Add tutorial.rst to toctree

• Enable python 3.8 to Travis-CI builds.

Unrelated changes part of this PR (sorry !):

• Other cookiecutter changes that are unapplied previously are also part of this PR. You might want to look at each commit to avoid the noises.

[cehbrecht]

@tlvu I merge it now ... and we make an update with a new pywps release.

[cehbrecht]

@tlvu thanks :)

[tlvu]

@cehbrecht oh thanks ! That was fast ! But next time please let me do the merge myself for all my PRs, except when I do not have write access.

I was going to do another round of final cruft update before the final merge to make sure we are really up-to-date. No problem, I'll do it on the next PR that will contain the pywps official release.

Also, just curious why you had to use squash merge and not a regular merge? See discussion here https://github.com/Ouranosinc/raven/pull/272#issuecomment-632907304 and here https://github.com/Ouranosinc/xclim/issues/373 about squash merge vs regular merge.

[cehbrecht]

@tlvu sorry for merging too quickly ... I usually have a single commit per PR that is why I'm using squash merge most of the times. But I understand you wanted to keep the commits.

[tlvu]

I usually have a single commit per PR that is why I'm using squash merge most of the times. But I understand you wanted to keep the commits.

@cehbrecht Even for single commit PR, just like my pywps PR https://github.com/geopython/pywps/pull/542, someone could have a direct reference to the existing commit, like I have done in this PR (c97ebca73792c1fb0c32d7b6079385fcd84a73b0), so squashing merge will invalidate that direct link since squashing will create a new commit to replace that existing commit and that existing commit will eventually be garbage collected (destroyed).

Basically squashing is only safe if you are in a private repo and you are the only user of your commit. If the repo is publicly on the internet and a lot of people can be interested in your changes, squashing is just a timing bomb waiting to happen in the future (commits garbage collection could happen in 3 months or later).

Hope I've convinced you regular merge is much safer and squashing is only very special case with a very good reason.