On 10/31/2012 07:12 PM, Lukáš Doktor wrote:
Dne 31.10.2012 18:50, Cleber Rosa napsal(a):
On 10/31/2012 09:10 AM, Lucas Meneghel Rodrigues wrote:
On 10/31/2012 07:49 AM, Lukáš Doktor wrote:
Hi guys,
Sometimes I spend time thinking about what this parameter stands for. I
think it might be good to create a database of all params + information
about that particular param and some additional information and I think
it shouldn't be that hard to make it automatic. I started by parsing
the
params and I ends-up with 749 unique params (not counting the once
ending with objects - _vm1, _image1, ...).
My idea is to create a script, which would be a part of check_patch.py.
Additionally it could generate wiki-like table which could be pasted on
github. I guess it could be split into 3 phases:
[Phase 1]
A script, which parses all files (by defaul
client/tests/virt/shared/cfg/*.cfg.sample) and tries to gather all
possible params + their values. Than it compares the output with
existing database (csv file?). In case param description is missing in
database it asks user to fill the informations. In the end it allows to
print-out wiki-like code to be able to publish the new version to
github
wiki.
The script should be able to run in non-stop mode, raising list of
errors in case of any failure and should be a part of check_patch.py.
informations: param;details;values;used
in;is_framework;group;values_check;force_perserve
param - param name
details - what the param stands for
values - list of values (grabbed from *.cfg files)
used in - in which .cfg file was this parameter set
is_framework - is this parameter used in framework or in test
(framework
params should not be changed offten.
group - to which part of framework or to which tests it's related (ex.
disk, network, virtio_console, ...)
values_check - this might be a regexp to test the values in the future
and might help user understand what is alowed (int, strin, list...)
force_perserve - keep this param even when it's not set anywhere in
*.cfg
That's one great idea! It'd make things dramatically better, as we'd
enforce documentation of the params. You also modeled the important
attributes of a param quitewell I'd say.
[Phase 2]
Modify the comments related to params in *.cfg files to be easily
parsable, ex. using double '## $param_name - $description' optionally
multiline. Than the descriptions might be automatically gathered from
cfg too.
Ok, sounds good (I'm a bit afraid that it'll render the cfg file hard
to read, but I might be over reacting).
[Phase 3]
Parse all 'params.get([^\)]*)' in tests and framework. Add informations
of where each param is used. Also check wether params are used or
should
be deleted as obsolete. Additional force_perserve tag should be
added as
not all params can be detected by parsing the source file (some params
are made of in-test variables).
It should detect params.get("$param_%s" % something) and try to guess
wether the '_%s' is object name (image, nic, usb, ...) or not.
What do you think about this idea? I guess it might help monitoring and
uniting the changes in params. As an example please find the attached
list of gathered params each with the list of values.
Terrific, let's do it :)
This is a greeeeeeat idea. Previous work (content) is available at:
https://github.com/autotest/virt-test/wiki/CartesianConfigReference
It may be better to copy and update those doc strings rather than
rewriting them.
PS: IMHO, the only thing better than this would be to write the
configuration itself in real python code, which could then be properly
and natively documented. But I'm probably ignoring its complexity.
Nice, I saw it once but was unable to find it afterwards. I'll think
about the simplest way to get to phase 3, which IMO got the right
complexity/usability ratio. I'm generally against keeping doc outside
the code/cfg itself, so we should get to the point where the info is
always there, but also available in better format (with links and
references..) It could be actually pretty similar to normal dosctring,
but it could be simplified for params...
I too think this is a great idea. There's an empty template in the virt
docs that I was going to use to categorize the parameters (e.g.
environment, pre_processor, test module, post_processor, etc.). Also,
be aware there are a good number of parameters checked in code but not
written in config. files :(
Another option, if automatically generating this is too difficult, is we
could "crowd source" it. Maybe we have a doc-week and everybody get's
to document a slice of, e.g. 25 parameters. IMHO they don't change over
time very much, so keeping the docs updated manually may not be so bad.
For the Cartesian params. that are tied to particular tests, perhaps we
can mandate some kind of docstring to be used for them w/in the test
modules. That should be easy enough to parse out and add to the
automatic or hand-drawn docs. of other params.
--
Chris Evich, RHCA, RHCE, RHCDS, RHCSS
Quality Assurance Engineer
e-mail: cevich + `@' + redhat.com o: 1-888-RED-HAT1 x44214
_______________________________________________
Autotest-kernel mailing list
[email protected]
https://www.redhat.com/mailman/listinfo/autotest-kernel
