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.

Docstrings do double-duty as reStructuredText input for `sphinx-build` and parseable syntax for `docopt`. This works but requires spaces in between options definitions, since sphinx treats those as definition lists.