[libvirt] Update libvirt API and refs XML files

[Daniel Veillard]

On Fri, Oct 02, 2009 at 12:16:36PM +0100, Daniel P. Berrange wrote:
> On Thu, Oct 01, 2009 at 01:33:50PM +0200, Daniel Veillard wrote:
> > On Thu, Oct 01, 2009 at 12:32:51PM +0200, Chris Lalancette wrote:
> > > Matthias Bolte wrote:
> > > > Commit 47c8709564ac3f2ec5b4a3830ac213e69b4a44d5 "Fix up a few typos in
> > > > the tree" triggered changes in docs/libvirt-api.xml and
> > > > docs/libvirt-refs.xml. The attached patch contains this changes.
> > > > 
> > > > The files docs/libvirt-api.xml and docs/libvirt-refs.xml are generated
> > > > by apibuild.py, why are this generated files under version control?
> > > 
> > > Yeah, I've been running into this too.  I think we should remove those files
> > > from version control, personally.
> > 
> >   I don't care about docs/libvirt-refs.xml, but I would prefer to keep
> > docs/libvirt-api.xml in the tree for the reasons exposed during the big
> > reshuffling.
> >   The problem is that now this is systematically rebuilt on make
> > while it used to be rebuilt only on a specific "make rebuild" target
> > in doc, this was done for example on "make dist", this is why so many
> > people start to see diffs.
> 
> There's a couple of problems here
> 
> I did not intentionally change it to be re-generated everytime, but it
> is being done as a side-effect of building the HTML files. ie the
> html/index.html file which is the website page for the API, has a 
> dependancy on libvirt-api.xml, so make checks if it is up2date and if
> not regenerates the API file. 

  IMHO there is no need to regenerate the web site all the time either
Only when we know there is a documentation change or a real API
addition.

> The second issue is a bug in apibuild.py which tries to sort the 
> element in the XML file, but after calling sort() in the list, it
> then calls uniq() which messes up sorting again. So the XML file 
> ends up different everytime anyone builds it.

  hum, that should be fixed,

> Even without that bug we constantly see changes which cause the
> re-generation of this file - eg when commiting new APIs like 
> Chris' migration ones people always forget to manually re-generate
> the XML file before commiting. Or when fixing typos in the libvirt.c
> function comments, etc people forget to re-generate.  This really
> says to me that we should not be storing this XML file in GIT, since
> every one of us constantly forgets to update it manually.

  Well it's not about forgetting, it's that usually this is not
immediately needed, and if needed "cd docs ; make rebuild" was
simple enough. I was doing that when needed, and it wasn't affecting
the majority of the people developping patches.

> >   I would really prefer to go back to the old way of only building it
> > when needed instead of systematically, this would avoid the problem
> > most people are facing while still allow me to monitor closely changes
> > to the generated API.
> 
> Changes in this libvirt-api.xml file don't have any impact of the API
> or ABI. It is just a side-effect of changes to the real important
> API files of include/libvirt/libvirt.h, and src/libvirt.c 

  It change the way we present the docs on the web site and the
python bindings, but ultimately it is good for me to have a single
resource to check, for example when getting ready to push a release.

Daniel

-- 
Daniel Veillard      | libxml Gnome XML XSLT toolkit  http://xmlsoft.org/
daniel at veillard.com  | Rpmfind RPM search engine http://rpmfind.net/
http://veillard.com/ | virtualization library  http://libvirt.org/