Open Stack

Hi All,

I'm replying on the mailing list here with Maria's permission, so we can
all hopefully learn together about this interesting automatic table
generation code.

So, when I look through the below email, here's my process.

1. It's a problem with the autogenerate-config-docs. Is it swift or
everything else?

Swift doesn't use oslo.config and so has its own generator with more
quirks than normal.

In this case, we're talking about a driver in cinder (which just happens
to be the swift backup driver), so we're not dealing with the swift code
(extract_swift_flags.py), but rather the main script autohelp-wrapper.

2. So, it's a flag that's missing from a table. Is that to do with the
script or not?

Sometimes, the script does interesting things with code that has certain
library dependencies - eg vendor drivers. Though, this is swift, so it's
probably not that.

Also, the option is actually being extracted successfully. This is the
key here. If the option is being retrieved and put anywhere, it's
probably not something wrong with the script.

3. Check the flag mappings

Under tools/autogenerate-config-flagmappings in the openstack-manuals
repository is where the "flag mappings" live. "Flag Mappings" are simple
text files that link an option name with the category or categories it
should live in. They're chosen by us, so we can present the most
human-friendly way of finding options possible.

Looking in cinder.flagmappings, I can see the options Maria found under
'misc':

backup_swift_auth_version swift
backup_swift_tenant swift


and other options that are in the "backups_swift" category

backup_swift_container backups_swift
...
backup_swift_user backups_swift


So what's happened here is we have some options in the category "swift"
that should probably be in "backups_swift".

4. Solve the bug

To solve this bug, what I'd do is fix the category of the options that
are in the wrong place, then regenerate the tables. In regenerating the
tables, if any tables are now empty they should be git removed, or any
new tables should be xi:included in the right spot.


I hope this was useful in walking through the process of working with
autogenerate-config-docs. Let us know if you need any further help :)



Regards,


Tom





On 24/02/15 02:32, Maria Zlatkova wrote:
> Hi Tom,
> My name is Maria and I'm working for Mirantis Inc.
> I would like to fix this bug: https://bugs.launchpad.net/openstack-
> manuals/+bug/1355475
> I have noticed that these options already exist on the following page:
> http://docs.openstack.org/trunk/config-reference/content/section_volume-
> misc.html but are missing here: http://docs.openstack.org/trunk/config-
> reference/content/swift-backup-driver.html#treeDiv
> As I've understood these tables are generated automatically, that's why
> I can't add these options into the table. But the bug is quite old
> (since August 2014) and the tables were generated January 1 (2015). So
> both options should have already been added to the table and I don't
> understand why it didn't happen.
> Could you please give me a tip on where I could add these options and
> their descriptions in order to close the bug?
> Can I add these options to this page: http://docs.openstack.org/trunk
> /config-reference/content/swift-backup-driver.html#treeDiv but not into
> the table (just as a plain text or a note)?
> 
> Thank you,
> Best regards,
> Maria
>