diff --git a/README.rst b/README.rst
index 00c920ba36..937c0fee25 100644
--- a/README.rst
+++ b/README.rst
@@ -2,8 +2,9 @@
OpenStack Client
================
-python-openstackclient is a unified command-line client for the OpenStack APIs.
-It is a thin wrapper to the stock python-*client modules that implement the
+OpenStackclient (aka ``python-openstackclient``) is a command-line client for
+the OpenStack APIs.
+It is primarily a wrapper to the stock python-*client modules that implement the
actual REST API client actions.
This is an implementation of the design goals shown in
@@ -14,8 +15,7 @@ operations in OpenStack. The master repository is on GitHub_.
.. _OpenStack Client Wiki: https://wiki.openstack.org/wiki/OpenStackClient
.. _GitHub: https://github.com/openstack/python-openstackclient
-python-openstackclient is designed to add support for API extensions via a
-plugin mechanism.
+OpenStackclient has a plugin mechanism to add support for API extensions.
* `Release management`_
* `Blueprints and feature specifications`_
@@ -32,32 +32,41 @@ plugin mechanism.
Note
====
-OpenStackClient is considered to be alpha release quality as of the 0.2 release;
+OpenStackClient is considered to be beta release quality as of the 0.3 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
===============
-We recommend using a virtualenv to install the client. This description
-uses the `install virtualenv`_ script to create the virtualenv::
+OpenStackclient can be installed from PyPI using pip::
+
+ pip install python-openstackclient
+
+Developers can use the `install virtualenv`_ script to create the virtualenv::
python tools/install_venv.py
source .venv/bin/activate
python setup.py develop
-Unit tests can be ran simply by running::
-
- run_tests.sh
+Unit tests are now run using tox. The ``run_test.sh`` script provides compatability
+but is generally considered deprecated.
The client can be called interactively by simply typing::
openstack
-Alternatively command line parameters can be called non-interactively::
+There are a few variants on getting help. A list of global options and supported
+commands is shown with ``--help``::
openstack --help
+There is also a ``help`` command that can be used to get help text for a specific
+command::
+
+ openstack help
+ openstack help server create
+
Configuration
=============
@@ -116,10 +125,9 @@ The source is maintained in the ``doc/source`` folder using
.. _reStructuredText: http://docutils.sourceforge.net/rst.html
.. _Sphinx: http://sphinx.pocoo.org/
-* Building Manually::
+Building Manually::
- $ export DJANGO_SETTINGS_MODULE=local.local_settings
- $ python doc/generate_autodoc_index.py
- $ sphinx-build -b html doc/source build/sphinx/html
+ cd doc
+ make html
-Results are in the `build/sphinx/html` directory.
+Results are in the ``build/html`` directory.
diff --git a/doc/source/commands.rst b/doc/source/commands.rst
index 0b93c64d98..31e7c14831 100644
--- a/doc/source/commands.rst
+++ b/doc/source/commands.rst
@@ -61,6 +61,36 @@ They follow the same style as the global options and always appear between
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 occurrance of the specified object
+* delete (create) - delete a specific occurrance 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
==============
diff --git a/doc/source/man/openstack.rst b/doc/source/man/openstack.rst
index 3a780e2472..74db68154a 100644
--- a/doc/source/man/openstack.rst
+++ b/doc/source/man/openstack.rst
@@ -18,7 +18,7 @@ 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
+equivalent to the CLIs provided by the OpenStack project client libraries, but with
a distinct and consistent command structure.
:program:`openstack` uses a similar authentication scheme as the OpenStack project CLIs, with
@@ -37,49 +37,51 @@ command line. The primary difference is the use of 'project' in the name of the
OPTIONS
=======
+:program:`openstack` takes global options that control overall behaviour and command-specific options that control the command operation. 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.
+
:program:`openstack` recognizes the following global topions:
-:option:`--os-auth-url <auth-url>`
+: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-domain-name` <auth-domain-name> | :option:`--os-domain-id` <auth-domain-id>
+ Domain-level authorization scope (name or ID)
-: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-project-name` <auth-project-name> | :option:`--os-project-id` <auth-project-id>
+ Project-level authentication scope (name or ID)
-:option:`--os-username <auth-username>`
+:option:`--os-project-domain-name` <auth-project-domain-name> | :option:`--os-project-domain-id` <auth-project-domain-id>
+ Domain name or id containing project
+
+:option:`--os-username` <auth-username>
Authentication username
-:option:`--os-password <auth-password>`
+:option:`--os-user-domain-name` <auth-user-domain-name> | :option:`--os-user-domain-id` <auth-user-domain-id>
+ Domain name or id containing user
+
+:option:`--os-password` <auth-password>
Authentication password
-:option:`--os-region-name <auth-region-name>`
+:option:`--os-region-name` <auth-region-name>
Authentication region name
-:option:`--os-default-domain <auth-domain>`
+:option:`--os-default-domain` <auth-domain>
Default domain ID (Default: 'default')
-:options:`--os-use-keyring`
+:option:`--os-use-keyring`
Use keyring to store password (default: False)
-:option:`--os-cacert <ca-bundle-file>`
+:option:`--os-cacert` <ca-bundle-file>
CA certificate bundle file
-:option:`--verify|--insecure`
+:option:`--verify` | :option:`--insecure`
Verify or ignore server certificate (default: verify)
-:option:`--os-identity-api-version <identity-api-version>`
+:option:`--os-identity-api-version` <identity-api-version>
Identity API version (Default: 2.0)
-:option:`--os-XXXX-api-version <XXXX-api-version>`
- Additional API version options will be presend depending on the installed API libraries.
-
-
-NOTES
-=====
-
-[This section intentionally left blank. So there.]
+:option:`--os-XXXX-api-version` <XXXX-api-version>
+ Additional API version options will be available depending on the installed API libraries.
COMMANDS
@@ -87,7 +89,7 @@ COMMANDS
To get a list of the available commands::
- openstack -h
+ openstack --help
To get a description of a specific command::
@@ -101,12 +103,23 @@ To get a description of a specific command::
Print help for an individual command
+NOTES
+=====
+
+The command list displayed in help output reflects the API versions selected. For
+example, to see Identity v3 commands ``OS_IDENTITY_API_VERSION`` must be set to ``3``.
+
+
EXAMPLES
========
Show the detailed information for server ``appweb01``::
- openstack --os-tenant-name ExampleCo --os-username demo --os-password secrete --os-auth-url http://localhost:5000:/v2.0 server show appweb01
+ openstack \
+ --os-project-name ExampleCo \
+ --os-username demo --os-password secrete \
+ --os-auth-url http://localhost:5000:/v2.0 \
+ server show appweb01
The same command if the auth environment variables (:envvar:`OS_AUTH_URL`, :envvar:`OS_PROJECT_NAME`,
:envvar:`OS_USERNAME`, :envvar:`OS_PASSWORD`) are set::
@@ -126,25 +139,53 @@ Create a new image::
FILES
=====
- :file:`~/.openstack`
+:file:`~/.openstack`
+ Placeholder for future local state directory. This directory is intended to be shared among multiple OpenStack-related applications; contents are namespaced with an identifier for the app that owns it. Shared contents (such as :file:`~/.openstack/cache`) have no prefix and the contents must be portable.
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
-
-:envvar:`OS_PROJECT_NAME`
- Set the project name
+The following environment variables can be set to alter the behaviour of :program:`openstack`. Most of them have corresponding command-line options that take precedence if set.
:envvar:`OS_AUTH_URL`
- Set the authentication URL
+ Authentication URL
+
+:envvar:`OS_DOMAIN_NAME`
+ Domain-level authorization scope (name or ID)
+
+:envvar:`OS_PROJECT_NAME`
+ Project-level authentication scope (name or ID)
+
+:envvar:`OS_PROJECT_DOMAIN_NAME`
+ Domain name or id containing project
+
+:envvar:`OS_USERNAME`
+ Authentication username
+
+:envvar:`OS_USER_DOMAIN_NAME`
+ Domain name or id containing user
+
+:envvar:`OS_PASSWORD`
+ Authentication password
+
+:envvar:`OS_REGION_NAME`
+ Authentication region name
+
+:envvar:`OS_DEFAULT_DOMAIN`
+ Default domain ID (Default: ‘default’)
+
+:envvar:`OS_USE_KEYRING`
+ Use keyring to store password (default: False)
+
+:envvar:`OS_CACERT`
+ CA certificate bundle file
+
+:envvar:`OS_IDENTITY_API_VERISON`
+ Identity API version (Default: 2.0)
+
+:envvar:`OS_XXXX_API_VERISON`
+ Additional API version options will be available depending on the installed API libraries.
BUGS
@@ -163,7 +204,7 @@ Please refer to the AUTHORS file distributed with OpenStackClient.
COPYRIGHT
=========
-Copyright 2011-2013 OpenStack Foundation and the authors listed in the AUTHORS file.
+Copyright 2011-2014 OpenStack Foundation and the authors listed in the AUTHORS file.
LICENSE
diff --git a/doc/source/releases.rst b/doc/source/releases.rst
index 7d74318e11..34bdce62db 100644
--- a/doc/source/releases.rst
+++ b/doc/source/releases.rst
@@ -2,6 +2,25 @@
Release Notes
=============
+0.3.1 (28 Feb 2014)
+===================
+
+* add ``token create`` command
+* internal changes for Python 3.3 compatability
+* Bug 1100116_: Prompt interactive user for passwords in ``user create`` and ``user set``
+* Bug 1198171_: add domain support options for Identity v3
+* Bug 1241177_: Fix region handling in volume commands
+* Bug 1256935_: Clean up ``security group rule list`` output format
+* Bug 1269821_: Fix for unreleased Glance client change in internal class structure
+* Bug 1284957_: Correctly pass ``--cacert`` and ``--insecure`` to Identity client in token flow auth
+
+.. _1100116: https://bugs.launchpad.net/ubuntu/+source/python-keystoneclient/+bug/1100116
+.. _1198171: https://bugs.launchpad.net/keystone/+bug/1198171
+.. _1241177: https://bugs.launchpad.net/python-openstackclient/+bug/1241177
+.. _1256935: https://bugs.launchpad.net/python-openstackclient/+bug/1256935
+.. _1269821: https://bugs.launchpad.net/python-openstackclient/+bug/1269821
+.. _1284957: https://bugs.launchpad.net/python-openstackclient/+bug/1284957
+
0.3.0 (17 Dec 2013)
===================
@@ -10,10 +29,6 @@ Release Notes
* add options to support TLS cetificate verification
* add object-store show commands for container and object
-.. commented to save format of bug fix
-.. * 1254168_: OS_REGION_NAME is not used
-.. _1254168: https://bugs.launchpad.net/python-openstackclient/+bug/1254168
-
0.2.2 (20 Sep 2013)
===================