Merge "Revamp documentation, add module references"

6 files changed, 226 insertions, 22 deletions

diff --git a/.gitignore b/.gitignore
index 2829f92..f196e15 100644
--- a/.gitignore
+++ b/.gitignore
@@ -7,6 +7,7 @@ cover
 .testrepository
 .venv
 doc/build
+doc/source/ref
 subunit.log
 AUTHORS
 ChangeLog
diff --git a/doc/ext/gen_ref.py b/doc/ext/gen_ref.py
new file mode 100644
index 0000000..f3ea677
--- /dev/null
+++ b/doc/ext/gen_ref.py
@@ -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"])
diff --git a/doc/source/api.rst b/doc/source/api.rst
new file mode 100644
index 0000000..85769c6
--- /dev/null
+++ b/doc/source/api.rst
@@ -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
diff --git a/doc/source/conf.py b/doc/source/conf.py
index 185f758..7124622 100644
--- a/doc/source/conf.py
+++ b/doc/source/conf.py
@@ -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
diff --git a/doc/source/index.rst b/doc/source/index.rst
index a89eab5..fc18b16 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -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`
diff --git a/doc/source/shell.rst b/doc/source/shell.rst
new file mode 100644
index 0000000..1c10c48
--- /dev/null
+++ b/doc/source/shell.rst
@@ -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