[libvirt] [PATCH] Fix API docs for header file re-organization

Daniel P. Berrange berrange at redhat.com
Wed Nov 12 15:00:36 UTC 2014


The API docs generators were broken by the header file
re-organization. Specifically

 * html/libvirt-libvirt.html was empty (and should be deleted)
 * Makefile.am didn't install html/libvirt-libvirt-*.html
 * hvsupport.html was mostly empty
 * sitemap.html.in didn't list the new html/*.html files
---
 docs/Makefile.am     |  17 +++++++--
 docs/apibuild.py     |   1 -
 docs/hvsupport.pl    | 101 +++++++++++++++++++++++++++++----------------------
 docs/sitemap.html.in |  48 ++++++++++++++++++++++--
 4 files changed, 115 insertions(+), 52 deletions(-)

diff --git a/docs/Makefile.am b/docs/Makefile.am
index 9de3406..910bfef 100644
--- a/docs/Makefile.am
+++ b/docs/Makefile.am
@@ -25,9 +25,20 @@ DOC_SOURCE_DIR=../src
 
 DEVHELP_DIR=$(datadir)/gtk-doc/html/libvirt
 
-apihtml =			\
-  html/index.html		\
-  html/libvirt-libvirt.html	\
+apihtml =					\
+  html/index.html				\
+  html/libvirt-libvirt-domain.html		\
+  html/libvirt-libvirt-domain-snapshot.html	\
+  html/libvirt-libvirt-event.html		\
+  html/libvirt-libvirt-host.html		\
+  html/libvirt-libvirt.html			\
+  html/libvirt-libvirt-interface.html		\
+  html/libvirt-libvirt-network.html		\
+  html/libvirt-libvirt-nodedev.html		\
+  html/libvirt-libvirt-nwfilter.html		\
+  html/libvirt-libvirt-secret.html		\
+  html/libvirt-libvirt-storage.html		\
+  html/libvirt-libvirt-stream.html		\
   html/libvirt-virterror.html
 
 apipng =	\
diff --git a/docs/apibuild.py b/docs/apibuild.py
index 797a7a5..7549a63 100755
--- a/docs/apibuild.py
+++ b/docs/apibuild.py
@@ -21,7 +21,6 @@ debugsym=None
 # C parser analysis code
 #
 included_files = {
-  "libvirt.h": "header with general libvirt API definitions",
   "libvirt-domain.h": "header with general libvirt API definitions",
   "libvirt-domain-snapshot.h": "header with general libvirt API definitions",
   "libvirt-event.h": "header with general libvirt API definitions",
diff --git a/docs/hvsupport.pl b/docs/hvsupport.pl
index 6d8ed9c..96720eb 100755
--- a/docs/hvsupport.pl
+++ b/docs/hvsupport.pl
@@ -12,7 +12,17 @@ my $srcdir = shift @ARGV;
 my $symslibvirt = "$srcdir/libvirt_public.syms";
 my $symsqemu = "$srcdir/libvirt_qemu.syms";
 my $symslxc = "$srcdir/libvirt_lxc.syms";
-my $drivertable = "$srcdir/driver.h";
+my @drivertable = (
+    "$srcdir/driver-hypervisor.h",
+    "$srcdir/driver-interface.h",
+    "$srcdir/driver-network.h",
+    "$srcdir/driver-nodedev.h",
+    "$srcdir/driver-nwfilter.h",
+    "$srcdir/driver-secret.h",
+    "$srcdir/driver-state.h",
+    "$srcdir/driver-storage.h",
+    "$srcdir/driver-stream.h",
+    );
 
 my %groupheaders = (
     "virHypervisorDriver" => "Hypervisor APIs",
@@ -182,41 +192,44 @@ $apis{virDomainMigrateConfirm3Params} = "1.1.0";
 # and driver struct fields. This lets us later match
 # update the driver impls with the public APis.
 
-open FILE, "<$drivertable"
-    or die "cannot read $drivertable: $!";
-
 # Group name -> hash of APIs { fields -> api name }
 my %groups;
 my $ingrp;
-while (defined($line = <FILE>)) {
-    if ($line =~ /struct _(vir\w*Driver)/) {
-        my $grp = $1;
-        if ($grp ne "virStateDriver" &&
-            $grp ne "virStreamDriver") {
-            $ingrp = $grp;
-            $groups{$ingrp} = { apis => {}, drivers => {} };
-        }
-    } elsif ($ingrp) {
-        if ($line =~ /^\s*vir(?:Drv)(\w+)\s+(\w+);\s*$/) {
-            my $field = $2;
-            my $name = $1;
-
-            my $api;
-            if (exists $apis{"vir$name"}) {
-                $api = "vir$name";
-            } elsif ($name =~ /\w+(Open|Close)/) {
-                next;
-            } else {
-                die "driver $name does not have a public API";
+foreach my $drivertable (@drivertable) {
+    open FILE, "<$drivertable"
+        or die "cannot read $drivertable: $!";
+
+    while (defined($line = <FILE>)) {
+        if ($line =~ /struct _(vir\w*Driver)/) {
+            my $grp = $1;
+            if ($grp ne "virStateDriver" &&
+                $grp ne "virStreamDriver") {
+                $ingrp = $grp;
+                warn "[$ingrp]";
+                $groups{$ingrp} = { apis => {}, drivers => {} };
+            }
+        } elsif ($ingrp) {
+            if ($line =~ /^\s*vir(?:Drv)(\w+)\s+(\w+);\s*$/) {
+                my $field = $2;
+                my $name = $1;
+
+                my $api;
+                if (exists $apis{"vir$name"}) {
+                    $api = "vir$name";
+                } elsif ($name =~ /\w+(Open|Close)/) {
+                    next;
+                } else {
+                    die "driver $name does not have a public API";
+                }
+                $groups{$ingrp}->{apis}->{$field} = $api;
+            } elsif ($line =~ /};/) {
+                $ingrp = undef;
             }
-            $groups{$ingrp}->{apis}->{$field} = $api;
-        } elsif ($line =~ /};/) {
-            $ingrp = undef;
         }
     }
-}
 
-close FILE;
+    close FILE;
+}
 
 
 # Finally, we read all the primary driver files and extract
@@ -290,43 +303,43 @@ foreach my $src (@srcs) {
 # have a bit of manual fixup todo with the per-driver versioning
 # and support matrix
 
-$groups{virDriver}->{apis}->{"openAuth"} = "virConnectOpenAuth";
-$groups{virDriver}->{apis}->{"openReadOnly"} = "virConnectOpenReadOnly";
-$groups{virDriver}->{apis}->{"domainMigrate"} = "virDomainMigrate";
+$groups{virHypervisorDriver}->{apis}->{"openAuth"} = "virConnectOpenAuth";
+$groups{virHypervisorDriver}->{apis}->{"openReadOnly"} = "virConnectOpenReadOnly";
+$groups{virHypervisorDriver}->{apis}->{"domainMigrate"} = "virDomainMigrate";
 
 my $openAuthVers = (0 * 1000 * 1000) + (4 * 1000) + 0;
 
-foreach my $drv (keys %{$groups{"virDriver"}->{drivers}}) {
-    my $openVersStr = $groups{"virDriver"}->{drivers}->{$drv}->{"connectOpen"};
+foreach my $drv (keys %{$groups{"virHypervisorDriver"}->{drivers}}) {
+    my $openVersStr = $groups{"virHypervisorDriver"}->{drivers}->{$drv}->{"connectOpen"};
     my $openVers;
     if ($openVersStr =~ /(\d+)\.(\d+)\.(\d+)/) {
         $openVers = ($1 * 1000 * 1000) + ($2 * 1000) + $3;
     }
 
     # virConnectOpenReadOnly always matches virConnectOpen version
-    $groups{"virDriver"}->{drivers}->{$drv}->{"connectOpenReadOnly"} =
-        $groups{"virDriver"}->{drivers}->{$drv}->{"connectOpen"};
+    $groups{"virHypervisorDriver"}->{drivers}->{$drv}->{"connectOpenReadOnly"} =
+        $groups{"virHypervisorDriver"}->{drivers}->{$drv}->{"connectOpen"};
 
     # virConnectOpenAuth is always 0.4.0 if the driver existed
     # before this time, otherwise it matches the version of
     # the driver's virConnectOpen entry
     if ($openVersStr eq "Y" ||
         $openVers >= $openAuthVers) {
-        $groups{"virDriver"}->{drivers}->{$drv}->{"connectOpenAuth"} = $openVersStr;
+        $groups{"virHypervisorDriver"}->{drivers}->{$drv}->{"connectOpenAuth"} = $openVersStr;
     } else {
-        $groups{"virDriver"}->{drivers}->{$drv}->{"connectOpenAuth"} = "0.4.0";
+        $groups{"virHypervisorDriver"}->{drivers}->{$drv}->{"connectOpenAuth"} = "0.4.0";
     }
 }
 
 
 # Another special case for the virDomainCreateLinux which was replaced
 # with virDomainCreateXML
-$groups{virDriver}->{apis}->{"domainCreateLinux"} = "virDomainCreateLinux";
+$groups{virHypervisorDriver}->{apis}->{"domainCreateLinux"} = "virDomainCreateLinux";
 
 my $createAPIVers = (0 * 1000 * 1000) + (0 * 1000) + 3;
 
-foreach my $drv (keys %{$groups{"virDriver"}->{drivers}}) {
-    my $createVersStr = $groups{"virDriver"}->{drivers}->{$drv}->{"domainCreateXML"};
+foreach my $drv (keys %{$groups{"virHypervisorDriver"}->{drivers}}) {
+    my $createVersStr = $groups{"virHypervisorDriver"}->{drivers}->{$drv}->{"domainCreateXML"};
     next unless defined $createVersStr;
     my $createVers;
     if ($createVersStr =~ /(\d+)\.(\d+)\.(\d+)/) {
@@ -338,9 +351,9 @@ foreach my $drv (keys %{$groups{"virDriver"}->{drivers}}) {
     # the driver's virCreateXML entry
     if ($createVersStr eq "Y" ||
         $createVers >= $createAPIVers) {
-        $groups{"virDriver"}->{drivers}->{$drv}->{"domainCreateLinux"} = $createVersStr;
+        $groups{"virHypervisorDriver"}->{drivers}->{$drv}->{"domainCreateLinux"} = $createVersStr;
     } else {
-        $groups{"virDriver"}->{drivers}->{$drv}->{"domainCreateLinux"} = "0.0.3";
+        $groups{"virHypervisorDriver"}->{drivers}->{$drv}->{"domainCreateLinux"} = "0.0.3";
     }
 }
 
@@ -367,7 +380,7 @@ in.
 
 EOF
 
-foreach my $grp (sort { $a cmp $b } keys %groups) {
+    foreach my $grp (sort { $a cmp $b } keys %groups) {
     print "<h2><a name=\"$grp\">", $groupheaders{$grp}, "</a></h2>\n";
     print <<EOF;
 <table class="top_table">
diff --git a/docs/sitemap.html.in b/docs/sitemap.html.in
index 1e91869..fad5358 100644
--- a/docs/sitemap.html.in
+++ b/docs/sitemap.html.in
@@ -291,12 +291,52 @@
             -->
             <ul>
               <li>
-                <a href="html/libvirt-libvirt.html">libvirt</a>
-                <span>core interfaces for the libvirt library</span>
+                <a href="html/libvirt-libvirt-domain.html">Domain</a>
+                <span>domain APIs for the libvirt library</span>
               </li>
               <li>
-                <a href="html/libvirt-virterror.html">virterror</a>
-                <span>error handling interfaces for the libvirt library</span>
+                <a href="html/libvirt-libvirt-domain-snapshot.html">Domain snapshot</a>
+                <span>domain snapshot APIs for the libvirt library</span>
+              </li>
+              <li>
+                <a href="html/libvirt-virterror.html">Error</a>
+                <span>error handling APIs for the libvirt library</span>
+              </li>
+              <li>
+                <a href="html/libvirt-libvirt-event.html">Event</a>
+                <span>event APIs for the libvirt library</span>
+              </li>
+              <li>
+                <a href="html/libvirt-libvirt-host.html">Host</a>
+                <span>host APIs for the libvirt library</span>
+              </li>
+              <li>
+                <a href="html/libvirt-libvirt-interface.html">Interface</a>
+                <span>interface APIs for the libvirt library</span>
+              </li>
+              <li>
+                <a href="html/libvirt-libvirt-network.html">Network</a>
+                <span>network APIs for the libvirt library</span>
+              </li>
+              <li>
+                <a href="html/libvirt-libvirt-nodedev.html">Node device</a>
+                <span>node device APIs for the libvirt library</span>
+              </li>
+              <li>
+                <a href="html/libvirt-libvirt-nwfilter.html">Network filter</a>
+                <span>network filter APIs for the libvirt library</span>
+              </li>
+              <li>
+                <a href="html/libvirt-libvirt-secret.html">Secret</a>
+                <span>secret APIs for the libvirt library</span>
+              </li>
+              <li>
+                <a href="html/libvirt-libvirt-storage.html">Storage</a>
+                <span>storage APIs for the libvirt library</span>
+              </li>
+              <li>
+                <a href="html/libvirt-libvirt-stream.html">Stream</a>
+                <span>stream APIs for the libvirt library</span>
               </li>
               <li>
                 <a href="hvsupport.html">Driver support</a>
-- 
2.1.0




More information about the libvir-list mailing list