openstack-doc-core team mailing list archive

[Anne Gentle <anne@xxxxxxxxxxxxx>]

On Mon, Aug 6, 2012 at 11:40 AM, Lorin Hochstein
<lorin@xxxxxxxxxxxxxxxxxx>wrote:

>
> 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.
>
>
>
OMGWTFBBQ. :) Wow thank you for outlining the mess and logging a bug.

Hm. I documented it with "pip install" in the "Quick Start" and that's how
I have it installed locally. Then, I never remember it's 'yolk -l | grep
"nova"' to find the version. Nuts! Is it pypi that's the "official"
packaging and versioning? Or should we be only documenting what's in a
particular distro?


> 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?
>
>
>
Really like this idea. I had a suggested outline from Anthony Young a few
months back that I analyzed to see which topics/sections were still
missing. It's here:
https://docs.google.com/a/justwriteclick.com/spreadsheet/ccc?key=0Ar7TiePyvTNVdF9hSC1ENEM5Yi1kM0RKNEoxX3l3RVE#gid=0

and anyone can edit, and I've added the last two "How do I?s" to this
outline.


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