Merge "Update docs and release notes for 0.4.0"0.4.0

5 files changed, 95 insertions, 39 deletions

diff --git a/doc/source/commands.rst b/doc/source/commands.rst
index e0cfee7a..a9d10c96 100644
--- a/doc/source/commands.rst
+++ b/doc/source/commands.rst
@@ -12,9 +12,9 @@ Commands take the form::
 
     openstack [<global-options>] <object-1> <action> [<object-2>] [<command-arguments>]
 
-* All long options names begin with two dashes ('--') and use a single dash
-  ('-') internally between words (--like-this).  Underscores ('_') are not used
-  in option names.
+* All long options names begin with two dashes (``--``) and use a single dash
+  (``-``) internally between words (``--like-this``).  Underscores (``_``) are
+  not used in option names.
 
 
 Global Options
@@ -25,11 +25,12 @@ invocation regardless of action to be performed. They include 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
+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``.
+For example, the default value of ``--os-username`` can be set by defining
+the environment variable ``OS_USERNAME``.
 
 
 Command Object(s) and Action
@@ -64,39 +65,46 @@ the command and any positional arguments the command requires.
 Actions
 -------
 
-The actions used by OpenStackClient are defined below to provide a consistent meaning to each action. Many of them have logical opposite actions. Those actions with an opposite action are noted in parens if applicable.
-
-* authorize - authorize a token (used in OAuth)
-* add (remove) - add some object to a container object; the command is built in the order of "container add object" (<container> <object>), the positional arguments appear in the same order
-* attach (detach) - deprecated; use add/remove
-* create (delete) - create a new occurrence of the specified object
-* delete (create) - delete a specific occurrence of the specified object
-* detach (attach) - deprecated; use add/remove
-* list - display summary information about multiple objects
-* lock (unlock)
-* migrate - move a server to a different host; --live performs a live migration if possible
-* pause (unpause) - stop a server and leave it in memory
-* reboot - forcibly reboot a server
-* rebuild - rebuild a server using (most of) the same arguments as in the original create
-* remove (add) - remove an object from a group of objects
-* rescue (unrescue) - reboot a server in a special rescue mode allowing access to the original disks
-* resize - change a server's flavor
-* resume (suspend) - return a suspended server to running state
-* save - download an object locally
-* set (unset) - set a property on the object, formerly called metadata
-* show - display detailed information about the specific object
-* suspend (resume) - stop a server and save to disk freeing memory
-* unlock (lock)
-* unpause (pause) - return a paused server to running state
-* unrescue (rescue) - return a server to normal boot mode
-* unset (set) - remove an attribute of the object
+The actions used by OpenStackClient are defined below to provide a consistent
+meaning to each action. Many of them have logical opposite actions.
+Those actions with an opposite action are noted in parens if applicable.
+
+* ``authorize`` - authorize a token (used in OAuth)
+* ``add`` (``remove``) - add some object to a container object; the command
+  is built in the order of ``container add object <container> <object>``,
+  the positional arguments appear in the same order
+* ``create`` (``delete``) - create a new occurrence of the specified object
+* ``delete`` (``create``) - delete a specific occurrence of the specified object
+* ``issue`` (``revoke``) - issue a token
+* ``list`` - display summary information about multiple objects
+* ``lock`` (``unlock``)
+* ``migrate`` - move a server to a different host; ``--live`` performs a
+  live migration if possible
+* ``pause`` (``unpause``) - stop a server and leave it in memory
+* ``reboot`` - forcibly reboot a server
+* ``rebuild`` - rebuild a server using (most of) the same arguments as in the original create
+* ``remove`` (``add``) - remove an object from a group of objects
+* ``rescue`` (``unrescue``) - reboot a server in a special rescue mode allowing access to the original disks
+* ``resize`` - change a server's flavor
+* ``resume`` (``suspend``) - return a suspended server to running state
+* ``revoke`` (``issue``) - revoke a token
+* ``save`` - download an object locally
+* ``set`` (``unset``) - set a property on the object, formerly called metadata
+* ``show`` - display detailed information about the specific object
+* ``suspend`` (``resume``) - stop a server and save to disk freeing memory
+* ``unlock`` (``lock``)
+* ``unpause`` (``pause``) - return a paused server to running state
+* ``unrescue`` (``rescue``) - return a server to normal boot mode
+* ``unset`` (``set``) - remove an attribute of the object
+
 
 Implementation
 ==============
 
 The command structure is designed to support seamless addition of plugin
 command modules via ``setuptools`` entry points.  The plugin commands must
-be subclasses of Cliff's command.Command object.
+be subclasses of Cliff's command.Command object.  See :doc:`plugins` for
+more information.
 
 
 Command Entry Points
@@ -111,7 +119,7 @@ entry points have the form::
 
     verb_object = fully.qualified.module.vXX.object:VerbObject
 
-For example, the 'list user' command fir the Identity API is identified in
+For example, the ``list user`` command for the Identity API is identified in
 ``setup.cfg`` with::
 
     openstack.identity.v3 =
diff --git a/doc/source/index.rst b/doc/source/index.rst
index f42ea1b7..2bb8f386 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -1,7 +1,9 @@
-OpenStack Client
-================
+===============
+OpenStackClient
+===============
 
-This is a command-line client for OpenStack that unifies the operation
+OpenStackClient (aka OSC) is a command-line client for OpenStack that
+unifies the operation
 of python-keystoneclient, python-novaclient, python-glanceclient and
 python-cinderclient in a single shell with a uniform command structure.
 
diff --git a/doc/source/man/openstack.rst b/doc/source/man/openstack.rst
index 74db6815..16f0bc47 100644
--- a/doc/source/man/openstack.rst
+++ b/doc/source/man/openstack.rst
@@ -181,9 +181,18 @@ The following environment variables can be set to alter the behaviour of :progra
 :envvar:`OS_CACERT`
     CA certificate bundle file
 
+:envvar:`OS_COMPUTE_API_VERISON`
+    Compute API version (Default: 2)
+
 :envvar:`OS_IDENTITY_API_VERISON`
     Identity API version (Default: 2.0)
 
+:envvar:`OS_IMAGE_API_VERISON`
+    Image API version (Default: 1)
+
+:envvar:`OS_VOLUME_API_VERISON`
+    Volume API version (Default: 1)
+
 :envvar:`OS_XXXX_API_VERISON`
     Additional API version options will be available depending on the installed API libraries.
 
diff --git a/doc/source/plugins.rst b/doc/source/plugins.rst
index 5cea16cf..690c1269 100644
--- a/doc/source/plugins.rst
+++ b/doc/source/plugins.rst
@@ -11,7 +11,7 @@ Implementation
 --------------
 
 Plugins are discovered by enumerating the entry points
-found under ``openstack.cli.extension`` and initializing the specified
+found under :py:mod:`openstack.cli.extension` and initializing the specified
 client module.
 
 ::
@@ -42,5 +42,5 @@ defined for the API version:
         plugin_list = oscplugin.v1.plugin:ListPlugin
         plugin_show = oscplugin.v1.plugin:ShowPlugin
 
-Note that OSC defines the group name as ``openstack.<api-name>.v<version>``
+Note that OSC defines the group name as :py:mod:`openstack.<api-name>.v<version>`
 so the version should not contain the leading 'v' character.
diff --git a/doc/source/releases.rst b/doc/source/releases.rst
index 85a29ba9..9551db2e 100644
--- a/doc/source/releases.rst
+++ b/doc/source/releases.rst
@@ -2,6 +2,43 @@
 Release Notes
 =============
 
+0.4.0 (20 Jun 2014)
+===================
+
+* Bug 1184012_: fix Identity v2 endpoint command name/id handling
+* Bug 1207615_: add ``--volume`` and ``--force`` to ``image create`` command
+* Bug 1220280_: add ``--property`` to project create and set commands
+* Bug 1246310_: add ``role assignments list`` command
+* Bug 1285800_: rename ``agent`` to ``compute agent``
+* Bug 1289513_: add ``--domain`` to project list
+* Bug 1289594_: fix keypair show output
+* Bug 1292337_: fix ec2 credentials project ID output
+* Bug 1303978_: fix output of ``volume type create`` command
+* Bug 1316870_: display all output when ``--lines`` omitted from ``console log show`` command
+* add 'interface' and 'url' columns to endpoint list command
+* add identity provider create/delete/list/set/show commands
+* change ``volume create --volume-type`` option to ``--type``
+* fix ``server image create`` command output
+* configure appropriate logging levels for ``--verbose``, ``--quiet`` and ``--debug``
+* properly handle properties in Image v1 ``create`` and ``set`` commands
+* rename Identity v2 ``token create`` to ``token issue``
+* add Identity v2 ``token revoke`` command
+* refactor the ``group|user|role list`` command filters so that each command
+  only lists rows of that type of object, ie ``user list`` always lists users, etc.
+* add ``role assignment list`` command
+* add ``extension list`` command
+
+.. _1184012: https://launchpad.net/bugs/1184012
+.. _1207615: https://launchpad.net/bugs/1207615
+.. _1220280: https://launchpad.net/bugs/1220280
+.. _1246310: https://launchpad.net/bugs/1246310
+.. _1285800: https://launchpad.net/bugs/1285800
+.. _1289513: https://launchpad.net/bugs/1289513
+.. _1289594: https://launchpad.net/bugs/1289594
+.. _1292337: https://launchpad.net/bugs/1292337
+.. _1303978: https://launchpad.net/bugs/1303978
+.. _1316870: https://launchpad.net/bugs/1316870
+
 0.3.1 (28 Feb 2014)
 ===================