Docs in cinderlcient were never actually updated.

Not only were the docs and release info here not being
maintainted properly, but the examples that were given were
not correct.

This change is an attempt to set us on the right path going
forward and includes info on how to import the API and history
info for the upcoming release/push to PyPi.

Fixes bug: 1156994

Change-Id: I169b1c01380ef653a6a25eb8946b9a06d6419e62

11 files changed, 54 insertions, 496 deletions

diff --git a/doc/source/api.rst b/doc/source/api.rst
deleted file mode 100644
index 116fba4..0000000
--- a/doc/source/api.rst
+++ /dev/null
@@ -1,67 +0,0 @@
-The :mod:`cinderclient` Python API
-==================================
-
-.. module:: cinderclient
-   :synopsis: A client for the OpenStack Cinder API.
-
-.. currentmodule:: cinderclient
-
-Usage
------
-
-First create an instance of :class:`OpenStack` with your credentials::
-
-    >>> from cinderclient import OpenStack
-    >>> cinder = OpenStack(USERNAME, PASSWORD, AUTH_URL)
-
-Then call methods on the :class:`OpenStack` object:
-
-.. class:: OpenStack
-
-    .. attribute:: backup_schedules
-
-        A :class:`BackupScheduleManager` -- manage automatic backup images.
-
-    .. attribute:: flavors
-
-        A :class:`FlavorManager` -- query available "flavors" (hardware
-        configurations).
-
-    .. attribute:: images
-
-        An :class:`ImageManager` -- query and create server disk images.
-
-    .. attribute:: ipgroups
-
-        A :class:`IPGroupManager` -- manage shared public IP addresses.
-
-    .. attribute:: servers
-
-        A :class:`ServerManager` -- start, stop, and manage virtual machines.
-
-    .. automethod:: authenticate
-
-For example::
-
-    >>> cinder.servers.list()
-    [<Server: buildslave-ubuntu-9.10>]
-
-    >>> cinder.flavors.list()
-    [<Flavor: 256 server>,
-     <Flavor: 512 server>,
-     <Flavor: 1GB server>,
-     <Flavor: 2GB server>,
-     <Flavor: 4GB server>,
-     <Flavor: 8GB server>,
-     <Flavor: 15.5GB server>]
-
-    >>> fl = cinder.flavors.find(ram=512)
-    >>> cinder.servers.create("my-server", flavor=fl)
-    <Server: my-server>
-
-For more information, see the reference:
-
-.. toctree::
-   :maxdepth: 2
-
-   ref/index
diff --git a/doc/source/index.rst b/doc/source/index.rst
index f199663..1ebe9a9 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -1,34 +1,52 @@
-Python bindings to the OpenStack Cinder API
-==================================================
-
-This is a client for OpenStack Cinder API. There's :doc:`a Python API
-<api>` (the :mod:`cinderclient` module), and a :doc:`command-line script
-<shell>` (installed as :program:`cinder`). Each implements the entire
-OpenStack Cinder API.
-
-Contents:
-
-.. toctree::
-   :maxdepth: 2
-
-   shell
-   api
-   ref/index
-   releases
-
-Contributing
-============
-
-Development takes place `on GitHub`__; please file bugs/pull requests there.
-
-__ https://github.com/openstack/python-cinderclient
-
-Run tests with ``python setup.py test``.
-
-Indices and tables
-==================
-
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
-
+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::
+
+    >>> from cinderclient import client
+    >>> cinder = client.Client('1', $OS_USER_NAME, $OS_PASSWORD, $OS_TENANT_NAME, $OS_AUTH_URL)
+    >>> cinder.volumes.list()
+    []
+    >>> myvol = cinder.volumes.create(display_name="test-vol", size=1)
+    >>> myvol.id
+    ce06d0a8-5c1b-4e2c-81d2-39eca6bbfb70
+    >>> cinder.volumes.list()
+    [<Volume: ce06d0a8-5c1b-4e2c-81d2-39eca6bbfb70>]
+    >>>myvol.delete
+
+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::
+
+    export OS_USERNAME=user
+    export OS_PASSWORD=pass
+    export OS_TENANT_ID=b363706f891f48019483f8bd6503c54b
+    export OS_AUTH_URL=http://auth.example.com:5000/v2.0
+
+Once you've configured your authentication parameters, you can run ``cinder help`` to see a complete listing of available commands.
+
+
+Release Notes
+=============
+
+1.1.0
+-----
+
+* Added support for V2 Cinder API
+* Corected upload-volume-to-image help messaging
+* Align handling of metadata args for all methods
+* Update OSLO version
+* Correct parsing of volume metadata
+* Enable force delete of volumes and snapshots in error state
+* Implement clone volume API call
+* Add list-extensions call to cinderclient
+* Add bootable column to list output
+* Add retries to cinderclient operations
+* Add Type/Extra-Specs support
+* Add volume and snapshot rename commands
+.. _1155655: http://bugs.launchpad.net/python-cinderclient/+bug/1155655
+.. _1130730: http://bugs.launchpad.net/python-cinderclient/+bug/1130730
+.. _1068521: http://bugs.launchpad.net/python-cinderclient/+bug/1068521
+.. _1052161: http://bugs.launchpad.net/python-cinderclient/+bug/1052161
+.. _1071003: http://bugs.launchpad.net/python-cinderclient/+bug/1071003
+.. _1065275: http://bugs.launchpad.net/python-cinderclient/+bug/1065275
+.. _1053432: http://bugs.launchpad.net/python-cinderclient/+bug/1053432
diff --git a/doc/source/ref/backup_schedules.rst b/doc/source/ref/backup_schedules.rst
deleted file mode 100644
index cbd69e3..0000000
--- a/doc/source/ref/backup_schedules.rst
+++ /dev/null
@@ -1,60 +0,0 @@
-Backup schedules
-================
-
-.. currentmodule:: cinderclient
-
-Rackspace allows scheduling of weekly and/or daily backups for virtual
-servers. You can access these backup schedules either off the API object as
-:attr:`OpenStack.backup_schedules`, or directly off a particular
-:class:`Server` instance as :attr:`Server.backup_schedule`.
-
-Classes
--------
-
-.. autoclass:: BackupScheduleManager
-   :members: create, delete, update, get
-   
-.. autoclass:: BackupSchedule
-   :members: update, delete
-   
-   .. attribute:: enabled
-   
-        Is this backup enabled? (boolean)
-        
-   .. attribute:: weekly
-   
-        The day of week upon which to perform a weekly backup.
-   
-   .. attribute:: daily
-   
-        The daily time period during which to perform a daily backup.
-        
-Constants
----------
-
-Constants for selecting weekly backup days:
-
-    .. data:: BACKUP_WEEKLY_DISABLED
-    .. data:: BACKUP_WEEKLY_SUNDAY
-    .. data:: BACKUP_WEEKLY_MONDAY  
-    .. data:: BACKUP_WEEKLY_TUESDAY 
-    .. data:: BACKUP_WEEKLY_WEDNESDA
-    .. data:: BACKUP_WEEKLY_THURSDAY
-    .. data:: BACKUP_WEEKLY_FRIDAY  
-    .. data:: BACKUP_WEEKLY_SATURDAY
-    
-Constants for selecting hourly backup windows:
-
-    .. data:: BACKUP_DAILY_DISABLED   
-    .. data:: BACKUP_DAILY_H_0000_0200
-    .. data:: BACKUP_DAILY_H_0200_0400
-    .. data:: BACKUP_DAILY_H_0400_0600
-    .. data:: BACKUP_DAILY_H_0600_0800
-    .. data:: BACKUP_DAILY_H_0800_1000
-    .. data:: BACKUP_DAILY_H_1000_1200
-    .. data:: BACKUP_DAILY_H_1200_1400
-    .. data:: BACKUP_DAILY_H_1400_1600
-    .. data:: BACKUP_DAILY_H_1600_1800
-    .. data:: BACKUP_DAILY_H_1800_2000
-    .. data:: BACKUP_DAILY_H_2000_2200
-    .. data:: BACKUP_DAILY_H_2200_0000
diff --git a/doc/source/ref/exceptions.rst b/doc/source/ref/exceptions.rst
deleted file mode 100644
index 23618e3..0000000
--- a/doc/source/ref/exceptions.rst
+++ /dev/null
@@ -1,14 +0,0 @@
-Exceptions
-==========
-
-.. currentmodule:: cinderclient
-
-Exceptions
-----------
-
-Exceptions that the API might throw:
-
-.. automodule:: cinderclient
-   :members: OpenStackException, BadRequest, Unauthorized, Forbidden, 
-             NotFound, OverLimit
-
diff --git a/doc/source/ref/flavors.rst b/doc/source/ref/flavors.rst
deleted file mode 100644
index 12b396a..0000000
--- a/doc/source/ref/flavors.rst
+++ /dev/null
@@ -1,35 +0,0 @@
-Flavors
-=======
-
-From Rackspace's API documentation:
-
-    A flavor is an available hardware configuration for a server. Each flavor
-    has a unique combination of disk space, memory capacity and priority for
-    CPU time.
-    
-Classes
--------
-
-.. currentmodule:: cinderclient
-
-.. autoclass:: FlavorManager
-   :members: get, list, find, findall
-
-.. autoclass:: Flavor
-   :members:
-   
-   .. attribute:: id
-   
-       This flavor's ID.
-       
-   .. attribute:: name
-   
-       A human-readable name for this flavor.
-   
-   .. attribute:: ram
-   
-       The amount of RAM this flavor has, in MB.
-       
-   .. attribute:: disk
-   
-       The amount of disk space this flavor has, in MB
diff --git a/doc/source/ref/images.rst b/doc/source/ref/images.rst
deleted file mode 100644
index 6ba6c24..0000000
--- a/doc/source/ref/images.rst
+++ /dev/null
@@ -1,54 +0,0 @@
-Images
-======
-
-.. currentmodule:: cinderclient
-
-An "image" is a snapshot from which you can create new server instances.
-
-From Rackspace's own API documentation:
-
-    An image is a collection of files used to create or rebuild a server.
-    Rackspace provides a number of pre-built OS images by default. You may
-    also create custom images from cloud servers you have launched. These
-    custom images are useful for backup purposes or for producing "gold"
-    server images if you plan to deploy a particular server configuration
-    frequently.
-
-Classes
--------
-
-.. autoclass:: ImageManager
-   :members: get, list, find, findall, create, delete
-
-.. autoclass:: Image
-   :members: delete
-      
-   .. attribute:: id
-   
-       This image's ID.
-       
-   .. attribute:: name
-   
-       This image's name.
-       
-   .. attribute:: created
-   
-       The date/time this image was created.
-       
-   .. attribute:: updated
-   
-       The date/time this instance was updated.
-       
-   .. attribute:: status
-   
-       The status of this image (usually ``"SAVING"`` or ``ACTIVE``).
-       
-   .. attribute:: progress
-   
-       During saving of an image this'll be set to something between
-       0 and 100, representing a rough percentage done.
-       
-   .. attribute:: serverId
-   
-       If this image was created from a :class:`Server` then this attribute
-       will be set to the ID of the server whence this image came.
diff --git a/doc/source/ref/index.rst b/doc/source/ref/index.rst
deleted file mode 100644
index c1fe136..0000000
--- a/doc/source/ref/index.rst
+++ /dev/null
@@ -1,12 +0,0 @@
-API Reference
-=============
-
-.. toctree::
-   :maxdepth: 1
-   
-   backup_schedules
-   exceptions
-   flavors
-   images
-   ipgroups
-   servers
\ No newline at end of file
diff --git a/doc/source/ref/ipgroups.rst b/doc/source/ref/ipgroups.rst
deleted file mode 100644
index 4c29f2e..0000000
--- a/doc/source/ref/ipgroups.rst
+++ /dev/null
@@ -1,46 +0,0 @@
-Shared IP addresses
-===================
-
-From the Rackspace API guide:
-
-    Public IP addresses can be shared across multiple servers for use in
-    various high availability scenarios. When an IP address is shared to
-    another server, the cloud network restrictions are modified to allow each
-    server to listen to and respond on that IP address (you may optionally
-    specify that the target server network configuration be modified). Shared
-    IP addresses can be used with many standard heartbeat facilities (e.g.
-    ``keepalived``) that monitor for failure and manage IP failover.
-
-    A shared IP group is a collection of servers that can share IPs with other
-    members of the group. Any server in a group can share one or more public
-    IPs with any other server in the group. With the exception of the first
-    server in a shared IP group, servers must be launched into shared IP
-    groups. A server may only be a member of one shared IP group.
-
-.. seealso::
-
-    Use :meth:`Server.share_ip` and `Server.unshare_ip` to share and unshare
-    IPs in a group.
-
-Classes
--------
-
-.. currentmodule:: cinderclient
-
-.. autoclass:: IPGroupManager
-   :members: get, list, find, findall, create, delete
-   
-.. autoclass:: IPGroup
-   :members: delete
-   
-   .. attribute:: id
-   
-        Shared group ID.
-   
-   .. attribute:: name
-   
-        Name of the group.
-   
-   .. attribute:: servers
-   
-        A list of server IDs in this group.
diff --git a/doc/source/ref/servers.rst b/doc/source/ref/servers.rst
deleted file mode 100644
index b02fca5..0000000
--- a/doc/source/ref/servers.rst
+++ /dev/null
@@ -1,73 +0,0 @@
-Servers
-=======
-
-A virtual machine instance.
-
-Classes
--------
-
-.. currentmodule:: cinderclient
-
-.. autoclass:: ServerManager
-   :members: get, list, find, findall, create, update, delete, share_ip,
-             unshare_ip, reboot, rebuild, resize, confirm_resize,
-             revert_resize
-
-.. autoclass:: Server
-   :members: update, delete, share_ip, unshare_ip, reboot, rebuild, resize,
-             confirm_resize, revert_resize
-
-   .. attribute:: id
-
-        This server's ID.
-
-   .. attribute:: name
-
-        The name you gave the server when you booted it.
-
-   .. attribute:: imageId
-
-        The :class:`Image` this server was booted with.
-
-   .. attribute:: flavorId
-
-        This server's current :class:`Flavor`.
-
-   .. attribute:: hostId
-
-        Rackspace doesn't document this value. It appears to be SHA1 hash.
-
-   .. attribute:: status
-
-        The server's status (``BOOTING``, ``ACTIVE``, etc).
-
-   .. attribute:: progress
-
-        When booting, resizing, updating, etc., this will be set to a
-        value between 0 and 100 giving a rough estimate of the progress
-        of the current operation.
-
-   .. attribute:: addresses
-
-        The public and private IP addresses of this server. This'll be a dict
-        of the form::
-
-            {
-              "public" : ["67.23.10.138"],
-              "private" : ["10.176.42.19"]
-            }
-
-        You *can* get more than one public/private IP provisioned, but not
-        directly from the API; you'll need to open a support ticket.
-
-   .. attribute:: metadata
-
-        The metadata dict you gave when creating the server.
-
-Constants
----------
-
-Reboot types:
-
-.. data:: REBOOT_SOFT
-.. data:: REBOOT_HARD
diff --git a/doc/source/releases.rst b/doc/source/releases.rst
deleted file mode 100644
index 783b1ca..0000000
--- a/doc/source/releases.rst
+++ /dev/null
@@ -1,99 +0,0 @@
-=============
-Release notes
-=============
-
-2.5.8 (July 11, 2011)
-=====================
-* returns all public/private ips, not just first one
-* better 'cinder list' search options
-
-2.5.7 - 2.5.6 = minor tweaks
-
-2.5.5 (June 21, 2011)
-=====================
-* zone-boot min/max instance count added thanks to comstud
-* create for user added thanks to cerberus
-* fixed tests
-
-2.5.3 (June 15, 2011)
-=====================
-* ProjectID can be None for backwards compatability.
-* README/docs updated for projectId thanks to usrleon
-
-2.5.1 (June 10, 2011)
-=====================
-* ProjectID now part of authentication
-
-2.5.0 (June 3, 2011)
-=================
-
-* better logging thanks to GridDynamics
-
-2.4.4 (June 1, 2011)
-=================
-
-* added support for GET /servers with reservation_id (and /servers/detail)
-
-2.4.3 (May 27, 2011)
-=================
-
-* added support for POST /zones/select (client only, not cmdline)
-
-2.4 (March 7, 2011)
-=================
-
-* added Jacob Kaplan-Moss copyright notices to older/untouched files.
-
-
-2.3 (March 2, 2011)
-=================
-
-* package renamed to python-cinderclient. Module to cinderclient
-
-
-2.2 (March 1, 2011)
-=================
-
-* removed some license/copywrite notices from source that wasn't
-  significantly changed.
-
-
-2.1 (Feb 28, 2011)
-=================
-
-* shell renamed to cinder from cindertools
-
-* license changed from BSD to Apache
-
-2.0 (Feb 7, 2011)
-=================
-
-* Forked from https://github.com/jacobian/python-cloudservers
-
-* Rebranded to python-cindertools
-
-* Auth URL support
-
-* New OpenStack specific commands added (pause, suspend, etc)
-
-1.2 (August 15, 2010)
-=====================
-
-* Support for Python 2.4 - 2.7.
-
-* Improved output of :program:`cloudservers ipgroup-list`.
-
-* Made ``cloudservers boot --ipgroup <name>`` work (as well as ``--ipgroup
-  <id>``).
-
-1.1 (May 6, 2010)
-=================
-
-* Added a ``--files`` option to :program:`cloudservers boot` supporting
-  the upload of (up to five) files at boot time.
-
-* Added a ``--key`` option to :program:`cloudservers boot` to key the server
-  with an SSH public key at boot time. This is just a shortcut for ``--files``,
-  but it's a useful shortcut.
-
-* Changed the default server image to Ubuntu 10.04 LTS.
diff --git a/doc/source/shell.rst b/doc/source/shell.rst
index 7ded87f..96b4f4f 100644
--- a/doc/source/shell.rst
+++ b/doc/source/shell.rst
@@ -39,9 +39,9 @@ For example, in Bash you'd use::
     export OS_TENANT_NAME=myproject
     export OS_AUTH_URL=http://...
     export OS_VOLUME_API_VERSION=1
-    
+
 From there, all shell commands take the form::
-    
+
     cinder <command> [arguments...]
 
 Run :program:`cinder help` to get a full list of all possible commands,