Fix docs build and reduce warnings

[uri-granta]

The docs build was temporarily broken due to a nbsphinx bug. This PR:

• updates nbsphinx to a version without the bug (see failing to parse long lines with docutils 0.17 spatialaudio/nbsphinx#549) [in fact this was done independently by another commit, so doesn't show up in the diff]
• fixes the remaining sphinx build warnings
• updates the docs build to error on warnings
• creates a new tox job for building the docs (and updates the documentation)
• creates a new github quality check job to run this job

Note that I may need to separately update the repository config to mark the new check as required for merges to develop.

[hstojic]

I think upgrading GPflow should be left to some other PR, probably it won't break any of the code, but just in case...

[joelberkeley]

bear in mind this is the constraints for CI, not for the library itself, so this number isn't used by users

[uri-granta]

Nevertheless, it might make sense to pin the versions of key libraries in requirements.txt, at least with ~. Though I'd certainly hope that a minor point revision change to gpflow would never break anything!

[joelberkeley]

gpflow doesn't use semver. Patch versions are meant to be backwards compatible

[uri-granta]

We already pin gpflow to 2.1.x in setup.py, so I would personally be happy with this update. Also I'd be very sad if the tests didn't catch a break.

[hstojic]

ok, if patches should be backward compatible lets go with the upgrade

[hstojic]

Looks good so far... why some notebooks didnt appear in manual docs build at the end?

[uri-granta]

Looks good so far... why some notebooks didnt appear in manual docs build at the end?

A change to docutils meant nbsphinx was automatically ignoring notebook files with lines longer than a (not very big) limit. Upgrading nbsphinx fixed it.

[uri-granta]

@joelberkeley You don't happen to know why this isn't working? I'm trying to mark this notebook as orphan (as described in https://nbsphinx.readthedocs.io/en/0.8.3/orphan.html) so we don't get a warning that it's not part of a TOC (it's only included as a doc link in the FAQ).

[joelberkeley]

no idea. I've never worked with headers for notebooks

[hstojic]

all good, tox build successful, no warnings shown and all notebooks seem to be there

[johnamcleod]

Looks good to me!