openstack/python-openstackclient
Code Issues Proposed changes

Update docs and release notes for 0.4.0

Browse Source 
Change-Id: Iad6cfe5dee63adb9e60a0ea9811217b3175eb99c
This commit is contained in:
Dean Troyer 2014-05-15 09:05:37 -05:00
parent 982b418da7
commit 3fa5fa5ba7
5 changed files with 94 additions and 38 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

74
doc/source/commands.rst
View File

@ -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.
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
* 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
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 =

8
doc/source/index.rst
View File

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

9
doc/source/man/openstack.rst
View File

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

4
doc/source/plugins.rst
View File

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

37
doc/source/releases.rst
View File

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