[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]

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



On Wed, Nov 12, 2014 at 8:30 PM, Daniel P. Berrange <berrange 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>
> -                <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
>
> --
> libvir-list mailing list
> libvir-list 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


[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]