Add API Reference for Watcher

This patch set adds API Reference along with some
fixes to documentation. It partially fixes bug #1757423.

Change-Id: I107b4fd5daf40aad63fc13864debbbbc82a9826c

tox.ini

@@ -38,6 +38,14 @@ commands =
     doc8 doc/source/ CONTRIBUTING.rst HACKING.rst README.rst
     python setup.py build_sphinx
 
+[testenv:api-ref]
+# This environment is called from CI scripts to test and publish
+# the API Ref to developer.openstack.org.
+whitelist_externals = bash
+commands =
+  bash -c 'rm -rf api-ref/build'
+  sphinx-build -W -b html -d api-ref/build/doctrees api-ref/source api-ref/build/html
+
 [testenv:debug]
 commands = oslo_debug_helper -t watcher/tests {posargs}