Revamp documentation, add module references
Documentation is modeled after python-novaclient docs. (http://docs.openstack.org/developer/python-novaclient/) Built preview for reviewers: https://nsaje.fedorapeople.org/python-ceilometerclient/ Change-Id: I61e9d6593e4a1aea5cf018081416d4be3a9372ac
This commit is contained in:
Nejc Saje
1
.gitignore
vendored
1
.gitignore
vendored
@@ -7,6 +7,7 @@ cover
|
||||
.testrepository
|
||||
.venv
|
||||
doc/build
|
||||
doc/source/ref
|
||||
subunit.log
|
||||
AUTHORS
|
||||
ChangeLog
|
||||
|
||||
59
doc/ext/gen_ref.py
Normal file
59
doc/ext/gen_ref.py
Normal file
@@ -0,0 +1,59 @@
|
||||
# -*- coding: utf-8 -*-
|
||||
# Licensed under the Apache License, Version 2.0 (the "License"); you may
|
||||
# not use this file except in compliance with the License. You may obtain
|
||||
# a copy of the License at
|
||||
#
|
||||
# http://www.apache.org/licenses/LICENSE-2.0
|
||||
#
|
||||
# Unless required by applicable law or agreed to in writing, software
|
||||
# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
|
||||
# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
|
||||
# License for the specific language governing permissions and limitations
|
||||
# under the License.
|
||||
|
||||
import os
|
||||
import sys
|
||||
|
||||
BASE_DIR = os.path.dirname(os.path.abspath(__file__))
|
||||
ROOT = os.path.abspath(os.path.join(BASE_DIR, "..", "..", ".."))
|
||||
|
||||
sys.path.insert(0, ROOT)
|
||||
sys.path.insert(0, BASE_DIR)
|
||||
|
||||
|
||||
def gen_ref(ver, title, names):
|
||||
refdir = os.path.join(BASE_DIR, "ref")
|
||||
pkg = "ceilometerclient"
|
||||
if ver:
|
||||
pkg = "%s.%s" % (pkg, ver)
|
||||
refdir = os.path.join(refdir, ver)
|
||||
if not os.path.exists(refdir):
|
||||
os.makedirs(refdir)
|
||||
idxpath = os.path.join(refdir, "index.rst")
|
||||
with open(idxpath, "w") as idx:
|
||||
idx.write(("%(title)s\n"
|
||||
"%(signs)s\n"
|
||||
"\n"
|
||||
".. toctree::\n"
|
||||
" :maxdepth: 1\n"
|
||||
"\n") % {"title": title, "signs": "=" * len(title)})
|
||||
for name in names:
|
||||
idx.write(" %s\n" % name)
|
||||
rstpath = os.path.join(refdir, "%s.rst" % name)
|
||||
with open(rstpath, "w") as rst:
|
||||
rst.write(("%(title)s\n"
|
||||
"%(signs)s\n"
|
||||
"\n"
|
||||
".. automodule:: %(pkg)s.%(name)s\n"
|
||||
" :members:\n"
|
||||
" :undoc-members:\n"
|
||||
" :show-inheritance:\n"
|
||||
" :noindex:\n")
|
||||
% {"title": name.capitalize(),
|
||||
"signs": "=" * len(name),
|
||||
"pkg": pkg, "name": name})
|
||||
|
||||
gen_ref("", "Client Reference", ["client", "exc"])
|
||||
gen_ref("v1", "Version 1 API Reference",
|
||||
["stacks", "resources", "events", "actions",
|
||||
"software_configs", "software_deployments"])
|
||||
48
doc/source/api.rst
Normal file
48
doc/source/api.rst
Normal file
@@ -0,0 +1,48 @@
|
||||
The :mod:`ceilometerclient` Python API
|
||||
======================================
|
||||
|
||||
.. module:: ceilometerclient
|
||||
:synopsis: A client for the OpenStack Ceilometer API.
|
||||
|
||||
.. currentmodule:: ceilometerclient
|
||||
|
||||
Usage
|
||||
-----
|
||||
|
||||
First create a client instance with your credentials::
|
||||
|
||||
>>> import ceilometerclient.client
|
||||
>>> cclient = ceilometerclient.client.get_client(VERSION, username=USERNAME, password=PASSWORD, tenant_name=PROJECT_NAME, auth_url=AUTH_URL)
|
||||
|
||||
Here ``VERSION`` can be: ``1`` and ``2``.
|
||||
|
||||
Then call methods on its managers::
|
||||
|
||||
>>> cclient.meters.list()
|
||||
[<Meter ...>, ...]
|
||||
|
||||
>>> cclient.samples.list()
|
||||
[<Sample ...>, ...]
|
||||
|
||||
V2 client tips
|
||||
++++++++++++++
|
||||
|
||||
Use queries to narrow your search (more info at `Ceilometer V2 API reference`__)::
|
||||
|
||||
>>> query = [dict(field='resource_id', op='eq', value='5a301761-f78b-46e2-8900-8b4f6fe6675a')]
|
||||
>>> ceilometer.samples.list(meter_name='cpu_util', limit=10, q=query)
|
||||
[<Sample ...>, ...]
|
||||
|
||||
__ http://docs.openstack.org/developer/ceilometer/webapi/v2.html#Query
|
||||
|
||||
Reference
|
||||
---------
|
||||
|
||||
For more information, see the reference:
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
ref/index
|
||||
ref/v1/index
|
||||
ref/v2/index
|
||||
@@ -1,7 +1,27 @@
|
||||
# Licensed under the Apache License, Version 2.0 (the "License"); you may
|
||||
# not use this file except in compliance with the License. You may obtain
|
||||
# a copy of the License at
|
||||
#
|
||||
# http://www.apache.org/licenses/LICENSE-2.0
|
||||
#
|
||||
# Unless required by applicable law or agreed to in writing, software
|
||||
# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
|
||||
# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
|
||||
# License for the specific language governing permissions and limitations
|
||||
# under the License.
|
||||
|
||||
import os
|
||||
execfile(os.path.join("..", "ext", "gen_ref.py"))
|
||||
|
||||
project = 'python-ceilometerclient'
|
||||
|
||||
gen_ref("", "Client Reference", ["client", "exc"])
|
||||
gen_ref("v1", "Version 1 API Reference",
|
||||
["meters"])
|
||||
gen_ref("v2", "Version 2 API Reference",
|
||||
["meters", "samples", "statistics", "resources", "query", "alarms",
|
||||
"events", "event_types", "traits", "trait_descriptions"])
|
||||
|
||||
# -- General configuration ----------------------------------------------------
|
||||
|
||||
# Add any Sphinx extension module names here, as strings. They can be
|
||||
|
||||
@@ -1,32 +1,47 @@
|
||||
Python API
|
||||
==========
|
||||
In order to use the python api directly, you must first obtain an auth token and identify which endpoint you wish to speak to. Once you have done so, you can use the API like so::
|
||||
Python bindings to the OpenStack Ceilometer API
|
||||
==================================================
|
||||
|
||||
>>> from ceilometerclient import Client
|
||||
>>> ceilometer = Client('1', endpoint=OS_IMAGE_ENDPOINT, token=OS_AUTH_TOKEN)
|
||||
...
|
||||
This is a client for OpenStack Ceilometer API. There's :doc:`a Python API
|
||||
<api>` (the :mod:`ceilometerclient` module), and a :doc:`command-line script
|
||||
<shell>` (installed as :program:`ceilometer`). Each implements the entire
|
||||
OpenStack Ceilometer API.
|
||||
|
||||
.. seealso::
|
||||
|
||||
Command-line Tool
|
||||
=================
|
||||
In order to use the CLI, you must provide your OpenStack username, password, tenant, and auth endpoint. Use the corresponding configuration options (``--os-username``, ``--os-password``, ``--os-tenant-id``, and ``--os-auth-url``) or set them in environment variables::
|
||||
You may want to read the `OpenStack Ceilometer Developer Guide`__ -- the overview, at
|
||||
least -- to get an idea of the concepts. By understanding the concepts
|
||||
this library should make more sense.
|
||||
|
||||
export OS_USERNAME=user
|
||||
export OS_PASSWORD=pass
|
||||
export OS_TENANT_ID=b363706f891f48019483f8bd6503c54b
|
||||
export OS_AUTH_URL=http://auth.example.com:5000/v2.0
|
||||
__ http://docs.openstack.org/developer/ceilometer/
|
||||
|
||||
The command line tool will attempt to reauthenticate using your provided credentials for every request. You can override this behavior by manually supplying an auth token using ``--os-image-url`` and ``--os-auth-token``. You can alternatively set these environment variables::
|
||||
Contents:
|
||||
|
||||
export OS_IMAGE_URL=http://ceilometer.example.org:8004/
|
||||
export OS_AUTH_TOKEN=3bcc3d3a03f44e3d8377f9247b0ad155
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
Once you've configured your authentication parameters, you can run ``ceilometer help`` to see a complete listing of available commands.
|
||||
shell
|
||||
api
|
||||
ref/index
|
||||
ref/v1/index
|
||||
ref/v2/index
|
||||
releases
|
||||
|
||||
Contributing
|
||||
============
|
||||
|
||||
Release Notes
|
||||
=============
|
||||
Code is hosted at `git.openstack.org`_. Submit bugs to the Ceilometer project on
|
||||
`Launchpad`_. Submit code to the openstack/python-ceilometerclient project using
|
||||
`Gerrit`_.
|
||||
|
||||
0.1.0
|
||||
-----
|
||||
* Initial release
|
||||
.. _git.openstack.org: https://git.openstack.org/cgit/openstack/python-ceilometerclient
|
||||
.. _Launchpad: https://launchpad.net/ceilometer
|
||||
.. _Gerrit: http://wiki.openstack.org/GerritWorkflow
|
||||
|
||||
Run tests with ``python setup.py test``.
|
||||
|
||||
Indices and tables
|
||||
==================
|
||||
|
||||
* :ref:`genindex`
|
||||
* :ref:`modindex`
|
||||
* :ref:`search`
|
||||
|
||||
61
doc/source/shell.rst
Normal file
61
doc/source/shell.rst
Normal file
@@ -0,0 +1,61 @@
|
||||
The :program:`ceilometer` shell utility
|
||||
=========================================
|
||||
|
||||
.. program:: ceilometer
|
||||
.. highlight:: bash
|
||||
|
||||
The :program:`ceilometer` shell utility interacts with OpenStack Ceilometer API
|
||||
from the command line. It supports the entirety of the OpenStack Ceilometer API.
|
||||
|
||||
You'll need to provide :program:`ceilometer` with your OpenStack credentials.
|
||||
You can do this with the :option:`--os-username`, :option:`--os-password`,
|
||||
:option:`--os-tenant-id` and :option:`--os-auth-url` options, but it's easier to
|
||||
just set them as environment variables:
|
||||
|
||||
.. envvar:: OS_USERNAME
|
||||
|
||||
Your OpenStack username.
|
||||
|
||||
.. envvar:: OS_PASSWORD
|
||||
|
||||
Your password.
|
||||
|
||||
.. envvar:: OS_TENANT_NAME
|
||||
|
||||
Project to work on.
|
||||
|
||||
.. envvar:: OS_AUTH_URL
|
||||
|
||||
The OpenStack auth server URL (keystone).
|
||||
|
||||
For example, in Bash you would use::
|
||||
|
||||
export OS_USERNAME=user
|
||||
export OS_PASSWORD=pass
|
||||
export OS_TENANT_NAME=myproject
|
||||
export OS_AUTH_URL=http://auth.example.com:5000/v2.0
|
||||
|
||||
The command line tool will attempt to reauthenticate using your provided credentials
|
||||
for every request. You can override this behavior by manually supplying an auth
|
||||
token using :option:`--os-ceilometer-url` and :option:`--os-auth-token`. You can alternatively
|
||||
set these environment variables::
|
||||
|
||||
export OS_CEILOMETER_URL=http://ceilometer.example.org:8777
|
||||
export OS_AUTH_TOKEN=3bcc3d3a03f44e3d8377f9247b0ad155
|
||||
|
||||
From there, all shell commands take the form::
|
||||
|
||||
ceilometer <command> [arguments...]
|
||||
|
||||
Run :program:`ceilometer help` to get a full list of all possible commands,
|
||||
and run :program:`ceilometer help <command>` to get detailed help for that
|
||||
command.
|
||||
|
||||
V2 client tips
|
||||
++++++++++++++
|
||||
|
||||
Use queries to narrow your search (more info at `Ceilometer V2 API reference`__)::
|
||||
|
||||
ceilometer sample-list --meter cpu_util --query 'resource_id=5a301761-f78b-46e2-8900-8b4f6fe6675a' --limit 10
|
||||
|
||||
__ http://docs.openstack.org/developer/ceilometer/webapi/v2.html#Query
|
||||
Reference in New Issue
Block a user