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