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
This commit is contained in:
Ian Wienand 2018-06-04 20:42:30 +10:00
parent f02241f8de
commit 59247628c4
5 changed files with 61 additions and 13 deletions

View File

@ -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>`__.

View File

@ -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

View File

@ -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`

View File

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

View File

@ -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