openstack team mailing list archive

[Anne Gentle <anne@xxxxxxxxxxxxx>]

Thanks for starting this thread, comments below.
*Anne Gentle*
anne@xxxxxxxxxxxxx
 my blog <http://justwriteclick.com/> | my
book<http://xmlpress.net/publications/conversation-community/>|
LinkedIn <http://www.linkedin.com/in/annegentle> |
Delicious<http://del.icio.us/annegentle>|
Twitter <http://twitter.com/annegentle>
On Tue, Feb 22, 2011 at 3:11 AM, Thierry Carrez <thierry@xxxxxxxxxxxxx>wrote:

> Christian Berendt wrote:
>
> > a) we should create a useful documentation including all flags
>
>
Agreed. I have taken a few steps in this direction.

On the Docs site, this page contains all the flags, their defaults, and
descriptions.

http://docs.openstack.org/openstack-compute/admin/content/ch05s08.html

I need specific questions answered in order to make this more accurate.
1. cc_host used to be a flag. If it's not listed in the --help output any
more, is it just ignored and doesn't set anything? My guess is that it has
been replaced with all the --ec2_ flags that indicate where nova-api is
installed.
2. It appears that --fixed_range and --network_size are not listed in the
--help listing either, but had been used previously. How are these network
settings handled now?

Also, we need to organize these in logical groups and then write "how to"
sections for configuring particular scenarios with the flags. For example,
the flags you need to set for volume management and the flags you need to
set to use Glance for image storage.

Thierry (and others who are interested), please see what logical groupings
make sense to you and send them to me. I started to do this in Table 5.2 on
the Docs site (on the page linked above).


> That's been identified as a necessary area of improvement for doc. I
> plan to work on the raw info (organize them in themes and document their
> use) and Anne should help me get it into the openstack manual.
>
> It's a bit hard to keep up to date though. Ideally we would autogenerate
> it from comments in code...
>
>
Agreed here too. I also have a merge request to put the list of flags into
the RST doc site - if one more Nova core group member approves and merges
this branch there will be a list in the RST docs, but it would be better to
include that in the autodoc to keep it updated rather than a manual method.
Here's the merge request:

https://code.launchpad.net/~annegentle/nova/docslice

Thanks for the help.

Anne


>  > b) we should introduce a naming convention for new flags and we should
> > rename existing flags
> >
> > example:
> >
> > all flags related to default values are starting with "default_", all
> > flags related to a path are starting with "path_".
> >
> > Looks like most of the flags have good names at the moment, but I think
> > we should write it down in the wiki or the developer documentation to
> > reduce the possibility of bad names in the future.
>
> That's definitely something we should do, either in the RST developer
> doc or as a CodingStandards subpage in the wiki. Christian: do you take
> the lead on that ?
>
> > c) if it's possible we should collect all flags in one file
> >
> > At the moment the flags are defined in the files where they are used. I
> > think it would be nice to have on file, for example nova/flags.py,
> > including all flags used all over the code.
>
> I think there is a rationale for defining some flags locally. If not,
> I'd support placing them all in flags.py with a comment about where they
> apply, which could serve as a basis for an autogenerated doc.
>
>
+1