Open Stack

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