From 59247628c42576c2962b8c9aabb03ff1575055e1 Mon Sep 17 00:00:00 2001
From: Ian Wienand <iwienand@redhat.com>
Date: Mon, 4 Jun 2018 20:42:30 +1000
Subject: [PATCH] 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            | 57 +++++++++++++++++++++++++++++++++++++------
 doc/source/conf.py    |  7 +++++-
 doc/source/index.rst  |  4 +--
 requirements.txt      |  2 +-
 test-requirements.txt |  4 +--
 5 files changed, 61 insertions(+), 13 deletions(-)

diff --git a/README.rst b/README.rst
index 777bb9e..85e294a 100644
--- a/README.rst
+++ b/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>`__.
diff --git a/doc/source/conf.py b/doc/source/conf.py
index 6f4cde6..6f76fb4 100755
--- a/doc/source/conf.py
+++ b/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
 
diff --git a/doc/source/index.rst b/doc/source/index.rst
index b62586e..97b9208 100644
--- a/doc/source/index.rst
+++ b/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`
diff --git a/requirements.txt b/requirements.txt
index 23568de..23564cc 100644
--- a/requirements.txt
+++ b/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
diff --git a/test-requirements.txt b/test-requirements.txt
index 2551232..e7171d9 100644
--- a/test-requirements.txt
+++ b/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