openstack-doc-core team mailing list archive

[Lorin Hochstein <lorin@xxxxxxxxxxxxxxxxxx>]

On Aug 1, 2012, at 10:29 PM, Anne Gentle <anne@xxxxxxxxxxxxx> wrote:

> Thanks for the description, Lorin, it helps.
> 
> What I find is that I'm not even sure how to a) know what version of
> nova client I'm running

The standard way of checking version in command-line tools is "--version" or "version". Of course, none of those work for the nova client. :(

I just filed a bug on this: https://bugs.launchpad.net/python-novaclient/+bug/1033567

If you've installed via package manager (which should be the common case), you can check that way, but each one is totally different.  If you used pip, for example, do:

$ pip freeze | grep python-novaclient
python-novaclient==2.6.10

On Ubuntu, you can use dpkg  or aptitude, for example:

$ dpkg -s python-novaclient
Package: python-novaclient
Status: install ok installed
Priority: optional
Section: python
Installed-Size: 288
Maintainer: Ubuntu Developers <ubuntu-devel-discuss@xxxxxxxxxxxxxxxx>
Architecture: all
Version: 2012.1-0ubuntu1
Depends: python2.7, python (>= 2.7.1-0ubuntu2), python (<< 2.8), python-httplib2, python-prettytable, python-pkg-resources, python-argparse
Description: client library for OpenStack Compute API
 Python novaclient library and nova CLI tool for interacting with OpenStack
 Compute (Nova) through the OpenStack Compute API.
Python-Version: 2.7

Of course, none of these are obvious, and you'll note that the versioning is completely different (2.6.10 versus 2012.1). So, it's basically a mess.



> and b) how to update it so I can trust the
> --help or man page. I'm backwards that way. :)
> 

I think the --help and man pages will need to have a pointer to a URL which has details about how to do this.

> 
> Lastly, work on updating the documentation that Google finds -
> however, does that mean updating python-novaclient,
> python-swiftclient, etc? Or are those projects not where we want to
> place CLI documentation specifically?
> 

I think the fact that the client apps are maintained as separate projects from the server apps is a project management detail that doesn't need to be exposed to the user that way. I'd vote for integrating them with the existing docs to make them as easy as possible to find.  Maybe a "User's Guide" on docs.openstack.org? The equivalent of man pages would be here, but it would also have documentation structured around tasks, like:

- How do I authenticate against OpenStack?
- How do I run an instance?
- How do I save a running instance to an image?
- How do I attach a volume?




Take care,

Lorin
--
Lorin Hochstein
Lead Architect - Cloud Services
Nimbis Services, Inc.
www.nimbisservices.com