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.

Python docstrings do double-duty as reStructuredText input for `sphinx-build` and parseable syntax for `docopt`. This works but requires blank lines in between options definitions, since sphinx treats those as definition lists.

The docs Makefile was cleaned up to minimize the diff between what `sphinx-quickstart` generates for a new project and ours. Also, the `sphinx-check` workaround wasn't really working, so just disable the "user-friendly" up-front check for `sphinx-build` so we can do `make test`. If `sphinx-build` isn't in the path, that will be fairly obvious when the make target fails anyway.

Closes #1942.