Merge "Prep for 0.2 release (0.2.rc1)"0.2.rc1

9 files changed, 315 insertions, 155 deletions

diff --git a/HACKING b/HACKING
deleted file mode 100644
index dd31ccd5..00000000
--- a/HACKING
+++ /dev/null
@@ -1,122 +0,0 @@
-OpenStack Style Commandments
-============================
-
-Step 1: Read http://www.python.org/dev/peps/pep-0008/
-Step 2: Read http://www.python.org/dev/peps/pep-0008/ again
-Step 3: Read on
-
-Imports
--------
-- thou shalt not import objects, only modules
-- thou shalt not import more than one module per line
-- thou shalt not make relative imports
-- thou shalt organize your imports according to the following template
-
-::
-  # vim: tabstop=4 shiftwidth=4 softtabstop=4
-  {{stdlib imports in human alphabetical order}}
-  \n
-  {{3rd-party imports in human alphabetical order}}
-  \n
-  {{openstack imports in human alphabetical order}}
-  \n
-  \n
-  {{begin your code}}
-
-General
--------
-- thou shalt put two newlines twixt toplevel code (funcs, classes, etc)
-- thou shalt put one newline twixt methods in classes and anywhere else
-- thou shalt not write "except:", use "except Exception:" at the very least
-- thou shalt include your name with TODOs as in "TODO(termie)"
-- thou shalt not name anything the same name as a builtin or reserved word
-- thou shalt not violate causality in our time cone, or else
-
-Human Alphabetical Order Examples
----------------------------------
-::
-  import httplib
-  import logging
-  import random
-  import StringIO
-  import testtools
-  import time
-
-  from nova import flags
-  from nova import test
-  from nova.auth import users
-  from nova.endpoint import api
-  from nova.endpoint import cloud
-
-Docstrings
-----------
-  """A one line docstring looks like this and ends in a period."""
-
-  """A multiline docstring has a one-line summary, less than 80 characters.
-
-  Then a new paragraph after a newline that explains in more detail any
-  general information about the function, class or method. Example usages
-  are also great to have here if it is a complex class for function. After
-  you have finished your descriptions add an extra newline and close the
-  quotations.
-
-  When writing the docstring for a class, an extra line should be placed
-  after the closing quotations. For more in-depth explanations for these
-  decisions see http://www.python.org/dev/peps/pep-0257/
-
-  If you are going to describe parameters and return values, use Sphinx, the
-  appropriate syntax is as follows.
-
-  :param foo: the foo parameter
-  :param bar: the bar parameter
-  :returns: description of the return value
-
-  """
-
-Text encoding
-----------
-- All text within python code should be of type 'unicode'.
-
-    WRONG:
-
-    >>> s = 'foo'
-    >>> s
-    'foo'
-    >>> type(s)
-    <type 'str'>
-
-    RIGHT:
-
-    >>> u = u'foo'
-    >>> u
-    u'foo'
-    >>> type(u)
-    <type 'unicode'>
-
-- Transitions between internal unicode and external strings should always
-  be immediately and explicitly encoded or decoded.
-
-- All external text that is not explicitly encoded (database storage,
-  commandline arguments, etc.) should be presumed to be encoded as utf-8.
-
-    WRONG:
-
-    mystring = infile.readline()
-    myreturnstring = do_some_magic_with(mystring)
-    outfile.write(myreturnstring)
-
-    RIGHT:
-
-    mystring = infile.readline()
-    mytext = s.decode('utf-8')
-    returntext = do_some_magic_with(mytext)
-    returnstring = returntext.encode('utf-8')
-    outfile.write(returnstring)
-
-Running Tests
--------------
-The testing system is based on a combination of tox and testr. If you just
-want to run the whole suite, run `tox` and all will be fine. However, if
-you'd like to dig in a bit more, you might want to learn some things about
-testr itself. A basic walkthrough for OpenStack can be found at
-http://wiki.openstack.org/testr
diff --git a/HACKING.rst b/HACKING.rst
new file mode 100644
index 00000000..15dca8f8
--- /dev/null
+++ b/HACKING.rst
@@ -0,0 +1,106 @@
+OpenStack Style Commandments
+============================
+
+Step 0: Read https://github.com/openstack-dev/hacking/blob/master/HACKING.rst
+Step 1: Read http://www.python.org/dev/peps/pep-0008/ one more time
+Step 2: Read on
+
+General
+-------
+- thou shalt not violate causality in our time cone, or else
+
+Docstrings
+----------
+
+Docstrings should ONLY use triple-double-quotes (``"""``)
+
+Single-line docstrings should NEVER have extraneous whitespace
+between enclosing triple-double-quotes.
+
+Deviation! Sentence fragments do not have punctuation.  Specifically in the
+command classes the one line docstring is also the help string for that
+command and those do not have periods.
+
+  """A one line docstring looks like this"""
+
+Calling Methods
+---------------
+
+Deviation! When breaking up method calls due to the 79 char line length limit,
+use the alternate 4 space indent.  With the frist argument on the succeeding
+line all arguments will then be vertically aligned.  Use the same convention
+used with other data structure literals and terminate the method call with
+the last argument line ending with a comma and the closing paren on its own
+line indented to the starting line level.
+
+    unnecessarily_long_function_name(
+        'string one',
+        'string two',
+        kwarg1=constants.ACTIVE,
+        kwarg2=['a', 'b', 'c'],
+    )
+
+Text encoding
+-------------
+
+Note: this section clearly has not been implemented in this project yet, it is
+the intention to do so.
+
+All text within python code should be of type 'unicode'.
+
+    WRONG:
+
+    >>> s = 'foo'
+    >>> s
+    'foo'
+    >>> type(s)
+    <type 'str'>
+
+    RIGHT:
+
+    >>> u = u'foo'
+    >>> u
+    u'foo'
+    >>> type(u)
+    <type 'unicode'>
+
+Transitions between internal unicode and external strings should always
+be immediately and explicitly encoded or decoded.
+
+All external text that is not explicitly encoded (database storage,
+commandline arguments, etc.) should be presumed to be encoded as utf-8.
+
+    WRONG:
+
+    mystring = infile.readline()
+    myreturnstring = do_some_magic_with(mystring)
+    outfile.write(myreturnstring)
+
+    RIGHT:
+
+    mystring = infile.readline()
+    mytext = s.decode('utf-8')
+    returntext = do_some_magic_with(mytext)
+    returnstring = returntext.encode('utf-8')
+    outfile.write(returnstring)
+
+Python 3.x Compatibility
+------------------------
+
+OpenStackClient strives to be Python 3.3 compatibile.  Common guidelines:
+
+* Convert print statements to functions: print statements should be converted
+  to an appropriate log or other output mechanism.
+* Use six where applicable: x.iteritems is converted to six.iteritems(x)
+  for example.
+
+Running Tests
+-------------
+
+Note: Oh boy, are we behing on writing tests.  But they are coming!
+
+The testing system is based on a combination of tox and testr. If you just
+want to run the whole suite, run `tox` and all will be fine. However, if
+you'd like to dig in a bit more, you might want to learn some things about
+testr itself. A basic walkthrough for OpenStack can be found at
+http://wiki.openstack.org/testr
diff --git a/README.rst b/README.rst
index 8f5b0ab7..b0f3b6b7 100644
--- a/README.rst
+++ b/README.rst
@@ -26,6 +26,13 @@ For issue tracking::
 
    * https://bugs.launchpad.net/python-openstackclient
 
+Note
+====
+
+OpenStackClient is considered to be alpha release quality as of the 0.2 release;
+no assurances are made at this point for ongoing compatibility in command forms
+or output.  We do not, however, expect any major changes at this point.
+
 Getting Started
 ===============
 
diff --git a/doc/source/commands.rst b/doc/source/commands.rst
index 0c278d05..7cd05951 100644
--- a/doc/source/commands.rst
+++ b/doc/source/commands.rst
@@ -2,33 +2,50 @@
 Commands
 ========
 
+
 Command Structure
 =================
 
-OpenStack Client uses a command form ``verb object``.
-
-Note that 'object' here refers to the target of a command's action.  In coding
-discussions 'object' has its usual Python meaning.  Go figure.
+OpenStackClient has a consistent and predictable format for all of its commands.
 
 Commands take the form::
 
-    openstack [<global-options>] <verb> <object> [<command-local-arguments>]
+    openstack [<global-options>] <object> <action> [<second-object>] [<command-arguments>]
+
+* All long options names begin with two dashes ('--') and use a single dash ('-') internally between words (--like-this)
+
+
+Global Options
+--------------
+
+Global options are global in the sense that the apply to every command invocation regardless of action to be performed. This includes authentication credentials and API version selection. Most global options have a corresponding environment variable that may also be used to set the value. If both are present, the command-line option takes priority. The environment variable names are derived from the option name by dropping the leading dashes ('--'), converting each embedded dash ('-') to an underscore ('_'), and converting to upper case.
+
+For example, ``--os-username`` can be set from the environment via ``OS_USERNAME``.
+
+
+Command Object(s) and Action
+----------------------------
 
-Command Arguments
------------------
+Commands consist of an object described by one or more words followed by an action.
+In commands requiring two objects be acted upon, the primary object appears ahead of the action and the secondary object appears after the action.
+If both objects have cooresponding positional arguments the arguments appear in the same order as the objects. In badly formed English it is expressed as "(Take) object1 (and perform) action (using) object2 (to it)."
 
-  * All long option names use two dashes ('--') as the prefix and a single dash
-    ('-') as the interpolation character.  Some common options also have the
-    traditional single letter name prefixed by a single dash ('-').
-  * Global options generally have a corresponding environment variable that
-    may also be used to set the value. If both are present, the command-line
-    option takes priority. The environment variable names can be derived from
-    the option name by dropping the leading '--', converting all embedded dashes
-    ('-') to underscores ('_'), and converting the name to upper case.
-  * Positional arguments trail command options. In commands that require two or
-    more objects be acted upon, such as 'attach A to B', both objects appear
-    as positional arguments. If they also appear in the command object they are
-    in the same order.
+::
+
+    <object-1> <action> <object-2>
+
+Examples::
+
+    group add user <group> <user>
+
+    volume type list   # 'volume type' is a two-word single object
+
+
+Command Arguments and Options
+-----------------------------
+
+Commands have their own set of options distinct from the global options.  They follow the
+same style as the global options and always appear between the command and any positional arguemnts the command may require.
 
 
 Implementation
@@ -38,6 +55,7 @@ The command structure is designed to support seamless addition of extension
 command modules via entry points.  The extensions are assumed to be subclasses
 of Cliff's command.Command object.
 
+
 Command Entry Points
 --------------------
 
diff --git a/doc/source/conf.py b/doc/source/conf.py
index df1e9e5f..47025b6d 100644
--- a/doc/source/conf.py
+++ b/doc/source/conf.py
@@ -15,10 +15,12 @@
 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
 # documentation root, use os.path.abspath to make it absolute, like shown here.
-#sys.path.insert(0, os.path.abspath('.'))
+sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(__file__), '..', '..')))
 
 # -- General configuration ----------------------------------------------------
 
@@ -46,16 +48,18 @@ master_doc = 'index'
 
 # General information about the project.
 project = u'OpenStack Command Line Client'
-copyright = u'2012, OpenStack'
+copyright = u'2012-2013 OpenStack Foundation'
 
 # 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-openstackclient')
+#
 # The short X.Y version.
-version = '0.1'
+version = version_info.version_string()
 # The full version, including alpha/beta/rc tags.
-release = '0.1'
+release = version_info.release_string()
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -221,9 +225,13 @@ latex_documents = [
 # One entry per manual page. List of tuples
 # (source start file, name, description, authors, manual section).
 man_pages = [
-    ('index', 'openstackcommandlineclient',
-    u'OpenStack Command Line Client Documentation',
-     [u'OpenStack'], 1)
+    (
+        'man/openstack',
+        'openstack',
+        u'OpenStack Command Line Client',
+        [u'OpenStack contributors'],
+        1,
+    ),
 ]
 
 # If true, show URL addresses after external links.
diff --git a/doc/source/index.rst b/doc/source/index.rst
index 8da13c90..deddd07e 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -2,24 +2,31 @@ OpenStack Client
 ================
 
 This is a command-line client for OpenStack that unifies the operation
-of python-keystoneclient, python-novaclient and python-glanceclient
-(formerly glance client) in a single shell with a uniform command
-structure.
+of python-keystoneclient, python-novaclient, python-glanceclient and
+python-cinderclient in a single shell with a uniform command structure.
 
 Contents:
 
 .. toctree::
    :maxdepth: 1
 
+   commands
+   man/openstack
+
 Getting Started
 ---------------
 
-* Read the source
+* Check out `the wiki`_
+* Try `some commands`_
+* Read the source `on GitHub`_
+
+.. _the wiki: https://wiki.openstack.org/OpenStackClient
+.. _some commands: https://wiki.openstack.org/OpenStackClient/Commands
 
 Contributing
 ============
 
-Code is hosted `on GitHub`_. Submit bugs to the Python-OpenStackClient project
+Code is hosted `on GitHub`_. Submit bugs to the python-openstackclient project
 on  `Launchpad`_. Submit code to the openstack/python-openstackclient project
 using `Gerrit`_.
 
@@ -27,6 +34,15 @@ using `Gerrit`_.
 .. _Launchpad: https://launchpad.net/python-openstackclient
 .. _Gerrit: http://wiki.openstack.org/GerritWorkflow
 
+Release Notes
+=============
+
+0.2
+---
+
+* First alpha release to PyPI
+* Implemented Compute, Identity, Image and Volume API commands
+
 Index
 =====
 
diff --git a/doc/source/man/openstack.rst b/doc/source/man/openstack.rst
new file mode 100644
index 00000000..c797f285
--- /dev/null
+++ b/doc/source/man/openstack.rst
@@ -0,0 +1,127 @@
+=========
+:program:`openstack`
+=========
+
+
+SYNOPSIS
+========
+
+:program:`openstack` [<global-options>] <command> [<command-arguments>]
+
+:program:`openstack help` <command>
+
+
+
+DESCRIPTION
+===========
+
+:program:`openstack` provides a common command-line interface to OpenStack APIs.  It is generally
+equivalent to the CLIs provided by the OpenStack project client librariess, but with
+a distinct and consistent command structure.
+
+:program:`openstack` uses a similar authentication scheme as the OpenStack project CLIs, with
+the credential information supplied either as environment variables or as options on the
+command line.  The primary difference is a preference for using
+``OS_PROJECT_NAME``/``OS_PROJECT_ID`` over the old tenant-based names.  The old names work
+for now though.
+
+::
+
+    export OS_AUTH_URL=<url-to-openstack-identity>
+    export OS_PROJECT_NAME=<project-name>
+    export OS_USERNAME=<user-name>
+    export OS_PASSWORD=<password>  # (optional)
+
+
+OPTIONS
+=======
+
+:program:`openstack` recognizes the following global topions:
+
+:option:`--os-auth-url <auth-url>`
+    Authentication URL
+
+:option:`--os-project-name <auth-project-name>`
+    Authentication project name (only one of :option:`--os-project-name` or :option:`--os-project-id` need be supplied)
+
+:option:`--os-project-id <auth-project-id>`
+    Authentication tenant ID  (only one of :option:`--os-project-name` or :option:`--os-project-id` need be supplied)
+
+:option:`--os-username <auth-username>`
+    Authentication username
+
+:option:`--os-password <auth-password>`
+    Authentication password
+
+:option:`--os-region-name <auth-region-name>`
+    Authentication region name
+
+:option:`--os-default-domain <auth-domain>`
+    Default domain ID (defaults to 'default')
+
+
+NOTES
+=====
+
+[This section intentionally left blank.  So there.]
+
+
+COMMANDS
+========
+
+To get a list of the available commands::
+
+    openstack -h
+
+To get a description of a specific command::
+
+    openstack help <command>
+
+
+FILES
+=====
+
+  :file:`~/.openstack`
+
+
+ENVIRONMENT VARIABLES
+=====================
+
+The following environment variables can be set to alter the behaviour of :program:`openstack`
+
+:envvar:`OS_USERNAME`
+    Set the username
+
+:envvar:`OS_PASSWORD`
+    Set the password
+
+
+BUGS
+====
+
+Bug reports are accepted at the python-openstackclient LaunchPad project
+"https://bugs.launchpad.net/python-openstackclient/+bugs".
+
+
+AUTHORS
+=======
+
+Please refer to the AUTHORS file distributed with OpenStackClient.
+
+
+COPYRIGHT
+=========
+
+Copyright 2011-2013 OpenStack Foundation and the authors listed in the AUTHORS file.
+
+
+LICENSE
+=======
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+
+SEE ALSO
+========
+
+The OpenStack project CLIs, the OpenStack API references. <links TBD>
diff --git a/openstackclient/shell.py b/openstackclient/shell.py
index 7bc0a44a..8a15bc9b 100644
--- a/openstackclient/shell.py
+++ b/openstackclient/shell.py
@@ -31,7 +31,7 @@ from openstackclient.common import openstackkeyring
 from openstackclient.common import utils
 
 
-VERSION = '0.1'
+VERSION = '0.2.rc1'
 KEYRING_SERVICE = 'openstack'
 
 DEFAULT_COMPUTE_API_VERSION = '2'
diff --git a/setup.cfg b/setup.cfg
index 585ab622..494de8d2 100644
--- a/setup.cfg
+++ b/setup.cfg
@@ -5,7 +5,7 @@ description-file =
     README.rst
 author = OpenStack
 author-email = openstack-dev@lists.openstack.org
-home-page = http://www.openstack.org/
+home-page = http://wiki.openstack.org/OpenStackClient
 classifier =
     Environment :: OpenStack
     Intended Audience :: Information Technology