[libvirt] RFC version information in API docs

[Claudio Bley]

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