Clean up all outstanding ReST errors and warnings

It's easier for us to spot new problems in the formatting of our ReST
docs if there are no warnings to start with.

To that end, I've fixed all the errors and warnings generated by a run
of `tox -edocs`

In addition, following jogo's suggestion, I've added a setting to
setup.cfg such that any warnings generated by Sphinx during the doc
build process will be understood by Jenkins to mean that the build
failed. This should help us to make sure that we don't have
syntactical errors creeping back into these docs.

Change-Id: Ib3c7ee7013306f3622f3f3e2729b23ea6ac55234
Merge "Clean up all outstanding ReST errors and warnings"