Skip to content

Commit 649dbf1

Browse files
author
Dean Troyer
committed
Update README
Re-orient README toward end-users Change-Id: I4623832dde72a7ae0eeadf09429402521771dd35
1 parent 8f7e0ef commit 649dbf1

1 file changed

Lines changed: 28 additions & 80 deletions

File tree

‎README.rst‎

Lines changed: 28 additions & 80 deletions
Original file line numberDiff line numberDiff line change
@@ -1,41 +1,28 @@
1-
================
2-
OpenStack Client
3-
================
4-
5-
OpenStack Client (aka ``python-openstackclient``) is a command-line client for
6-
the OpenStack APIs.
7-
It is primarily a wrapper to the stock python-\*client modules that implement the
8-
actual REST API client actions.
9-
10-
This is an implementation of the design goals shown in
11-
`OpenStack Client Wiki`_. The primary goal is to provide
12-
a unified shell command structure and a common language to describe
13-
operations in OpenStack. The master repository is on GitHub_.
14-
15-
.. _OpenStack Client Wiki: https://wiki.openstack.org/wiki/OpenStackClient
16-
.. _GitHub: https://github.com/openstack/python-openstackclient
17-
18-
OpenStack Client has a plugin mechanism to add support for API extensions.
19-
20-
* `Release management`_
21-
* `Blueprints and feature specifications`_
22-
* `Issue tracking`_
23-
* `PyPi`_
24-
* `Developer Docs`_
25-
26-
.. _release management: https://launchpad.net/python-openstackclient
27-
.. _Blueprints and feature specifications: https://blueprints.launchpad.net/python-openstackclient
28-
.. _Issue tracking: https://bugs.launchpad.net/python-openstackclient
29-
.. _PyPi: https://pypi.python.org/pypi/python-openstackclient
30-
.. _Developer Docs: http://docs.openstack.org/developer/python-openstackclient/
31-
.. _install virtualenv: tools/install_venv.py
1+
===============
2+
OpenStackClient
3+
===============
4+
5+
OpenStackClient (aka OSC) is a command-line client for OpenStack that brings
6+
the command set for Compute, Identity, Image, Object Store and Volume APIs
7+
together in a single shell with a uniform command structure.
8+
9+
The primary goal is to provide a unified shell command structure and a common
10+
language to describe operations in OpenStack.
3211

33-
Note
34-
====
12+
* `PyPi`_ - package installation
13+
* `Online Documentation`_
14+
* `Launchpad project`_ - release management
15+
* `Blueprints`_ - feature specifications
16+
* `Bugs`_ - issue tracking
17+
* `Source`_
18+
* License: Apache 2.0
3519

36-
OpenStackClient is considered to be beta release quality as of the 0.3 release;
37-
no assurances are made at this point for ongoing compatibility in command forms
38-
or output. We do not, however, expect any major changes at this point.
20+
.. _PyPi: https://pypi.python.org/pypi/python-openstackclient
21+
.. _Online Documentation: http://docs.openstack.org/developer/python-openstackclient/
22+
.. _Launchpad project: https://launchpad.net/python-openstackclient
23+
.. _Blueprints: https://blueprints.launchpad.net/python-openstackclient
24+
.. _Bugs: https://bugs.launchpad.net/python-openstackclient
25+
.. _Source: https://git.openstack.org/cgit/openstack/python-openstackclient
3926

4027
Getting Started
4128
===============
@@ -44,19 +31,6 @@ OpenStack Client can be installed from PyPI using pip::
4431

4532
pip install python-openstackclient
4633

47-
Developers can use the `install virtualenv`_ script to create the virtualenv::
48-
49-
python tools/install_venv.py
50-
source .venv/bin/activate
51-
python setup.py develop
52-
53-
Unit tests are now run using tox. The ``run_test.sh`` script provides compatibility
54-
but is generally considered deprecated.
55-
56-
The client can be called interactively by simply typing::
57-
58-
openstack
59-
6034
There are a few variants on getting help. A list of global options and supported
6135
commands is shown with ``--help``::
6236

@@ -72,26 +46,26 @@ Configuration
7246
=============
7347

7448
The CLI is configured via environment variables and command-line
75-
options as listed in https://wiki.openstack.org/wiki/OpenStackClient/Authentication.
49+
options as listed in http://docs.openstack.org/developer/python-openstackclient/authentication.html.
7650

77-
The 'password flow' variation is most commonly used::
51+
Authentication using username/password is most commonly used::
7852

7953
export OS_AUTH_URL=<url-to-openstack-identity>
8054
export OS_PROJECT_NAME=<project-name>
81-
export OS_USERNAME=<user-name>
55+
export OS_USERNAME=<username>
8256
export OS_PASSWORD=<password> # (optional)
8357

8458
The corresponding command-line options look very similar::
8559

8660
--os-auth-url <url>
8761
--os-project-name <project-name>
88-
--os-username <user-name>
62+
--os-username <username>
8963
[--os-password <password>]
9064

9165
If a password is not provided above (in plaintext), you will be interactively
9266
prompted to provide one securely.
9367

94-
The token flow variation for authentication uses an already-acquired token
68+
Authentication may also be performed using an already-acquired token
9569
and a URL pointing directly to the service API that presumably was acquired
9670
from the Service Catalog::
9771

@@ -102,29 +76,3 @@ The corresponding command-line options look very similar::
10276

10377
--os-token <token>
10478
--os-url <url-to-openstack-service>
105-
106-
Additional command-line options and their associated environment variables
107-
are listed here::
108-
109-
--debug # turns on some debugging of the API conversation
110-
--verbose | -v # Increase verbosity of output. Can be repeated.
111-
--quiet | -q # suppress output except warnings and errors
112-
--help | -h # show a help message and exit
113-
114-
Building Documentation
115-
======================
116-
117-
This documentation is written by contributors, for contributors.
118-
119-
The source is maintained in the ``doc/source`` folder using
120-
`reStructuredText`_ and built by `Sphinx`_
121-
122-
.. _reStructuredText: http://docutils.sourceforge.net/rst.html
123-
.. _Sphinx: http://sphinx.pocoo.org/
124-
125-
Building Manually::
126-
127-
cd doc
128-
make html
129-
130-
Results are in the ``build/html`` directory.

0 commit comments

Comments
 (0)