Prep for 0.2 release (0.2.rc1)

* rename HACKING to HACKING.rst and refer to the common OpenStack HACKING file
* add the barest of pointers to the wiki, etc. to the source docs
* add a bare-bones man page

Change-Id: I80e5b972af645f14ef17ae87f182ab09cb08dabe

HACKING

@@ -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

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

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
 ===============
 

doc/source/commands.rst

@@ -2,33 +2,50 @@
 Commands
 ========
 
+
 Command Structure
 =================
 
-OpenStack Client uses a command form ``verb object``.
+OpenStackClient has a consistent and predictable format for all of its commands.
-
-Note that 'object' here refers to the target of a command's action.  In coding
-discussions 'object' has its usual Python meaning.  Go figure.
 
 Commands take the form::
 
-    openstack [<global-options>] <verb> <object> [<command-local-arguments>]
+    openstack [<global-options>] <object> <action> [<second-object>] [<command-arguments>]
 
-Command Arguments
+* All long options names begin with two dashes ('--') and use a single dash ('-') internally between words (--like-this)
------------------
 
-  * All long option names use two dashes ('--') as the prefix and a single dash
+
-    ('-') as the interpolation character.  Some common options also have the
+Global Options
-    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
+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.
-    option takes priority. The environment variable names can be derived from
+
-    the option name by dropping the leading '--', converting all embedded dashes
+For example, ``--os-username`` can be set from the environment via ``OS_USERNAME``.
-    ('-') 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
+Command Object(s) and Action
-    as positional arguments. If they also appear in the command object they are
+----------------------------
-    in the same order.
+
+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)."
+
+::
+
+    <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
 --------------------
 

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',
+        'man/openstack',
-     [u'OpenStack'], 1)
+        'openstack',
+        u'OpenStack Command Line Client',
+        [u'OpenStack contributors'],
+        1,
+    ),
 ]
 
 # If true, show URL addresses after external links.

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
+of python-keystoneclient, python-novaclient, python-glanceclient and
-(formerly glance client) in a single shell with a uniform command
+python-cinderclient in a single shell with a uniform command structure.
-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
 =====
 

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>

openstackclient/shell.py

@@ -30,7 +30,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'

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