<div dir="ltr"><br><div class="gmail_extra"><br><br><div class="gmail_quote">On Thu, Aug 29, 2013 at 7:07 PM, Tom Fifield <span dir="ltr"><<a href="mailto:tom@openstack.org" target="_blank">tom@openstack.org</a>></span> wrote:<br>

<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">Apologies, I'd been meaning to write about this!<br>
<br>
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.<br>
<br>
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.<br>


<br>
<br>
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.<br>


<br></blockquote><div><br></div><div>Yep, my sense of it was that this is the case for swift.</div><div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
So I wrote some nasty scraping things (from RST and sample conf file) to seed an initial list of configuration options.<br>
<br>
My plan from here was to make the 'update' portion of the script treat the textual descriptions in common/tables/swift-*.xml as definitive.<br>
<br>
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.<br>
<br></blockquote><div><br></div><div>That sounds fine, but does it mean we can edit the tables or not? </div><div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">


I realise this is less-than-ideal, so I'd really love your feedback.<br>
<br>
<br>
Regards,<br>
<br>
<br>
Tom<div><div class="h5"><br>
<br>
<br>
On 30/08/13 04:08, Anne Gentle wrote:<br>
</div></div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div><div class="h5">
Hi all,<br>
Tom's done a pile of work on automatically documenting config info for<br>
the Configuration Reference. The latest is a scrape of the swift config<br>
info.<br>
<br>
While perusing it I'm noticing a ton of "No help text available for this<br>
option" in the swift tables. Looking closer at the code, I wonder if the<br>
scraping of the rst files could be revisited. Since the merge happened<br>
today I'm too late to comment in the review so bringing it to the list.<br>
<br>
Here's an example:<br>
read_affinity- swift/doc/source/admin_guide.<u></u>rst has examples but the<br>
code doesn't scrape it since it's not in the tables, I think. Is there<br>
an automation idea for this type of config info?<br>
<br>
I want to fix bug<br>
<a href="https://bugs.launchpad.net/openstack-manuals/+bug/1192657" target="_blank">https://bugs.launchpad.net/<u></u>openstack-manuals/+bug/1192657</a> but I'm kind<br>
of stuck unless we start manually updating tables or something.<br>
<br>
Thanks,<br>
Anne<br>
<br>
<br></div></div>
______________________________<u></u>_________________<br>
Openstack-docs mailing list<br>
<a href="mailto:Openstack-docs@lists.openstack.org" target="_blank">Openstack-docs@lists.<u></u>openstack.org</a><br>
<a href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs" target="_blank">http://lists.openstack.org/<u></u>cgi-bin/mailman/listinfo/<u></u>openstack-docs</a><br>
<br>
</blockquote>
<br>
</blockquote></div><br></div></div>