From af1b89d1d4f975c904789cf73fe35ae0c659282a Mon Sep 17 00:00:00 2001 From: Martin Kletzander Date: Mon, 1 Dec 2014 14:36:13 +0100 Subject: [PATCH] docs: Correct invalid hyperlinks Since libvirt.h was split into multiple files and similarly docs/libvirt-libvirt.html, docs/hvsupport.html have bad hyperlinks. The same happens for all the html.in files that used tag, because page.xsl has no idea where to point the link that's found. Signed-off-by: Martin Kletzander --- docs/Makefile.am | 4 +- docs/acl.html.in | 2 +- docs/api.html.in | 224 +++++++++++++++++++++++++++------- docs/errors.html.in | 4 +- docs/formatdomain.html.in | 15 ++- docs/formatdomaincaps.html.in | 17 ++- docs/hvsupport.pl | 75 ++++++++---- docs/java.html.in | 6 +- docs/page.xsl | 5 - docs/python.html.in | 8 +- docs/uri.html.in | 12 +- libvirt.spec.in | 1 + 12 files changed, 277 insertions(+), 96 deletions(-) diff --git a/docs/Makefile.am b/docs/Makefile.am index 5485ee9574..684687dec9 100644 --- a/docs/Makefile.am +++ b/docs/Makefile.am @@ -1,6 +1,6 @@ ## Process this file with automake to produce Makefile.in -## Copyright (C) 2005-2013 Red Hat, Inc. +## Copyright (C) 2005-2014 Red Hat, Inc. ## ## This library is free software; you can redistribute it and/or ## modify it under the terms of the GNU Lesser General Public @@ -195,7 +195,7 @@ todo: hvsupport.html:: $(srcdir)/hvsupport.html.in -$(srcdir)/hvsupport.html.in: $(srcdir)/hvsupport.pl \ +$(srcdir)/hvsupport.html.in: $(srcdir)/hvsupport.pl $(api_DATA) \ $(srcdir)/../src/libvirt_public.syms \ $(srcdir)/../src/libvirt_qemu.syms $(srcdir)/../src/libvirt_lxc.syms \ $(srcdir)/../src/driver.h diff --git a/docs/acl.html.in b/docs/acl.html.in index 2d228e2ecf..6d280c194d 100644 --- a/docs/acl.html.in +++ b/docs/acl.html.in @@ -90,7 +90,7 @@ types in its API. Each object type, in turn, has a set of permissions defined. To determine what permissions are checked for specific API call, consult the - API reference manual + API reference manual documentation for the API in question.

diff --git a/docs/api.html.in b/docs/api.html.in index 68ffa0b022..5c64db142e 100644 --- a/docs/api.html.in +++ b/docs/api.html.in @@ -16,7 +16,7 @@ manipulated through the API is the virConnectPtr, which represents the connection to a hypervisor. Any application using libvirt is likely to start using the - API by calling one of the virConnectOpen functions. You will note that those functions take a name argument which is actually a connection URI to select the right hypervisor to open. @@ -26,7 +26,10 @@ name will default to a preselected hypervisor, but it's probably not a wise thing to do in most cases. See the connection URI page for a full descriptions of the values allowed.

-

Once the application obtains a virConnectPtr +

OnDevice the application obtains a + + virConnectPtr + connection to the hypervisor it can then use it to manage the hypervisor's available domains and related virtualization resources, such as storage and networking. All those are @@ -38,33 +41,61 @@

The figure above shows the five main objects exported by the API:

    -
  • virConnectPtr +
  • + + virConnectPtr +

    Represents the connection to a hypervisor. Use one of the - virConnectOpen + virConnectOpen functions to obtain connection to the hypervisor which is then used as a parameter to other connection API's.

    • -
  • virDomainPtr +
  • + + virDomainPtr +

    Represents one domain either active or defined (i.e. existing as permanent config file and storage but not currently running on that - node). The function virConnectListAllDomains + node). The function + + virConnectListAllDomains + lists all the domains for the hypervisor.

    • -
  • virNetworkPtr +
  • + + virNetworkPtr +

    Represents one network either active or defined (i.e. existing as permanent config file and storage but not currently activated). - The function virConnectListAllNetworks + The function + + virConnectListAllNetworks + lists all the virtualization networks for the hypervisor.

    • -
  • virStorageVolPtr +
  • + + virStorageVolPtr +

    Represents one storage volume generally used as a block device available to one of the domains. The function - virStorageVolLookupByPath finds - the storage volume object based on its path on the node.

    • -
  • virStoragePoolPtr + + virStorageVolLookupByPath + + finds the storage volume object based on its path on the node.

    • +
  • + + virStoragePoolPtr +

    Represents a storage pool, which is a logical area used to allocate and store storage volumes. The function - virConnectListAllStoragePools lists - all of the virtualization storage pools on the hypervisor. The function - virStoragePoolLookupByVolume finds - the storage pool containing a given storage volume.

    • + + virConnectListAllStoragePools + + lists all of the virtualization storage pools on the hypervisor. + The function + + virStoragePoolLookupByVolume + + finds the storage pool containing a given storage volume.

Most objects manipulated by the library can also be represented using XML descriptions. This is used primarily to create those object, but is @@ -101,42 +132,114 @@

Used to perform lookups on objects by some type of identifier, such as:

  • Enumeration [virConnectList..., virConnectNumOf...]

    Used to enumerate a set of object available to an given hypervisor connection such as:

  • Description [...GetInfo]

    Generic accessor providing a set of generic information about an object, such as:

  • Accessors [...Get..., ...Set...]

    Specific accessors used to query or modify data for the given object, such as:

  • Creation [...Create, ...CreateXML] @@ -144,18 +247,46 @@ the object based on an XML description, while the ...Create APIs will create the object based on existing object pointer, such as:

  • Destruction [...Destroy]

    Used to shutdown or deactivate and destroy objects, such as:

    • @@ -170,7 +301,11 @@

    Drivers are the basic building block for libvirt functionality to support the capability to handle specific hypervisor driver calls. Drivers are discovered and registered during connection processing as - part of the virInitialize API. Each driver + part of the + + virInitialize + + API. Each driver has a registration API which loads up the driver specific function references for the libvirt APIs to call. The following is a simplistic view of the hypervisor driver mechanism. Consider the stacked list of @@ -199,7 +334,10 @@ The libvirtd daemon service is started on the host at system boot time and can also be restarted at any time by a properly privileged user, such as root. The libvirtd daemon uses the same libvirt API - virInitialize sequence as applications + + virInitialize + + sequence as applications for client-side driver registrations, but then extends the registered driver list to encompass all known drivers supported for all driver types supported on the host.

    diff --git a/docs/errors.html.in b/docs/errors.html.in index df9aa7c56f..668d280c15 100644 --- a/docs/errors.html.in +++ b/docs/errors.html.in @@ -46,9 +46,9 @@ following fields:

  • level: the error level, usually VIR_ERR_ERROR, though there is room for warnings like VIR_ERR_WARNING
  • message: the full human-readable formatted string of the error
    • -
  • conn: if available a pointer to the virConnectPtr +
  • conn: if available a pointer to the virConnectPtr connection to the hypervisor where this happened
    • -
  • dom: if available a pointer to the virDomainPtr domain +
  • dom: if available a pointer to the virDomainPtr domain targeted in the operation

    • and then extra raw information about the error which may be initialized diff --git a/docs/formatdomain.html.in b/docs/formatdomain.html.in index d05912e51e..8fcbd29549 100644 --- a/docs/formatdomain.html.in +++ b/docs/formatdomain.html.in @@ -190,7 +190,7 @@ "emulate" (let the hypervisor generate all values), "host" (copy all of Block 0 and Block 1, except for the UUID, from the host's SMBIOS values; - the + the virConnectGetSysinfo call can be used to see what values are copied), or "sysinfo" (use the values in the sysinfo element). If not @@ -1196,9 +1196,16 @@ It is sometimes necessary to override the default actions taken on various events. Not all hypervisors support all events and actions. The actions may be taken as a result of calls to libvirt APIs - virDomainReboot, - virDomainShutdown, or - virDomainShutdownFlags. + + virDomainReboot + , + + virDomainShutdown + , + or + + virDomainShutdownFlags + . Using virsh reboot or virsh shutdown would also trigger the event.

    diff --git a/docs/formatdomaincaps.html.in b/docs/formatdomaincaps.html.in index 6959dfef29..7beb5a4466 100644 --- a/docs/formatdomaincaps.html.in +++ b/docs/formatdomaincaps.html.in @@ -16,11 +16,14 @@ then it needs to be more recent to support VFIO, while legacy KVM is achievable just fine with older qemus.

    -

    The main difference between virConnectGetCapabilities and the emulator - capabilities API is, the former one aims more on the host capabilities - (e.g. NUMA topology, security models in effect, etc.) while the latter one - specializes on the hypervisor capabilities.

    +

    The main difference between + + virConnectGetCapabilities + + and the emulator capabilities API is, the former one aims more on + the host capabilities (e.g. NUMA topology, security models in + effect, etc.) while the latter one specializes on the hypervisor + capabilities.

    While the Driver Capabilities provides the host capabilities (e.g NUMA topology, security models in effect, etc.), the @@ -41,7 +44,9 @@ 1.2.7):

    -    virConnectGetDomainCapabilities
+  
+    virConnectGetDomainCapabilities
+

    The root element that emulator capability XML document starts with has diff --git a/docs/hvsupport.pl b/docs/hvsupport.pl index 6bbd44a818..44a30ce45a 100755 --- a/docs/hvsupport.pl +++ b/docs/hvsupport.pl @@ -4,6 +4,8 @@ use strict; use warnings; use File::Find; +use XML::XPath; +use XML::XPath::XMLParser; die "syntax: $0 SRCDIR\n" unless int(@ARGV) == 1; @@ -52,6 +54,7 @@ open FILE, "<$symslibvirt" my $vers; my $prevvers; +my $apixpath = XML::XPath->new(filename => "$srcdir/../docs/libvirt-api.xml"); while (defined($line = )) { chomp $line; next if $line =~ /^\s*#/; @@ -75,7 +78,10 @@ while (defined($line = )) { $prevvers = $vers; $vers = undef; } elsif ($line =~ /\s*(\w+)\s*;\s*$/) { - $apis{$1} = $vers; + my $file = $apixpath->find("/api/symbols/function[\@name='$1']/\@file"); + $apis{$1} = {}; + $apis{$1}->{vers} = $vers; + $apis{$1}->{file} = $file; } else { die "unexpected data $line\n"; } @@ -91,6 +97,7 @@ open FILE, "<$symsqemu" $prevvers = undef; $vers = undef; +$apixpath = XML::XPath->new(filename => "$srcdir/../docs/libvirt-qemu-api.xml"); while (defined($line = )) { chomp $line; next if $line =~ /^\s*#/; @@ -114,7 +121,10 @@ while (defined($line = )) { $prevvers = $vers; $vers = undef; } elsif ($line =~ /\s*(\w+)\s*;\s*$/) { - $apis{$1} = $vers; + my $file = $apixpath->find("/api/symbols/function[\@name='$1']/\@file"); + $apis{$1} = {}; + $apis{$1}->{vers} = $vers; + $apis{$1}->{file} = $file; } else { die "unexpected data $line\n"; } @@ -130,6 +140,7 @@ open FILE, "<$symslxc" $prevvers = undef; $vers = undef; +$apixpath = XML::XPath->new(filename => "$srcdir/../docs/libvirt-lxc-api.xml"); while (defined($line = )) { chomp $line; next if $line =~ /^\s*#/; @@ -153,7 +164,10 @@ while (defined($line = )) { $prevvers = $vers; $vers = undef; } elsif ($line =~ /\s*(\w+)\s*;\s*$/) { - $apis{$1} = $vers; + my $file = $apixpath->find("/api/symbols/function[\@name='$1']/\@file"); + $apis{$1} = {}; + $apis{$1}->{vers} = $vers; + $apis{$1}->{file} = $file; } else { die "unexpected data $line\n"; } @@ -164,27 +178,27 @@ close FILE; # Some special things which aren't public APIs, # but we want to report -$apis{virConnectSupportsFeature} = "0.3.2"; -$apis{virDomainMigratePrepare} = "0.3.2"; -$apis{virDomainMigratePerform} = "0.3.2"; -$apis{virDomainMigrateFinish} = "0.3.2"; -$apis{virDomainMigratePrepare2} = "0.5.0"; -$apis{virDomainMigrateFinish2} = "0.5.0"; -$apis{virDomainMigratePrepareTunnel} = "0.7.2"; +$apis{virConnectSupportsFeature}->{vers} = "0.3.2"; +$apis{virDomainMigratePrepare}->{vers} = "0.3.2"; +$apis{virDomainMigratePerform}->{vers} = "0.3.2"; +$apis{virDomainMigrateFinish}->{vers} = "0.3.2"; +$apis{virDomainMigratePrepare2}->{vers} = "0.5.0"; +$apis{virDomainMigrateFinish2}->{vers} = "0.5.0"; +$apis{virDomainMigratePrepareTunnel}->{vers} = "0.7.2"; -$apis{virDomainMigrateBegin3} = "0.9.2"; -$apis{virDomainMigratePrepare3} = "0.9.2"; -$apis{virDomainMigratePrepareTunnel3} = "0.9.2"; -$apis{virDomainMigratePerform3} = "0.9.2"; -$apis{virDomainMigrateFinish3} = "0.9.2"; -$apis{virDomainMigrateConfirm3} = "0.9.2"; +$apis{virDomainMigrateBegin3}->{vers} = "0.9.2"; +$apis{virDomainMigratePrepare3}->{vers} = "0.9.2"; +$apis{virDomainMigratePrepareTunnel3}->{vers} = "0.9.2"; +$apis{virDomainMigratePerform3}->{vers} = "0.9.2"; +$apis{virDomainMigrateFinish3}->{vers} = "0.9.2"; +$apis{virDomainMigrateConfirm3}->{vers} = "0.9.2"; -$apis{virDomainMigrateBegin3Params} = "1.1.0"; -$apis{virDomainMigratePrepare3Params} = "1.1.0"; -$apis{virDomainMigratePrepareTunnel3Params} = "1.1.0"; -$apis{virDomainMigratePerform3Params} = "1.1.0"; -$apis{virDomainMigrateFinish3Params} = "1.1.0"; -$apis{virDomainMigrateConfirm3Params} = "1.1.0"; +$apis{virDomainMigrateBegin3Params}->{vers} = "1.1.0"; +$apis{virDomainMigratePrepare3Params}->{vers} = "1.1.0"; +$apis{virDomainMigratePrepareTunnel3Params}->{vers} = "1.1.0"; +$apis{virDomainMigratePerform3Params}->{vers} = "1.1.0"; +$apis{virDomainMigrateFinish3Params}->{vers} = "1.1.0"; +$apis{virDomainMigrateConfirm3Params}->{vers} = "1.1.0"; @@ -406,10 +420,23 @@ EOF $groups{$grp}->{apis}->{$b} } keys %{$groups{$grp}->{apis}}) { my $api = $groups{$grp}->{apis}->{$field}; - my $vers = $apis{$api}; + my $vers = $apis{$api}->{vers}; + my $htmlgrp = $apis{$api}->{file}; print < -$api + +EOF + + if (defined $htmlgrp) { + print <$api +EOF + + } else { + print $api; + } + print < $vers EOF diff --git a/docs/java.html.in b/docs/java.html.in index daa7b769b2..659c0b90f4 100644 --- a/docs/java.html.in +++ b/docs/java.html.in @@ -98,18 +98,18 @@ the code you can build the code with

    The bindings are articulated around a few classes in the org/libvirt package, notably the Connect, Domain and Network -ones. Functions in the C API +ones. Functions in the C API taking virConnectPtr, virDomainPtr or virNetworkPtr as their first argument usually become methods for the classes, their name is just stripped from the virConnect or virDomain(Get) prefix and the first letter gets converted to lower case, for example the C functions:

    - int virConnectNumOfDomains + int virConnectNumOfDomains (virConnectPtr conn);

    - int virDomainSetMaxMemory + int virDomainSetMaxMemory (virDomainPtr domain, unsigned long memory);

    become

    diff --git a/docs/page.xsl b/docs/page.xsl index 7de238edc8..80164dd6cc 100644 --- a/docs/page.xsl +++ b/docs/page.xsl @@ -10,11 +10,6 @@ - - - - - diff --git a/docs/python.html.in b/docs/python.html.in index 3033337f2b..36517fec77 100644 --- a/docs/python.html.in +++ b/docs/python.html.in @@ -12,11 +12,11 @@ becomes methods for the classes, their name is just stripped from the virConnect or virDomain(Get) prefix and the first letter gets converted to lower case, for example the C functions:

    - int virConnectNumOfDomains + int virConnectNumOfDomains (virConnectPtr conn);

    - int virDomainSetMaxMemory + int virDomainSetMaxMemory (virDomainPtr domain, unsigned long memory);

    become

    @@ -31,10 +31,10 @@ in the file libvirtclass.txt present in the python dir or in the docs.There is a couple of function who don't map directly to their C counterparts due to specificities in their argument conversions:

      -
    • virConnectListDomains +
    • virConnectListDomains is replaced by virDomain::listDomainsID(self) which returns a list of the integer ID for the currently running domains
      • -
    • virDomainGetInfo +
    • virDomainGetInfo is replaced by virDomain::info() which returns a list of
      1. state: one of the state values (virDomainState)
      2. maxMemory: the maximum memory used by the domain
      3. memory: the current amount of memory used by the domain
      4. nbVirtCPU: the number of virtual CPU
      5. cpuTime: the time used by the domain in nanoseconds
    diff --git a/docs/uri.html.in b/docs/uri.html.in index 73c3e88f3e..7702ccc6e6 100644 --- a/docs/uri.html.in +++ b/docs/uri.html.in @@ -19,7 +19,15 @@ documents libvirt URIs.

    Specifying URIs to libvirt

    -The URI is passed as the name parameter to virConnectOpen or virConnectOpenReadOnly. For example: + The URI is passed as the name parameter to + + virConnectOpen + + or + + virConnectOpenReadOnly + . + For example: 

     virConnectPtr conn = virConnectOpenReadOnly ("test:///default");
@@ -291,7 +299,7 @@ Notes:
     
      
       
    1.  The HTTP client does not fully support IPv6. 
      2. 
       
    2.  Many features do not work as expected across HTTP connections, in
- particular, virConnectGetCapabilities.
+ particular, virConnectGetCapabilities.
  The remote support however does work
  correctly. 
      3. 
       
    3.  XenD's new-style XMLRPC interface is not supported by
diff --git a/libvirt.spec.in b/libvirt.spec.in
index 095948312a..3edb7bde08 100644
--- a/libvirt.spec.in
+++ b/libvirt.spec.in
@@ -427,6 +427,7 @@ BuildRequires: /usr/bin/pod2man
 %endif
 BuildRequires: git
 BuildRequires: perl
+BuildRequires: perl-XML-XPath
 BuildRequires: python
 %if %{with_systemd}
 BuildRequires: systemd-units