Documentation cleanup
Documentation cleanup

Several warnings and errors were reported when building
documentation. This makes it difficult for developers to
validate that new changes to don't have problems.

Most of the warnings and errors are fixed with this change.

Change-Id: Ifb9edffce66dde27fbe72bb1ce1b997b041786ae

openstack/oslo.cache,openstack/oslo.cache,citrix-openstack-build/oslo.cache