Open Stack

On 30/08/13 23:42, Anne Gentle wrote:
>
>
>
> On Thu, Aug 29, 2013 at 7:07 PM, Tom Fifield <tom at openstack.org
> <mailto:tom at openstack.org>> wrote:
>
>     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.
>
>
> Yep, my sense of it was that this is the case for swift.
>
>     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.
>
>
> That sounds fine, but does it mean we can edit the tables or not?

Yup, feel free to go editing the help strings in the tables for swift. 
I'll update the code so that it uses them as a source of truth, and 
provided its used in update mode things should "just work".


>     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
>         <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
>         <mailto:Openstack-docs at lists.openstack.org>
>         http://lists.openstack.org/__cgi-bin/mailman/listinfo/__openstack-docs
>         <http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs>
>
>
>