Open Stack

Apologies, I'd been meaning to write about this!

Backstory: All projects other than Swift use OpenStack Common for 
configuration, and define option, default value and help text in the 
code in a way that it's possible to extract.

Since the code is able to act in this way, we can stop maintaining 
separate instructive lines for configuration options, and instead fix 
any text problems in the code itself. This both improves the quality of 
the code and fixes our double maintenance problem.


For swift, we needed a different approach. Unfortunately, I think we 
don't have the ability to treat the code as the definitive source and 
move all maintenance there. The lack of instruction for every option, 
and absence of structure precludes this.

So I wrote some nasty scraping things (from RST and sample conf file) to 
seed an initial list of configuration options.

My plan from here was to make the 'update' portion of the script treat 
the textual descriptions in common/tables/swift-*.xml as definitive.

The script would still search the swift code to add or remove options, 
so we could guarantee completeness, and after an initial push to write 
out proper help text the maintenance becomes far simpler.

I realise this is less-than-ideal, so I'd really love your feedback.


Regards,


Tom


On 30/08/13 04:08, Anne Gentle wrote:
> Hi all,
> Tom's done a pile of work on automatically documenting config info for
> the Configuration Reference. The latest is a scrape of the swift config
> info.
>
> While perusing it I'm noticing a ton of "No help text available for this
> option" in the swift tables. Looking closer at the code, I wonder if the
> scraping of the rst files could be revisited. Since the merge happened
> today I'm too late to comment in the review so bringing it to the list.
>
> Here's an example:
> read_affinity- swift/doc/source/admin_guide.rst has examples but the
> code doesn't scrape it since it's not in the tables, I think. Is there
> an automation idea for this type of config info?
>
> I want to fix bug
> https://bugs.launchpad.net/openstack-manuals/+bug/1192657 but I'm kind
> of stuck unless we start manually updating tables or something.
>
> Thanks,
> Anne
>
>
> _______________________________________________
> Openstack-docs mailing list
> Openstack-docs at lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
>