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>

2 files changed, 118 insertions, 0 deletions

diff --git a/doc/source/cli/glance.rst b/doc/source/cli/glance.rst
new file mode 100644
index 0000000..8d3cac0
--- /dev/null
+++ b/doc/source/cli/glance.rst
@@ -0,0 +1,87 @@
+==============================
+:program:`glance` CLI man page
+==============================
+
+.. program:: glance
+.. highlight:: bash
+
+SYNOPSIS
+========
+
+:program:`glance` [options] <command> [command-options]
+
+:program:`glance help`
+
+:program:`glance help` <command>
+
+
+DESCRIPTION
+===========
+
+The :program:`glance` command line utility interacts with OpenStack Images
+Service (Glance).
+
+In order to use the CLI, you must provide your OpenStack username, password,
+project (historically called tenant), and auth endpoint. You can use
+configuration options ``--os-username``, ``--os-password``, ``--os-tenant-id``,
+and ``--os-auth-url`` or set corresponding 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
+
+The command line tool will attempt to reauthenticate using provided credentials
+for every request. You can override this behavior by manually supplying an auth
+token using ``--os-image-url`` and ``--os-auth-token`` or by setting
+corresponding environment variables::
+
+    export OS_IMAGE_URL=http://glance.example.org:9292/
+    export OS_AUTH_TOKEN=3bcc3d3a03f44e3d8377f9247b0ad155
+
+You can select an API version to use by ``--os-image-api-version`` option or by
+setting corresponding environment variable::
+
+    export OS_IMAGE_API_VERSION=1
+
+Default Images API used is v2.
+
+OPTIONS
+=======
+
+To get a list of available commands and options run::
+
+    glance help
+
+To get usage and options of a command::
+
+    glance help <command>
+
+
+EXAMPLES
+========
+
+Get information about image-create command::
+
+    glance help image-create
+
+See available images::
+
+    glance image-list
+
+Create new image::
+
+    glance image-create --name foo --disk-format=qcow2 \
+                        --container-format=bare --visibility=public \
+                        --file /tmp/foo.img
+
+Describe a specific image::
+
+    glance image-show <Image-ID>
+
+
+BUGS
+====
+
+Glance client is hosted in Launchpad so you can view current bugs at
+https://bugs.launchpad.net/python-glanceclient/.
diff --git a/doc/source/cli/index.rst b/doc/source/cli/index.rst
new file mode 100644
index 0000000..01b594c
--- /dev/null
+++ b/doc/source/cli/index.rst
@@ -0,0 +1,31 @@
+=============================
+ Command-line Tool Reference
+=============================
+
+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
+
+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::
+
+    export OS_IMAGE_URL=http://glance.example.org:9292/
+    export OS_AUTH_TOKEN=3bcc3d3a03f44e3d8377f9247b0ad155
+
+Once you've configured your authentication parameters, you can run
+``glance help`` to see a complete listing of available commands.
+
+.. toctree::
+
+   glance
+