From e04232b552634a7429c94120cd02c12d86a192c1 Mon Sep 17 00:00:00 2001
From: Jakub Ruzicka <jruzicka@redhat.com>
Date: Wed, 31 Jul 2013 13:07:14 -0400
Subject: [PATCH] Provide cinder CLI man page.

Provide basic but hopefully useful man page.

shell.rst was merged into and replaced by the man page in HTML docs.

pbr is used to determine version.

Docs copyright was changed to more accurate "OpenStack Contributors".

Fixes: bug 1206968
Implements: blueprint clients-man-pages
Change-Id: Iedd7b4b161ced564833fd9433762b87a4c1a374d
---
 doc/source/conf.py        | 13 ++++++---
 doc/source/index.rst      |  2 ++
 doc/source/man/cinder.rst | 58 +++++++++++++++++++++++++++++++++++++++
 3 files changed, 69 insertions(+), 4 deletions(-)
 create mode 100644 doc/source/man/cinder.rst

diff --git a/doc/source/conf.py b/doc/source/conf.py
index a89528da8..d4ae7ca43 100644
--- a/doc/source/conf.py
+++ b/doc/source/conf.py
@@ -13,6 +13,7 @@
 
 import os
 import sys
+import pbr.version
 
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
@@ -43,16 +44,16 @@ master_doc = 'index'
 
 # General information about the project.
 project = 'python-cinderclient'
-copyright = 'Rackspace, based on work by Jacob Kaplan-Moss'
+copyright = 'OpenStack Contributors'
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
 # built documents.
-#
+version_info = pbr.version.VersionInfo('python-cinderclient')
 # The short X.Y version.
-version = '2.6'
+version = version_info.version_string()
 # The full version, including alpha/beta/rc tags.
-release = '2.6.10'
+release = version_info.release_string()
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -93,6 +94,10 @@ pygments_style = 'sphinx'
 #modindex_common_prefix = []
 
 
+man_pages = [
+    ('man/cinder', 'cinder', u'Client for OpenStack Block Storage API',
+     [u'OpenStack Contributors'], 1),
+]
 # -- Options for HTML output --------------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  Major themes that come with
diff --git a/doc/source/index.rst b/doc/source/index.rst
index 784a6656a..27606564f 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -24,6 +24,8 @@ In order to use the CLI, you must provide your OpenStack username, password, ten
 
 Once you've configured your authentication parameters, you can run ``cinder help`` to see a complete listing of available commands.
 
+See also :doc:`/man/cinder`.
+
 
 Release Notes
 =============
diff --git a/doc/source/man/cinder.rst b/doc/source/man/cinder.rst
new file mode 100644
index 000000000..50fb644f0
--- /dev/null
+++ b/doc/source/man/cinder.rst
@@ -0,0 +1,58 @@
+==============================
+:program:`cinder` CLI man page
+==============================
+
+.. program:: cinder
+.. highlight:: bash
+
+
+SYNOPSIS
+========
+
+:program:`cinder` [options] <command> [command-options]
+
+:program:`cinder help`
+
+:program:`cinder help` <command>
+
+
+DESCRIPTION
+===========
+
+The :program:`cinder` command line utility interacts with OpenStack Block
+Storage Service (Cinder).
+
+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-name` or :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_NAME=myproject
+    export OS_AUTH_URL=http://auth.example.com:5000/v2.0
+
+You can select an API version to use by :option:`--os-volume-api-version`
+option or by setting corresponding environment variable::
+
+    export OS_VOLUME_API_VERSION=2
+
+
+OPTIONS
+=======
+
+To get a list of available commands and options run::
+
+    cinder help
+
+To get usage and options of a command::
+
+    cinder help <command>
+
+
+BUGS
+====
+
+Cinder client is hosted in Launchpad so you can view current bugs at
+https://bugs.launchpad.net/python-cinderclient/.