Add some expanded documentation on what grafyaml actually does to
README.rst
While we're here, fix this up to use openstackdocs theme and the
latest sphinx, as it was producing a bunch of warnings.
Change-Id: I570b44cb911cd48d53d62234426edeabb22b1469