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
This commit is contained in:
Dean Troyer 2013-07-29 17:05:02 -05:00
parent 22386eb9e6
commit 6f9dcc13f6
9 changed files with 315 additions and 155 deletions

122
HACKING
View File

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

106
HACKING.rst Normal file
View File

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

View File

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

View File

@ -2,33 +2,50 @@
Commands
========
Command Structure
=================
OpenStack Client uses a command form ``verb object``.
Note that 'object' here refers to the target of a command's action. In coding
discussions 'object' has its usual Python meaning. Go figure.
OpenStackClient has a consistent and predictable format for all of its commands.
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
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
option takes priority. The environment variable names can be derived from
the option name by dropping the leading '--', converting all embedded dashes
('-') 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
as positional arguments. If they also appear in the command object they are
in the same order.
Global Options
--------------
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.
For example, ``--os-username`` can be set from the environment via ``OS_USERNAME``.
Command Object(s) and Action
----------------------------
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
--------------------

View File

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

View File

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

View File

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

View File

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

View File

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