fix(docs): clean up sources and treat warnings as errors

Many deficiencies in the docs were being skipped over because
`sphinx-build` is lenient. Adding the `-W` flag treats issues
such as "missing reference" and "class not found" as errors.
Merge pull request #1952 from mboersma/1942-fix-doc-testing

fix(docs): clean up sources and treat warnings as errors