[libvirt] RFC version information in API docs
Hi. Sometimes, it's a bit hard to determine when exactly a function, flag or macro appeared in libvirt, ie. whether it will be supported on my target machine having a specific version of libvirt or not. So, I have created an enriched version of the API docs, using a XSL stylesheet enumerating the libvirt?-api.xml files of all libvirt releases. For an example, you can have a look here: http://avdv.github.io/libvirt/html/libvirt-libvirt.html#virVcpuState Hovering over an enum value displays version information in a tooltip. What do you think? Should this information be included by default in the API docs? If so, I could use a little help on how to integrate the generation of this information into the automake process. Basically, the XSL stylesheet enriches the generated libvirt-api.xml with the current version given as a parameter to xsltproc plus version information gathered from a previous enriched libvirt-api.xml file. That way, every symbol/node() gets a since="..." version attribute. So, during a build there's an extra step necessary when generating the libvirt-api.xml file: 1. apibuild.py => libvirt-api.1.xml 2. (libvirt-api.1.xml + libvirt-api.0.xml) => XSLT => libvirt-api.xml When releasing, libvirt-api.xml should be moved to libvirt-api.0.xml. Alternatively, there could be a second XSL file only extracting the version information without the boilerplate. Claudio -- AV-Test GmbH, Henricistraße 20, 04155 Leipzig, Germany Phone: +49 341 265 310 19 Web:<http://www.av-test.org> Eingetragen am / Registered at: Amtsgericht Stendal (HRB 114076) Geschaeftsfuehrer (CEO): Andreas Marx, Guido Habicht, Maik Morgenstern
On Mon, May 13, 2013 at 02:30:41PM +0200, Claudio Bley wrote:
Hi.
Sometimes, it's a bit hard to determine when exactly a function, flag or macro appeared in libvirt, ie. whether it will be supported on my target machine having a specific version of libvirt or not.
So, I have created an enriched version of the API docs, using a XSL stylesheet enumerating the libvirt?-api.xml files of all libvirt releases.
For an example, you can have a look here:
http://avdv.github.io/libvirt/html/libvirt-libvirt.html#virVcpuState
Hovering over an enum value displays version information in a tooltip.
What do you think? Should this information be included by default in the API docs?
The version an API appeared is not always that useful - since you typically need to know what version a hypervisor driver supported it in. Do you know about this page which shows the version matrix for APIs + drivers: http://libvirt.org/hvsupport.html Daniel -- |: http://berrange.com -o- http://www.flickr.com/photos/dberrange/ :| |: http://libvirt.org -o- http://virt-manager.org :| |: http://autobuild.org -o- http://search.cpan.org/~danberr/ :| |: http://entangle-photo.org -o- http://live.gnome.org/gtk-vnc :|
At Mon, 13 May 2013 13:39:53 +0100, Daniel P. Berrange wrote:
On Mon, May 13, 2013 at 02:30:41PM +0200, Claudio Bley wrote:
Hi.
Sometimes, it's a bit hard to determine when exactly a function, flag or macro appeared in libvirt, ie. whether it will be supported on my target machine having a specific version of libvirt or not.
So, I have created an enriched version of the API docs, using a XSL stylesheet enumerating the libvirt?-api.xml files of all libvirt releases.
For an example, you can have a look here:
http://avdv.github.io/libvirt/html/libvirt-libvirt.html#virVcpuState
Hovering over an enum value displays version information in a tooltip.
What do you think? Should this information be included by default in the API docs?
The version an API appeared is not always that useful - since you typically need to know what version a hypervisor driver supported it in.
Yeah, maybe it's a special use case, but when wrapping libvirt functions in Java, I'm interested in the exact version, e.g. to see what's still missing.
Do you know about this page which shows the version matrix for APIs + drivers:
Yes, but this list is just to overwhelming, I'm almost getting headaches when reading it... ;) Having to switch back and forth between html/libvirt-libvirt.html and searching in this page is not exactly comfortable by any manner of means. It's also a lot easier to answer "Which functions where introduced in version x.y.z?" querying the (enriched) libvirt-api.xml than looking it up in this matrix. But, maybe interlinking these two pages would be sufficient. On-line filtering by libvirt version and driver support would be even better. What do you think? Claudio -- AV-Test GmbH, Henricistraße 20, 04155 Leipzig, Germany Phone: +49 341 265 310 19 Web:<http://www.av-test.org> Eingetragen am / Registered at: Amtsgericht Stendal (HRB 114076) Geschaeftsfuehrer (CEO): Andreas Marx, Guido Habicht, Maik Morgenstern
On Mon, May 13, 2013 at 03:04:40PM +0200, Claudio Bley wrote:
At Mon, 13 May 2013 13:39:53 +0100, Daniel P. Berrange wrote:
On Mon, May 13, 2013 at 02:30:41PM +0200, Claudio Bley wrote:
Hi.
Sometimes, it's a bit hard to determine when exactly a function, flag or macro appeared in libvirt, ie. whether it will be supported on my target machine having a specific version of libvirt or not.
So, I have created an enriched version of the API docs, using a XSL stylesheet enumerating the libvirt?-api.xml files of all libvirt releases.
For an example, you can have a look here:
http://avdv.github.io/libvirt/html/libvirt-libvirt.html#virVcpuState
Hovering over an enum value displays version information in a tooltip.
What do you think? Should this information be included by default in the API docs?
The version an API appeared is not always that useful - since you typically need to know what version a hypervisor driver supported it in.
Yeah, maybe it's a special use case, but when wrapping libvirt functions in Java, I'm interested in the exact version, e.g. to see what's still missing.
FWIW, rather than doing it manually I'd recommend that you create a script which extracts a list of all APIs currently implemented by the java bindings, and then match it against the list of APIs exported in /usr/share/libvirt/api/libvirt-api.xml That's how I validate that the Perl bindings has 100% coverage of all current libvirt APIs: http://libvirt.org/git/?p=libvirt-perl.git;a=blob;f=t/030-api-coverage.t;hb=...
Do you know about this page which shows the version matrix for APIs + drivers:
Yes, but this list is just to overwhelming, I'm almost getting headaches when reading it... ;)
Having to switch back and forth between html/libvirt-libvirt.html and searching in this page is not exactly comfortable by any manner of means.
It's also a lot easier to answer "Which functions where introduced in version x.y.z?" querying the (enriched) libvirt-api.xml than looking it up in this matrix.
But, maybe interlinking these two pages would be sufficient.
On-line filtering by libvirt version and driver support would be even better. What do you think?
I think what would be best is to get the full set of driver support version numbers into the API docs. Daniel -- |: http://berrange.com -o- http://www.flickr.com/photos/dberrange/ :| |: http://libvirt.org -o- http://virt-manager.org :| |: http://autobuild.org -o- http://search.cpan.org/~danberr/ :| |: http://entangle-photo.org -o- http://live.gnome.org/gtk-vnc :|
On Mon, May 13, 2013 at 02:30:41PM +0200, Claudio Bley wrote:
Hi.
Sometimes, it's a bit hard to determine when exactly a function, flag or macro appeared in libvirt, ie. whether it will be supported on my target machine having a specific version of libvirt or not.
So, I have created an enriched version of the API docs, using a XSL stylesheet enumerating the libvirt?-api.xml files of all libvirt releases.
For an example, you can have a look here:
http://avdv.github.io/libvirt/html/libvirt-libvirt.html#virVcpuState
Hovering over an enum value displays version information in a tooltip.
What do you think? Should this information be included by default in the API docs?
Sounds a rather good idea to me, adding an extra attribute for each entry should not break anything. But I don't understand why you would need a libvirt-api-0.xml and libvirt-api-1.xml. Daniel -- Daniel Veillard | Open Source and Standards, Red Hat veillard@redhat.com | libxml Gnome XML XSLT toolkit http://xmlsoft.org/ http://veillard.com/ | virtualization library http://libvirt.org/
At Mon, 13 May 2013 21:17:35 +0800, Daniel Veillard wrote:
On Mon, May 13, 2013 at 02:30:41PM +0200, Claudio Bley wrote:
Hi.
Sometimes, it's a bit hard to determine when exactly a function, flag or macro appeared in libvirt, ie. whether it will be supported on my target machine having a specific version of libvirt or not.
So, I have created an enriched version of the API docs, using a XSL stylesheet enumerating the libvirt?-api.xml files of all libvirt releases.
For an example, you can have a look here:
http://avdv.github.io/libvirt/html/libvirt-libvirt.html#virVcpuState
Hovering over an enum value displays version information in a tooltip.
What do you think? Should this information be included by default in the API docs?
Sounds a rather good idea to me, adding an extra attribute for each entry should not break anything. But I don't understand why you would need a libvirt-api-0.xml and libvirt-api-1.xml.
Since apibuild.py always generates a fresh libvirt-api file, version information for all symbols will be lost. So, I need to keep the info somewhere else; merging the information for the old and newly added symbols into the final libvirt-api.xml. At least, that's how it'd work using the stylesheet I put together for that matter. For the sake of completeness, here's the XSL stylesheet: <xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform"> <xsl:output method="xml" indent="yes" encoding="ISO-8859-1" cdata-section-elements="info" /> <!-- the current version of the libvirt API --> <xsl:param name="version"/> <!-- build up a lookup table for existing symbols from an older --> <!-- libvirt-api.xml file. Any newly introduced symbols are then --> <!-- tagged with a since="$version" attribute. --> <xsl:variable name="symbols" select="document('libvirt-api.0.xml')/api/symbols/*"/> <xsl:template match="/api/symbols/node()"> <xsl:variable name="name" select="string(@name)"/> <xsl:copy> <xsl:apply-templates select="@*"/> <xsl:attribute name="since"> <xsl:choose> <xsl:when test="not($symbols[@name = $name])"> <xsl:value-of select="$version"/> </xsl:when> <xsl:otherwise> <xsl:value-of select="$symbols[@name = $name]/@since"/> </xsl:otherwise> </xsl:choose> </xsl:attribute> <xsl:apply-templates select="node()"/> </xsl:copy> </xsl:template> <xsl:template match="node() | @*"> <xsl:copy> <xsl:apply-templates select="@*"/> <xsl:apply-templates select="node()"/> </xsl:copy> </xsl:template> </xsl:stylesheet> Alternatively, we could just as well do this directly in apibuild.py, but this requires version information in, say, apiversion.py which I could generate using the enriched libvirt-api.xml. Claudio -- AV-Test GmbH, Henricistraße 20, 04155 Leipzig, Germany Phone: +49 341 265 310 19 Web:<http://www.av-test.org> Eingetragen am / Registered at: Amtsgericht Stendal (HRB 114076) Geschaeftsfuehrer (CEO): Andreas Marx, Guido Habicht, Maik Morgenstern
On Mon, May 13, 2013 at 04:44:00PM +0200, Claudio Bley wrote:
At Mon, 13 May 2013 21:17:35 +0800, Daniel Veillard wrote:
On Mon, May 13, 2013 at 02:30:41PM +0200, Claudio Bley wrote:
Hi.
Sometimes, it's a bit hard to determine when exactly a function, flag or macro appeared in libvirt, ie. whether it will be supported on my target machine having a specific version of libvirt or not.
So, I have created an enriched version of the API docs, using a XSL stylesheet enumerating the libvirt?-api.xml files of all libvirt releases.
For an example, you can have a look here:
http://avdv.github.io/libvirt/html/libvirt-libvirt.html#virVcpuState
Hovering over an enum value displays version information in a tooltip.
What do you think? Should this information be included by default in the API docs?
Sounds a rather good idea to me, adding an extra attribute for each entry should not break anything. But I don't understand why you would need a libvirt-api-0.xml and libvirt-api-1.xml.
Since apibuild.py always generates a fresh libvirt-api file, version information for all symbols will be lost.
So, I need to keep the info somewhere else; merging the information for the old and newly added symbols into the final libvirt-api.xml.
At least, that's how it'd work using the stylesheet I put together for that matter.
For the sake of completeness, here's the XSL stylesheet:
<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
<xsl:output method="xml" indent="yes" encoding="ISO-8859-1" cdata-section-elements="info" />
<!-- the current version of the libvirt API --> <xsl:param name="version"/>
<!-- build up a lookup table for existing symbols from an older --> <!-- libvirt-api.xml file. Any newly introduced symbols are then --> <!-- tagged with a since="$version" attribute. --> <xsl:variable name="symbols" select="document('libvirt-api.0.xml')/api/symbols/*"/>
<xsl:template match="/api/symbols/node()"> <xsl:variable name="name" select="string(@name)"/>
<xsl:copy> <xsl:apply-templates select="@*"/> <xsl:attribute name="since"> <xsl:choose> <xsl:when test="not($symbols[@name = $name])"> <xsl:value-of select="$version"/> </xsl:when> <xsl:otherwise> <xsl:value-of select="$symbols[@name = $name]/@since"/> </xsl:otherwise> </xsl:choose> </xsl:attribute> <xsl:apply-templates select="node()"/> </xsl:copy> </xsl:template>
<xsl:template match="node() | @*"> <xsl:copy> <xsl:apply-templates select="@*"/> <xsl:apply-templates select="node()"/> </xsl:copy> </xsl:template>
</xsl:stylesheet>
Alternatively, we could just as well do this directly in apibuild.py, but this requires version information in, say, apiversion.py which I could generate using the enriched libvirt-api.xml.
What we should do is this - Take the bit of hvsupport.pl which extracts the version data for each API and make it generate a libvirt-api-versions.xml file - Make hvsupport.pl read data from that XML file when generating the HTML - Make apibuild.py read data from that XML file when generating the API XML files, and include this version data into the libvirt-api.xml files Daniel -- |: http://berrange.com -o- http://www.flickr.com/photos/dberrange/ :| |: http://libvirt.org -o- http://virt-manager.org :| |: http://autobuild.org -o- http://search.cpan.org/~danberr/ :| |: http://entangle-photo.org -o- http://live.gnome.org/gtk-vnc :|
participants (3)
-
Claudio Bley -
Daniel P. Berrange -
Daniel Veillard