move existing content into the new standard structure

This patch rearranges and reformats existing content.

It replaces the home-grown autodoc feature with the one built into pbr,
for consistency with other OpenStack projects.

It depends on the doc-migration spec and a pbr feature to allow us to
specify where the autodoc content should go in the source tree during
the build.

Change-Id: I8d2bb11b5ef3e46fcd22c8bed8f84060d8ab6f03
Depends-On: Ia750cb049c0f53a234ea70ce1f2bbbb7a2aa9454
Depends-On: I2bd5652bb59cbd9c939931ba2e7db1b37d2b30bb
Signed-off-by: Doug Hellmann <doug@doughellmann.com>

doc/source/reference/api/index.rst

@@ -0,0 +1,8 @@
+======================
+ Python API Reference
+======================
+
+.. toctree::
+   :maxdepth: 2
+
+   autoindex

doc/source/reference/apiv2.rst

@@ -0,0 +1,89 @@
+Python API v2
+=============
+
+To create a client::
+
+   from keystoneauth1 import loading
+   from keystoneauth1 import session
+   from glanceclient import Client
+
+   loader = loading.get_plugin_loader('password')
+   auth = loader.load_from_options(
+       auth_url=AUTH_URL,
+       username=USERNAME,
+       password=PASSWORD,
+       project_id=PROJECT_ID)
+   session = session.Session(auth=auth)
+
+   glance = Client('2', session=session)
+
+
+Create
+------
+Create a new image::
+
+   image = glance.images.create(name="myNewImage")
+   glance.images.upload(image.id, open('/tmp/myimage.iso', 'rb'))
+
+Show
+----
+Describe a specific image::
+
+   glance.images.get(image.id)
+
+Update
+------
+Update a specific image::
+
+   # update with a list of image attribute names and their new values
+   glance.images.update(image.id, name="myNewImageName")
+
+Custom Properties
+-----------------
+Set a custom property on an image::
+
+   # set an arbitrary property on an image
+   glance.images.update(image.id, my_custom_property='value')
+
+Remove a custom property from an image::
+
+   # remove the custom property 'my_custom_property'
+   glance.images.update(image.id, remove_props=['my_custom_property'])
+
+Delete
+------
+Delete specified image(s)::
+
+   glance.images.delete(image.id)
+
+List
+----
+List images you can access::
+
+   for image in glance.images.list():
+      print image
+
+Download
+--------
+Download a specific image::
+
+   d = glance.images.data(image.id)
+
+Share an Image
+--------------
+Share a specific image with a tenant::
+
+   glance.image_members.create(image_id, member_id)
+
+Remove a Share
+--------------
+Remove a shared image from a tenant::
+
+   glance.image_members.delete(image_id, member_id)
+
+List Sharings
+-------------
+Describe sharing permissions by image or tenant::
+
+   glance.image_members.list(image_id)
+

doc/source/reference/index.rst

@@ -0,0 +1,27 @@
+==========================
+ Python Library Reference
+==========================
+
+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 glanceclient import Client
+    >>> glance = Client('1', endpoint=OS_IMAGE_ENDPOINT, token=OS_AUTH_TOKEN)
+    >>> image = glance.images.create(name="My Test Image")
+    >>> print image.status
+    'queued'
+    >>> image.update(data=open('/tmp/myimage.iso', 'rb'))
+    >>> print image.status
+    'active'
+    >>> image.update(properties=dict(my_custom_property='value'))
+    >>> with open('/tmp/copyimage.iso', 'wb') as f:
+            for chunk in image.data():
+                f.write(chunk)
+    >>> image.delete()
+
+.. toctree::
+   :maxdepth: 2
+
+   api/index
+   apiv2