Update documentation

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

README.rst

@@ -1,16 +1,59 @@
-========
 grafyaml
-========
+--------
 
-Grafyaml takes simple descriptions of Grafana dashboards in YAML format, and
-uses them to configure Grafana.
+At a glance
++++++++++++
 
 * Free software: Apache license
 * Documentation: http://docs.openstack.org/infra/grafyaml/
 * Source: http://git.openstack.org/cgit/openstack-infra/grafyaml
 * Bugs: https://storyboard.openstack.org/#!/project/818
 
-Features
---------
+Overview
+++++++++
 
-* TODO
+``grafyaml`` takes descriptions of `Grafana <https://grafana.com/>`__
+dashboards in YAML format, and uses them to produce JSON formatted
+output suitable for direct import into Grafana.
+
+The tool uses the `Voluptuous
+<https://github.com/alecthomas/voluptuous>`__ data validation library
+to ensure the input produces a valid dashboard.  Along with
+validation, users receive the benefits of YAML markup such as comments
+and clearer type support.
+
+For example, here is a minimal dashboard specification
+
+.. code-block:: yaml
+
+  dashboard:
+    time:
+      from: "2018-02-07T08:42:27.000Z"
+      to: "2018-02-07T13:48:32.000Z"
+    templating:
+      - name: hostname
+        type: query
+        datasource: graphite
+        query: node*
+        refresh: true
+    title: My great dashboard
+    rows:
+      - title: CPU Usage
+        height: 250px
+        panels:
+            - title: CPU Usage for $hostname
+              type: graph
+              datasource: graphite
+              targets:
+                - target: $hostname.Cpu.cpu_prct_used
+
+
+``grafyaml`` can be very useful in continuous-integration
+environments.  Users can specify their dashboards via a normal review
+process and tests can validate their correctness.
+
+A large number of examples are available in the OpenStack
+`project-config
+<https://git.openstack.org/cgit/openstack-infra/project-config/tree/grafana>`__
+repository, which are used to create dashboards on
+`<http://grafana.openstack.org>`__.

doc/source/conf.py

@@ -21,7 +21,7 @@ sys.path.insert(0, os.path.abspath('../..'))
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
 extensions = [
     'sphinx.ext.autodoc',
-    'oslosphinx'
+    'openstackdocstheme',
 ]
 
 # Also document __init__
@@ -47,6 +47,9 @@ add_module_names = True
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = 'sphinx'
 
+# openstackdocstheme options
+repository_name = 'openstack-infra/grafyaml'
+
 # -- Options for HTML output --------------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  Major themes that come with
@@ -55,6 +58,8 @@ pygments_style = 'sphinx'
 # html_theme = '_theme'
 # html_static_path = ['static']
 
+html_theme = 'openstackdocs'
+
 # Output file base name for HTML help builder.
 htmlhelp_basename = '%sdoc' % project
 

doc/source/index.rst

@@ -4,7 +4,7 @@ Welcome to grafyaml's documentation!
 .. include:: ../../README.rst
 
 Contents
-========
+++++++++
 
 .. toctree::
    :maxdepth: 2
@@ -16,7 +16,7 @@ Contents
    api
 
 Indices and tables
-==================
+++++++++++++++++++
 
 * :ref:`genindex`
 * :ref:`modindex`

requirements.txt

@@ -1,5 +1,5 @@
 dogpile.cache
-pbr>=1.6
+pbr!=2.1.0,>=2.0.0
 python-slugify
 PyYAML>=3.1.0
 requests

test-requirements.txt

@@ -7,9 +7,9 @@ hacking<0.11,>=0.10.0
 coverage>=3.6
 python-subunit>=0.0.18
 requests-mock>=0.6.0
-sphinx>=1.1.2,!=1.2.0,!=1.3b1,<1.3
+sphinx>=1.6.2
 mock>=1.2
-oslosphinx>=2.2.0  # Apache-2.0
+openstackdocstheme>=1.11.0 # Apache-2.0
 oslotest>=1.2.0  # Apache-2.0
 testrepository>=0.0.18
 testscenarios>=0.4