Add a basic man page for heat

This shows a taste of commands and shows how to access the help

Closes-bug: #1153824
Change-Id: Ia69072c224e8940927dce0c984040d4c81bcee45

doc/source/conf.py

@@ -223,6 +223,11 @@ latex_documents = [
 
 # One entry per manual page. List of tuples
 # (source start file, name, description, authors, manual section).
+man_pages = [
+    ('man/heat', 'heat',
+     u'Command line access to the heat project.',
+     [u'Heat Developers'], 1),
+]
 
 # If true, show URL addresses after external links.
 #man_show_urls = False

doc/source/index.rst

@@ -28,6 +28,14 @@ The command line tool will attempt to reauthenticate using your provided credent
 
 Once you've configured your authentication parameters, you can run ``heat help`` to see a complete listing of available commands.
 
+Man Pages
+=========
+
+.. toctree::
+    :maxdepth: 1
+
+    man/heat
+
 Contributing
 ============
 Code is hosted `on GitHub`_. Submit bugs to the Heat project on

doc/source/man/heat.rst

@@ -0,0 +1,76 @@
+====
+heat
+====
+
+.. program:: heat
+
+SYNOPSIS
+========
+
+  `heat` [options] <command> [command-options]
+
+  `heat help`
+
+  `heat help` <command>
+
+
+DESCRIPTION
+===========
+
+`heat` is a command line client for controlling OpenStack Heat.
+
+Before the `heat` command is issued, ensure the environment contains
+the necessary variables so that the CLI can pass user credentials to
+the server.
+See `Getting Credentials for a CLI`  section of `OpenStack CLI Guide`
+for more info.
+
+
+OPTIONS
+=======
+
+To get a list of available commands and options run::
+
+    heat help
+
+To get usage and options of a command run::
+
+    heat help <command>
+
+
+EXAMPLES
+========
+
+Get information about stack-create command::
+
+    heat help stack-create
+
+List available stacks::
+
+    heat stack-list
+
+List available resources in a stack::
+
+    heat resource-list <stack name>
+
+Create a stack::
+
+    heat stack-create mystack -f some-template.yaml -P "KeyName=mine"
+
+View stack information::
+
+    heat stack-show mystack
+
+List events::
+
+    heat event-list mystack
+
+Delete a stack::
+
+    heat stack-delete mystack
+
+
+BUGS
+====
+
+Heat client is hosted in Launchpad so you can view current bugs at https://bugs.launchpad.net/python-heatclient/.