From d1aded801f427c50509a2d0e8dd1b1fd3e7fccb9 Mon Sep 17 00:00:00 2001
From: Jakub Ruzicka <jruzicka@redhat.com>
Date: Thu, 20 Jun 2013 22:15:15 +0200
Subject: Provide glance CLI man page.

Provide basic but hopefully useful man page.

Also update OpenStack LCC to OpenStack Foundation in docs.

Resolves: bug 1193111
Implements blueprint: clients-man-pages
Change-Id: I9502b3d5ca75149d747d523934a6401e435924b7
---
 doc/source/conf.py        | 17 +++++++--
 doc/source/index.rst      |  3 +-
 doc/source/man/glance.rst | 87 +++++++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 103 insertions(+), 4 deletions(-)
 create mode 100644 doc/source/man/glance.rst

diff --git a/doc/source/conf.py b/doc/source/conf.py
index d7afad5..0b53cdc 100644
--- a/doc/source/conf.py
+++ b/doc/source/conf.py
@@ -3,8 +3,11 @@
 
 import os
 import sys
+import pbr.version
+
+sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(__file__),
+                '..', '..')))
 
-project = 'python-glanceclient'
 
 # -- General configuration ----------------------------------------------------
 
@@ -26,7 +29,8 @@ source_suffix = '.rst'
 master_doc = 'index'
 
 # General information about the project.
-copyright = u'OpenStack LLC'
+project = 'python-glanceclient'
+copyright = u'OpenStack Foundation'
 
 # If true, '()' will be appended to :func: etc. cross-reference text.
 add_function_parentheses = True
@@ -38,6 +42,13 @@ add_module_names = True
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = 'sphinx'
 
+# Grouping the document tree for man pages.
+# List of tuples 'sourcefile', 'target', u'title', u'Authors name', 'manual'
+
+man_pages = [
+    ('man/glance', 'glance', u'Client for OpenStack Images API',
+     [u'OpenStack Foundation'], 1),
+]
 # -- Options for HTML output --------------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  Major themes that come with
@@ -56,7 +67,7 @@ latex_documents = [
         'index',
         '%s.tex' % project,
         u'%s Documentation' % project,
-        u'OpenStack LLC',
+        u'OpenStack Foundation',
         'manual'
     ),
 ]
diff --git a/doc/source/index.rst b/doc/source/index.rst
index a21eb9c..01bbf64 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -32,6 +32,7 @@ The command line tool will attempt to reauthenticate using your provided credent
 
 Once you've configured your authentication parameters, you can run ``glance help`` to see a complete listing of available commands.
 
+See also :doc:`/man/glance`.
 
 Release Notes
 =============
@@ -94,7 +95,7 @@ Release Notes
 .. _1050345: http://bugs.launchpad.net/python-glanceclient/+bug/1050345
 
 0.5.1
-----
+-----
 * 1045824_: Always send Content-Length when updating image with image data
 * 1046607_: Handle 300 Multiple Choices nicely in the CLI
 * 1035931_: Properly display URI in legacy 'show' command
diff --git a/doc/source/man/glance.rst b/doc/source/man/glance.rst
new file mode 100644
index 0000000..2b73dc5
--- /dev/null
+++ b/doc/source/man/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 :option:`--os-username`, :option:`--os-password`,
+:option:`--os-tenant-id`, and :option:`--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 :option:`--os-image-url` and
+:option:`--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 :option:`--os-image-api-version`
+option or by setting corresponding environment variable::
+
+    export OS_IMAGE_API_VERSION=2
+
+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 --is-public=True \
+                        --copy-from http://somewhere.net/foo.img
+
+Describe a specific image::
+
+    glance image-show foo
+
+
+BUGS
+====
+
+Glance client is hosted in Launchpad so you can view current bugs at
+https://bugs.launchpad.net/python-glanceclient/.
-- 
cgit v1.2.1