Fail doc build on warnings

[dstansby]

I noticed that the documentation build allows warnings through - these can include things like broken links, broken RST, or duplicate references. I've enabled the -W flag by default in the makefile so these get caught, and fixed the few existing warnings.

TODO:

• Add unit tests and/or doctests in docstrings
• Add docstrings and API docs for any new/modified user-facing classes and functions
• New/modified features documented in docs/tutorial.rst
• Changes documented in docs/release.rst
• GitHub Actions have all passed
• Test coverage is 100% (Codecov passes)

[d-v-b]

Looks good to me! I think we need some release notes.

[joshmoore]

Thanks!