[libvirt] RFC version information in API docs

[Daniel P. Berrange]

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 :|