Open Stack

Le 2014-03-12 20:36, Steve Gordon a écrit :
> ----- Original Message -----
>> Hi!
>> 
>> This change is raising a big question: how do we handle duplication 
>> of
>> tables. Tables now have an xml:id attribute, and multiple inclusions 
>> of
>> tables make the build fail [0]. Here are a few solutions:
>> 
>> 1) find a way to include tables multiple times in the config-ref book
>> (docbook magic).
> 
> There's no real magic possible here, each element in the DOM that has
> an ID must have a *unique* ID. Including the tables twice results in
> this not being the case.
> 
>> 2) include tables in pages where they are actually needed, and add a
>> "misc options" page which includes all remaining tables.
>> 3) create a page including all the tables, and xlink from other 
>> pages.
> 
> This is my preference for consistency and to benefit maintenance. At
> the moment it's kind of difficult for the chapters that don't do this
> to work out which tables are missing because the ones that are there
> are spread around in the hierarchy. I would add that really it's a
> subset of the chapters (particularly compute and block storage) that
> aren't doing this already.
> 
>> Personally I'm OK with duplicating tables but it might be hard to get
>> this working in docbook, and even harder to convince everyone that 
>> it's
>> a good idea (based on IRC discussions) ;)
> 
> The reason I asked for IDs on these tables in the first place was so
> I could add a reference from the Libvirt/KVM hypervisor section to the
> relevant table and avoid duplicating it. I did not realize that we
> were already duplicating tables :/.
> 
>> I like solution 3 because it provides a single page with all the 
>> config
>> options, in which it's easy to search for what you need. The downside
>> (IMO) is that hyperlinks makes you jump back and forth between pages.
>> 
>> So what do you think is the best option, or is there an other one we
>> didn't think of?
> 
> I think that the problem we are having is that the config files
> driving the automation are "flat", as in the option groups are all on
> the same level:
> 
> * api
> * apiv3
> * xen
> * hyperv
> * libvirt
> * spice
> * vnc
> 
> There are some obvious logical groupings you can make here like "api
> configuration", "hypervisor configuration", and "console
> configuration". That's effectively what's being reflected in the
> manually handled hierarchy in the guide today for the minority of
> configuration groups where somebody took the time to write an overview
> of that component. I'm wonder if the solution isn't something like the
> flag mappings file for the CLI where we manually map out the hierarchy
> we expect, obviously we'd need to maintain it as new groups are added.
> 
> The script would then generate both the tables (as it does today) and
> the top level files for the book itself that link the tables into the
> hierarchy, potentially with a xi:include to a predictable location for
> the overview for that group if one was written (we would place them
> into this location) and an xi:fallback to a known small/null snippet
> to catch cases where none exists (maybe even a call to action, know
> about this section? help us write an overview!).

I think I like this option, but I'm not sure I understand it fully... 
Do you think you could provide a basic example of what you'd expect to 
see (only xi:include's and tables)?

Thanks,
Gauvain

> 
> Sounding like the rantings of a mad man I know, if I had to decide on
> what we have today I'd still say all reference tables together but I
> think the above might be something to think about if we want to solve
> the illness rather than the symptom :).
> 
> -Steve
> 
>> Le 2014-03-11 08:16, Gauvain Pocentek a écrit :
>>> Hello,
>>> Just some news about the config ref tools, what's been done and what
>>> needs to be done.
>>> I've spent some time trying to improve the autohelp.py script
>>> recently, and with the help of Andreas, Shaun and Doug (and of 
>>> course
>>> thanks to the work of the previous developers), we have now 
>>> something
>>> that works quite well.
>>> In case you've never heard of it, this script extracts configuration
>>> options from a project and generates docbook tables. There's one
>>> manual step, config options must be categorized to generate multiple
>>> tables instead of one huge table. This is done in "flagmappings" 
>>> files
>>> [0].
>>> The main projects tables are generated, but some are not used yet in
>>> the config ref (ceilometer, heat and trove). A starting point for
>>> these missing refs would be to have a big page referencing all the
>>> tables (as is done for glance). I'll try to find some time to work 
>>> on
>>> this in the next days, but if anyone wants to step in I'll be happy 
>>> to
>>> help in any way I can. There's probably some work to do on the
>>> categorization of the options too...
>>> [0]
>>> http://git.openstack.org/cgit/openstack/openstack-manuals/tree/tools/autogenerate-config-flagmappings
>>> Cheers,
>>> Gauvain
>>> Objectif Libre - Infrastructure et Formations Linux
>>> http://www.objectif-libre.com
>>> _______________________________________________
>>> Openstack-docs mailing list
>>> Openstack-docs at lists.openstack.org
>>> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
>> 
>> 
>> _______________________________________________
>> Openstack-docs mailing list
>> Openstack-docs at lists.openstack.org
>> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
>>