[Openstack-docs] Group info in autogenerated config reference

Shaun McCance shaunm at gnome.org
Sat Jan 18 14:25:41 UTC 2014


On Sat, 2014-01-18 at 07:49 -0600, Anne Gentle wrote:
> I'm leaning towards a full row for [DEFAULT] and other sections, like
> Andreas describes. Then the filename itself is clear because it's
> grouped in a table. 

I agree. I don't know why I didn't think of doing it that way.

> One design oddity that sticks out is, why are there groupings if
> they're not also logically in a single table anyway? Are devs picking
> poor groupings or are there too many items in DEFAULT? I ask because I
> would think the groupings would help with the mappings.

In some cases, it could be that we've categorized poorly. Which options
go into which tables is entirely on our end. We might get some wrong.
But I think there's also inconsistency in whether developers even use
groups. When you have so many people working on a code base so large
with so many options, that's bound to happen.

Having the group in the flagmappings has made it easier for me to pick
categories though. And it helps to point out possible inconsistencies.
For example, the only [database] option in nova that isn't "db" is
use_tpool. Is that right? I don't know. But I never would have even
noticed without the group info. 


> Thanks for asking Shaun!
> Anne
> 
> 
> 
> 
> 
> 
> On Sat, Jan 18, 2014 at 2:13 AM, Andreas Jaeger <aj at suse.com> wrote:
>         On 01/17/2014 09:58 PM, Shaun McCance wrote:
>         > I've been doing a lot of work on the autohelp.py script that
>         generates
>         > our reference tables of configuration options. One of the
>         problems it
>         > had was that it couldn't distinguish between options with
>         the same name
>         > in different groups. For example, these are both options in
>         nova:
>         >
>         > [spice]
>         > enabled = False
>         >
>         > [osapi_v3]
>         > enabled = False
>         >
>         > The old code would duplicate these, putting the reference
>         for both of
>         > them in both nova-spice.xml and nova-apiv3.xml. I've fixed
>         that.
>         >
>         > But the DocBook still doesn't specify the group, which is a
>         pretty
>         > important piece of information to have. I'm trying to think
>         of a good
>         > way to add it, and I'd like feedback. Currently we have:
>         >
>         > <td>option = default</td><td>help string</td>
>         >
>         > We could do
>         >
>         > <td><programlisting>[group]
>         > option = default</td><td>help string</td>
>         >
>         > That's a pretty good indication of how you'd actually write
>         the config
>         > file, but it makes the tables longer. We could do
>         >
>         > <td>[group]</td><td>option = default</td><td>help
>         string</td>
>         >
>         > That makes the tables wider, and/or gives less space to the
>         help string.
>         > Or we could write out separate tables for anything that's in
>         a group
>         > other than DEFAULT, and put the group name in the caption.
>         >
>         > Thoughts?
>         
>         
>         I would do it similar to how the conf files look like, for
>         example for
>         this snippet
>         [DEFAULT]
>         option1 = text
>         [database]
>         connection= text
>         
>         This would be:
>         <th>
>         <tr>
>         <td>option = default</td><td>help string</td>
>         
>         </tr>
>         </th>
>         <tbody>
>         <tr>
>         <th colspan="2"><code>[DEFAULT]</code></th></tr>
>         <tr>
>         <td>option1 = text</td><td>Explanation</td>
>         </tr>
>         <th colspan="2"><code>[database]</code></th></tr>
>         <tr>connection = text...
>         
>         So, use a separate header line for each new section,
>         
>         Andreas
>         --
>          Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica:
>         jaegerandi
>           SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 Nürnberg,
>         Germany
>            GF: Jeff Hawn,Jennifer Guild,Felix Imendörffer,HRB16746 (AG
>         Nürnberg)
>             GPG fingerprint = 93A3 365E CE47 B889 DF7F  FED1 389A 563C
>         C272 A126
>         
>         _______________________________________________
>         Openstack-docs mailing list
>         Openstack-docs at lists.openstack.org
>         http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
>         
> 
> 
> _______________________________________________
> Openstack-docs mailing list
> Openstack-docs at lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs





More information about the Openstack-docs mailing list