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

Mon Nov 17 23:18:32 UTC 2014

On Wed, Nov 12, 2014 at 8:30 PM, Daniel P. Berrange <berrange at redhat.com> wrote:
> 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>
> - core interfaces for the libvirt library
> + <a href="html/libvirt-libvirt-domain.html">Domain</a>
> + domain APIs for the libvirt library
> </li>
> <li>
> - <a href="html/libvirt-virterror.html">virterror</a>
> - error handling interfaces for the libvirt library
> + <a href="html/libvirt-libvirt-domain-snapshot.html">Domain snapshot</a>
> + domain snapshot APIs for the libvirt library
> + </li>
> + <li>
> + <a href="html/libvirt-virterror.html">Error</a>
> + error handling APIs for the libvirt library
> + </li>
> + <li>
> + <a href="html/libvirt-libvirt-event.html">Event</a>
> + event APIs for the libvirt library
> + </li>
> + <li>
> + <a href="html/libvirt-libvirt-host.html">Host</a>
> + host APIs for the libvirt library
> + </li>
> + <li>
> + <a href="html/libvirt-libvirt-interface.html">Interface</a>
> + interface APIs for the libvirt library
> + </li>
> + <li>
> + <a href="html/libvirt-libvirt-network.html">Network</a>
> + network APIs for the libvirt library
> + </li>
> + <li>
> + <a href="html/libvirt-libvirt-nodedev.html">Node device</a>
> + node device APIs for the libvirt library
> + </li>
> + <li>
> + <a href="html/libvirt-libvirt-nwfilter.html">Network filter</a>
> + network filter APIs for the libvirt library
> + </li>
> + <li>
> + <a href="html/libvirt-libvirt-secret.html">Secret</a>
> + secret APIs for the libvirt library
> + </li>
> + <li>
> + <a href="html/libvirt-libvirt-storage.html">Storage</a>
> + storage APIs for the libvirt library
> + </li>
> + <li>
> + <a href="html/libvirt-libvirt-stream.html">Stream</a>
> + stream APIs for the libvirt library
> </li>
> <li>
> <a href="hvsupport.html">Driver support</a>
> --
> 2.1.0
>
> --
> libvir-list mailing list
> libvir-list at redhat.com
> https://www.redhat.com/mailman/listinfo/libvir-list

Make rpm fails with error:

 GEN devhelp/libvirt-libvirt.html
cp: cannot stat './html/libvirt-libvirt.html': No such file or directory
make[3]: *** [distdir] Error 1

I guess, references of libvirt-libvirt.html were not removed from
docs/Makefile.am

Following patch fixes it (But I am not sure if it is the right way to go):

diff --git a/docs/Makefile.am b/docs/Makefile.am
index 910bfef..5485ee9 100644
--- a/docs/Makefile.am
+++ b/docs/Makefile.am
@@ -31,7 +31,6 @@ apihtml =                    \
   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        \
@@ -51,7 +50,6 @@ devhelphtml =            \
   devhelp/libvirt.devhelp    \
   devhelp/index.html        \
   devhelp/general.html        \
-  devhelp/libvirt-libvirt.html    \
   devhelp/libvirt-virterror.html

 css =         \
@@ -269,7 +267,6 @@ $(addprefix $(srcdir)/,$(devhelphtml)):
$(srcdir)/libvirt-api.xml $(devhelpxsl)


 python_generated_files = \
-        $(srcdir)/html/libvirt-libvirt.html \
         $(srcdir)/html/libvirt-libvirt-lxc.html \
         $(srcdir)/html/libvirt-libvirt-qemu.html \
         $(srcdir)/html/libvirt-virterror.html \


-- 
Nehal J Wani


