[libvirt PATCH 3/9] docs: html.in: Convert api to rst

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

 



There were a number of occurrences where we used nested inline markup
(verbatim + refs) which is currently not possible with RST syntax [1].
There is a possible workaround involving substitution definitions like

  .. |virConnectPtr| replace:: ``virConnectPtr``
  .. _virConnectPtr: /html/libvirt-libvirt-host.html#virConnectPtr

Substitutions cannot be made generic, hence we cannot create a template
for substitution and use a single template everywhere, so we'd end up
with a lot of clutter and convolution. Therefore, we can make an
exception and just link the data type without further style markup.

[1] https://docutils.sourceforge.io/FAQ.html#is-nested-inline-markup-possible

Signed-off-by: Erik Skultety <eskultet@xxxxxxxxxx>
---
 docs/api.html.in | 380 -----------------------------------------------
 docs/api.rst     | 265 +++++++++++++++++++++++++++++++++
 docs/meson.build |   2 +-
 3 files changed, 266 insertions(+), 381 deletions(-)
 delete mode 100644 docs/api.html.in
 create mode 100644 docs/api.rst

diff --git a/docs/api.html.in b/docs/api.html.in
deleted file mode 100644
index 4bff037d48..0000000000
--- a/docs/api.html.in
+++ /dev/null
@@ -1,380 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE html>
-<html xmlns="http://www.w3.org/1999/xhtml";>
-  <body>
-    <h1>The libvirt API concepts</h1>
-
-    <p> This page describes the main principles and architecture choices
-    behind the definition of the libvirt API:</p>
-
-    <ul id="toc"></ul>
-
-    <h2><a id="Objects">Objects Exposed</a></h2>
-    <p> As defined in the <a href="goals.html">goals section</a>, the libvirt
-    API is designed to expose all the resources needed to manage the
-    virtualization support of recent operating systems. The first object
-    manipulated through the API is the <code>virConnectPtr</code>, which
-    represents the connection to a hypervisor. Any application using libvirt
-    is likely to start using the
-    API by calling one of <a href="html/libvirt-libvirt-host.html#virConnectOpen"
-    >the virConnectOpen functions</a>. You will note that those functions take
-    a name argument which is actually a <a href="uri.html">connection URI</a>
-    to select the right hypervisor to open.
-    A URI is needed to allow remote connections and also select between
-    different possible hypervisors. For example, on a Linux system it may be
-    possible to use both KVM and LinuxContainers on the same node. A NULL
-    name will default to a preselected hypervisor, but it's probably not a
-    wise thing to do in most cases. See the <a href="uri.html">connection
-    URI</a> page for a full descriptions of the values allowed.</p>
-    <p> OnDevice the application obtains a
-      <a href="/html/libvirt-libvirt-host.html#virConnectPtr">
-        <code>virConnectPtr</code>
-      </a>
-    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
-    exposed as first class objects and connected to the hypervisor connection
-    (and the node or cluster where it is available).</p>
-    <p class="image">
-      <img alt="first class objects exposed by the API"
-           src="libvirt-object-model.png"/>
-    </p>
-    <p> The figure above shows the five main objects exported by the API:</p>
-    <ul>
-      <li>
-        <a href="html/libvirt-libvirt-host.html#virConnectPtr">
-          <code>virConnectPtr</code>
-        </a>
-      <p>Represents the connection to a hypervisor. Use one of the
-      <a href="html/libvirt-libvirt-host.html#virConnectOpen">virConnectOpen</a>
-      functions to obtain connection to the hypervisor which is then used
-      as a parameter to other connection API's.</p></li>
-      <li>
-        <a href="html/libvirt-libvirt-domain.html#virDomainPtr">
-          <code>virDomainPtr</code>
-        </a>
-      <p>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
-        <a href="html/libvirt-libvirt-domain.html#virConnectListAllDomains">
-          <code>virConnectListAllDomains</code>
-        </a>
-      lists all the domains for the hypervisor.</p></li>
-      <li>
-        <a href="html/libvirt-libvirt-network.html#virNetworkPtr">
-          <code>virNetworkPtr</code>
-        </a>
-      <p>Represents one network either active or defined (i.e. existing
-      as permanent config file and storage but not currently activated).
-      The function
-        <a href="html/libvirt-libvirt-network.html#virConnectListAllNetworks">
-          <code>virConnectListAllNetworks</code>
-        </a>
-      lists all the virtualization networks for the hypervisor.</p></li>
-      <li>
-        <a href="html/libvirt-libvirt-storage.html#virStorageVolPtr">
-          <code>virStorageVolPtr</code>
-        </a>
-      <p>Represents one storage volume generally used
-      as a block device available to one of the domains. The function
-        <a href="html/libvirt-libvirt-storage.html#virStorageVolLookupByPath">
-          <code>virStorageVolLookupByPath</code>
-        </a>
-      finds the storage volume object based on its path on the node.</p></li>
-      <li>
-        <a href="html/libvirt-libvirt-storage.html#virStoragePoolPtr">
-          <code>virStoragePoolPtr</code>
-        </a>
-      <p>Represents a storage pool, which is a logical area
-      used to allocate and store storage volumes. The function
-        <a href="html/libvirt-libvirt-storage.html#virConnectListAllStoragePools">
-          <code>virConnectListAllStoragePools</code>
-        </a>
-      lists all of the virtualization storage pools on the hypervisor.
-      The function
-        <a href="html/libvirt-libvirt-storage.html#virStoragePoolLookupByVolume">
-          <code>virStoragePoolLookupByVolume</code>
-        </a>
-      finds the storage pool containing a given storage volume.</p></li>
-    </ul>
-    <p> Most objects manipulated by the library can also be represented using
-      XML descriptions. This is used primarily to create those object, but is
-      also helpful to modify or save their description back.</p>
-    <p> Domains, networks, and storage pools can be either <code>active</code>
-      i.e. either running or available for immediate use, or
-      <code>defined</code> in which case they are inactive but there is
-      a permanent definition available in the system for them. Based on this
-      they can be activated dynamically in order to be used.</p>
-    <p> Most objects can also be named in various ways:</p>
-    <ul>
-      <li><code>name</code>
-      <p>A user friendly identifier but whose uniqueness
-      cannot be guaranteed between two nodes.</p></li>
-      <li><code>ID</code>
-      <p>A runtime unique identifier
-      provided by the hypervisor for one given activation of the object;
-      however, it becomes invalid once the resource is deactivated.</p></li >
-      <li><code>UUID</code>
-      <p> A 16 byte unique identifier
-      as defined in <a href="https://www.ietf.org/rfc/rfc4122.txt";>RFC 4122</a>,
-      which is guaranteed to be unique for long term usage and across a
-      set of nodes.</p></li>
-    </ul>
-
-    <h2><a id="Functions">Functions and Naming Conventions</a></h2>
-    <p> The naming of the functions present in the library is usually
-      composed by a prefix describing the object associated to the function
-      and a verb describing the action on that object.</p>
-    <p> For each first class object you will find APIs
-      for the following actions:</p>
-    <ul>
-      <li><b>Lookup</b> [...LookupBy...]
-      <p>Used to perform lookups on objects by some type of identifier,
-      such as:</p>
-          <ul>
-            <li>
-              <a href="html/libvirt-libvirt-domain.html#virDomainLookupByID">
-                <code>virDomainLookupByID</code>
-              </a>
-            </li>
-            <li>
-              <a href="html/libvirt-libvirt-domain.html#virDomainLookupByName">
-                <code>virDomainLookupByName</code>
-              </a>
-            </li>
-            <li>
-              <a href="html/libvirt-libvirt-domain.html#virDomainLookupByUUID">
-                <code>virDomainLookupByUUID</code>
-              </a>
-            </li>
-            <li>
-              <a href="html/libvirt-libvirt-domain.html#virDomainLookupByUUIDString">
-                <code>virDomainLookupByUUIDString</code>
-              </a>
-            </li>
-          </ul>
-      </li>
-      <li><b>Enumeration</b> [virConnectList..., virConnectNumOf...]
-      <p>Used to enumerate a set of object available to a given
-      hypervisor connection such as:</p>
-          <ul>
-            <li>
-              <a href="html/libvirt-libvirt-domain.html#virConnectListDomains">
-                <code>virConnectListDomains</code>
-              </a>
-            </li>
-            <li>
-              <a href="html/libvirt-libvirt-domain.html#virConnectNumOfDomains">
-                <code>virConnectNumOfDomains</code>
-              </a>
-            </li>
-            <li>
-              <a href="html/libvirt-libvirt-network.html#virConnectListNetworks">
-                <code>virConnectListNetworks</code>
-              </a>
-            </li>
-            <li>
-              <a href="html/libvirt-libvirt-storage.html#virConnectListStoragePools">
-                <code>virConnectListStoragePools</code>
-              </a>
-            </li>
-          </ul>
-      </li>
-      <li><b>Description</b> [...GetInfo]
-      <p>Generic accessor providing a set of generic information about an
-      object, such as: </p>
-        <ul>
-          <li>
-            <a href="html/libvirt-libvirt-host.html#virNodeGetInfo">
-              <code>virNodeGetInfo</code>
-            </a>
-          </li>
-          <li>
-            <a href="html/libvirt-libvirt-domain.html#virDomainGetInfo">
-              <code>virDomainGetInfo</code>
-            </a>
-          </li>
-          <li>
-            <a href="html/libvirt-libvirt-storage.html#virStoragePoolGetInfo">
-              <code>virStoragePoolGetInfo</code>
-            </a>
-          </li>
-          <li>
-            <a href="html/libvirt-libvirt-storage.html#virStorageVolGetInfo">
-              <code>virStorageVolGetInfo</code>
-            </a>
-          </li>
-        </ul>
-      </li>
-      <li><b>Accessors</b> [...Get..., ...Set...]
-      <p>Specific accessors used to query or modify data for the given object,
-      such as: </p>
-        <ul>
-          <li>
-            <a href="html/libvirt-libvirt-host.html#virConnectGetType">
-              <code>virConnectGetType</code>
-            </a>
-          </li>
-          <li>
-            <a href="html/libvirt-libvirt-domain.html#virDomainGetMaxMemory">
-              <code>virDomainGetMaxMemory</code>
-            </a>
-          </li>
-          <li>
-            <a href="html/libvirt-libvirt-domain.html#virDomainSetMemory">
-              <code>virDomainSetMemory</code>
-            </a>
-          </li>
-          <li>
-            <a href="html/libvirt-libvirt-domain.html#virDomainGetVcpus">
-              <code>virDomainGetVcpus</code>
-            </a>
-          </li>
-          <li>
-            <a href="html/libvirt-libvirt-storage.html#virStoragePoolSetAutostart">
-              <code>virStoragePoolSetAutostart</code>
-            </a>
-          </li>
-          <li>
-            <a href="html/libvirt-libvirt-network.html#virNetworkGetBridgeName">
-              <code>virNetworkGetBridgeName</code>
-            </a>
-          </li>
-        </ul>
-      </li>
-      <li><b>Creation</b> [...Create, ...CreateXML]
-      <p>Used to create and start objects.  The ...CreateXML APIs will create
-      the object based on an XML description, while the ...Create APIs will
-      create the object based on existing object pointer, such as: </p>
-        <ul>
-          <li>
-            <a href="html/libvirt-libvirt-domain.html#virDomainCreate">
-              <code>virDomainCreate</code>
-            </a>
-          </li>
-          <li>
-            <a href="html/libvirt-libvirt-domain.html#virDomainCreateXML">
-              <code>virDomainCreateXML</code>
-            </a>
-          </li>
-          <li>
-            <a href="html/libvirt-libvirt-network.html#virNetworkCreate">
-              <code>virNetworkCreate</code>
-            </a>
-          </li>
-          <li>
-            <a href="html/libvirt-libvirt-network.html#virNetworkCreateXML">
-              <code>virNetworkCreateXML</code>
-            </a>
-          </li>
-        </ul>
-      </li>
-      <li><b>Destruction</b> [...Destroy]
-      <p>Used to shutdown or deactivate and destroy objects, such as: </p>
-        <ul>
-          <li>
-            <a href="html/libvirt-libvirt-domain.html#virDomainDestroy">
-              <code>virDomainDestroy</code>
-            </a>
-          </li>
-          <li>
-            <a href="html/libvirt-libvirt-network.html#virNetworkDestroy">
-              <code>virNetworkDestroy</code>
-            </a>
-          </li>
-          <li>
-            <a href="html/libvirt-libvirt-storage.html#virStoragePoolDestroy">
-              <code>virStoragePoolDestroy</code>
-            </a>
-          </li>
-        </ul>
-      </li>
-    </ul>
-    <p>Note: functions returning vir*Ptr (like the virDomainLookup functions)
-    allocate memory which needs to be freed by the caller by the corresponding
-    vir*Free function (e.g. virDomainFree for a virDomainPtr object).
-    </p>
-    <p> For more in-depth details of the storage related APIs see
-      <a href="storage.html">the storage management page</a>.
-    </p>
-    <h2><a id="Drivers">The libvirt Drivers</a></h2>
-    <p>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
-      <a href="html/libvirt-libvirt-host.html#virInitialize">
-        <code>virInitialize</code>
-      </a>
-    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
-    drivers as a series of modules that can be plugged into the architecture
-    depending on how libvirt is configured to be built.</p>
-    <p class="image">
-      <img alt="The libvirt driver architecture"
-           src="libvirt-driver-arch.png"/>
-    </p>
-    <p>The driver architecture is also used to support other virtualization
-    components such as storage, storage pools, host device, networking,
-    network interfaces, and network filters.</p>
-    <p>See the <a href="drivers.html">libvirt drivers</a> page for more
-    information on hypervisor and storage specific drivers.</p>
-    <p>Not all drivers support every virtualization function possible.
-    The <a href="hvsupport.html">libvirt API support matrix</a> lists
-    the various functions and support found in each driver by the version
-    support was added into libvirt.
-    </p>
-    <h2><a id="Remote">Daemon and Remote Access</a></h2>
-    <p>Access to libvirt drivers is primarily handled by the libvirtd
-    daemon through the <a href="remote.html">remote</a> driver via an
-    <a href="internals/rpc.html">RPC</a>. Some hypervisors do support
-    client-side connections and responses, such as Test, OpenVZ, VMware,
-    VirtualBox (vbox), ESX, Hyper-V, Xen, and Virtuozzo.
-    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
-    <a href="html/libvirt-libvirt-host.html#virInitialize">
-      <code>virInitialize</code>
-    </a>
-    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. </p>
-    <p>The libvirt client <a href="apps.html">applications</a> use a
-    <a href="uri.html">URI</a> to obtain the <code>virConnectPtr</code>.
-    The <code>virConnectPtr</code> keeps track of the driver connection
-    plus a variety of other connections (network, interface, storage, etc.).
-    The <code>virConnectPtr</code> is then used as a parameter to other
-    virtualization <a href="#Functions">functions</a>. Depending upon the
-    driver being used, calls will be routed through the remote driver to
-    the libvirtd daemon. The daemon will reference the connection specific
-    driver in order to retrieve the requested information and then pass
-    back status and/or data through the connection back to the application.
-    The application can then decide what to do with that data, such as
-    display, write log data, etc. <a href="migration.html">Migration</a>
-    is an example of many facets of the architecture in use.</p>
-
-    <p class="image">
-      <img alt="The libvirt daemon and remote architecture"
-           src="libvirt-daemon-arch.png"/>
-    </p>
-    <p>
-    The key takeaway from the above diagram is that there is a remote driver
-    which handles transactions for a majority of the drivers. The libvirtd
-    daemon running on the host will receive transaction requests from the
-    remote driver and will then query the hypervisor driver as specified in
-    the <code>virConnectPtr</code> in order to fetch the data. The data will
-    then be returned through the remote driver to the client application
-    for processing.
-    </p>
-    <p>If you are interested in contributing to libvirt, read the
-    <a href="https://wiki.libvirt.org/page/FAQ";>FAQ</a> and
-    <a href="hacking.html">hacking</a> guidelines to gain an understanding
-    of basic rules and guidelines.  In order to add new API functionality
-    follow the instructions regarding
-    <a href="api_extension.html">implementing a new API in libvirt</a>.
-    </p>
-
-  </body>
-</html>
diff --git a/docs/api.rst b/docs/api.rst
new file mode 100644
index 0000000000..a8f527e197
--- /dev/null
+++ b/docs/api.rst
@@ -0,0 +1,265 @@
+========================
+The libvirt API concepts
+========================
+
+This page describes the main principles and architecture choices behind
+the definition of the libvirt API:
+
+.. contents::
+
+Objects Exposed
+---------------
+
+As defined in the `goals section <goals.html>`__, the libvirt API is
+designed to expose all the resources needed to manage the virtualization
+support of recent operating systems. The first object 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 <html/libvirt-libvirt-host.html#virConnectOpen>`__. You will
+note that those functions take a name argument which is actually a
+`connection URI <uri.html>`__ to select the right hypervisor to open. A
+URI is needed to allow remote connections and also select between
+different possible hypervisors. For example, on a Linux system it may be
+possible to use both KVM and LinuxContainers on the same node. A NULL
+name will default to a preselected hypervisor, but it's probably not a
+wise thing to do in most cases. See the `connection URI <uri.html>`__
+page for a full descriptions of the values allowed.
+
+OnDevice the application obtains a
+`virConnectPtr </html/libvirt-libvirt-host.html#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 exposed as first class
+objects and connected to the hypervisor connection (and the node or
+cluster where it is available).
+
+|first class objects exposed by the API|
+
+The figure above shows the five main objects exported by the API:
+
+-  `virConnectPtr <html/libvirt-libvirt-host.html#virConnectPtr>`__
+
+   Represents the connection to a hypervisor. Use one of the
+   `virConnectOpen <html/libvirt-libvirt-host.html#virConnectOpen>`__
+   functions to obtain connection to the hypervisor which is then used
+   as a parameter to other connection API's.
+
+-  `virDomainPtr <html/libvirt-libvirt-domain.html#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 <html/libvirt-libvirt-domain.html#virConnectListAllDomains>`__
+   lists all the domains for the hypervisor.
+
+-  `virNetworkPtr <html/libvirt-libvirt-network.html#virNetworkPtr>`__
+
+   Represents one network either active or defined (i.e. existing as
+   permanent config file and storage but not currently activated). The
+   function
+   `virConnectListAllNetworks <html/libvirt-libvirt-network.html#virConnectListAllNetworks>`__
+   lists all the virtualization networks for the hypervisor.
+
+-  `virStorageVolPtr <html/libvirt-libvirt-storage.html#virStorageVolPtr>`__
+
+   Represents one storage volume generally used as a block device
+   available to one of the domains. The function
+   `virStorageVolLookupByPath <html/libvirt-libvirt-storage.html#virStorageVolLookupByPath>`__
+   finds the storage volume object based on its path on the node.
+
+-  `virStoragePoolPtr <html/libvirt-libvirt-storage.html#virStoragePoolPtr>`__
+
+   Represents a storage pool, which is a logical area used to allocate
+   and store storage volumes. The function
+   `virConnectListAllStoragePools <html/libvirt-libvirt-storage.html#virConnectListAllStoragePools>`__
+   lists all of the virtualization storage pools on the hypervisor. The
+   function
+   `virStoragePoolLookupByVolume <html/libvirt-libvirt-storage.html#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
+also helpful to modify or save their description back.
+
+Domains, networks, and storage pools can be either ``active`` i.e.
+either running or available for immediate use, or ``defined`` in which
+case they are inactive but there is a permanent definition available in
+the system for them. Based on this they can be activated dynamically in
+order to be used.
+
+Most objects can also be named in various ways:
+
+-  ``name``
+
+   A user friendly identifier but whose uniqueness cannot be guaranteed
+   between two nodes.
+
+-  ``ID``
+
+   A runtime unique identifier provided by the hypervisor for one given
+   activation of the object; however, it becomes invalid once the
+   resource is deactivated.
+
+-  ``UUID``
+
+   A 16 byte unique identifier as defined in `RFC
+   4122 <https://www.ietf.org/rfc/rfc4122.txt>`__, which is guaranteed
+   to be unique for long term usage and across a set of nodes.
+
+Functions and Naming Conventions
+--------------------------------
+
+The naming of the functions present in the library is usually composed
+by a prefix describing the object associated to the function and a verb
+describing the action on that object.
+
+For each first class object you will find APIs for the following
+actions:
+
+-  **Lookup** [...LookupBy...]
+
+   Used to perform lookups on objects by some type of identifier, such
+   as:
+
+   -  `virDomainLookupByID <html/libvirt-libvirt-domain.html#virDomainLookupByID>`__
+   -  `virDomainLookupByName <html/libvirt-libvirt-domain.html#virDomainLookupByName>`__
+   -  `virDomainLookupByUUID <html/libvirt-libvirt-domain.html#virDomainLookupByUUID>`__
+   -  `virDomainLookupByUUIDString <html/libvirt-libvirt-domain.html#virDomainLookupByUUIDString>`__
+
+-  **Enumeration** [virConnectList..., virConnectNumOf...]
+
+   Used to enumerate a set of object available to a given hypervisor
+   connection such as:
+
+   -  `virConnectListDomains <html/libvirt-libvirt-domain.html#virConnectListDomains>`__
+   -  `virConnectNumOfDomains <html/libvirt-libvirt-domain.html#virConnectNumOfDomains>`__
+   -  `virConnectListNetworks <html/libvirt-libvirt-network.html#virConnectListNetworks>`__
+   -  `virConnectListStoragePools <html/libvirt-libvirt-storage.html#virConnectListStoragePools>`__
+
+-  **Description** [...GetInfo]
+
+   Generic accessor providing a set of generic information about an
+   object, such as:
+
+   -  `virNodeGetInfo <html/libvirt-libvirt-host.html#virNodeGetInfo>`__
+   -  `virDomainGetInfo <html/libvirt-libvirt-domain.html#virDomainGetInfo>`__
+   -  `virStoragePoolGetInfo <html/libvirt-libvirt-storage.html#virStoragePoolGetInfo>`__
+   -  `virStorageVolGetInfo <html/libvirt-libvirt-storage.html#virStorageVolGetInfo>`__
+
+-  **Accessors** [...Get..., ...Set...]
+
+   Specific accessors used to query or modify data for the given object,
+   such as:
+
+   -  `virConnectGetType <html/libvirt-libvirt-host.html#virConnectGetType>`__
+   -  `virDomainGetMaxMemory <html/libvirt-libvirt-domain.html#virDomainGetMaxMemory>`__
+   -  `virDomainSetMemory <html/libvirt-libvirt-domain.html#virDomainSetMemory>`__
+   -  `virDomainGetVcpus <html/libvirt-libvirt-domain.html#virDomainGetVcpus>`__
+   -  `virStoragePoolSetAutostart <html/libvirt-libvirt-storage.html#virStoragePoolSetAutostart>`__
+   -  `virNetworkGetBridgeName <html/libvirt-libvirt-network.html#virNetworkGetBridgeName>`__
+
+-  **Creation** [...Create, ...CreateXML]
+
+   Used to create and start objects. The ...CreateXML APIs will create
+   the object based on an XML description, while the ...Create APIs will
+   create the object based on existing object pointer, such as:
+
+   -  `virDomainCreate <html/libvirt-libvirt-domain.html#virDomainCreate>`__
+   -  `virDomainCreateXML <html/libvirt-libvirt-domain.html#virDomainCreateXML>`__
+   -  `virNetworkCreate <html/libvirt-libvirt-network.html#virNetworkCreate>`__
+   -  `virNetworkCreateXML <html/libvirt-libvirt-network.html#virNetworkCreateXML>`__
+
+-  **Destruction** [...Destroy]
+
+   Used to shutdown or deactivate and destroy objects, such as:
+
+   -  `virDomainDestroy <html/libvirt-libvirt-domain.html#virDomainDestroy>`__
+   -  `virNetworkDestroy <html/libvirt-libvirt-network.html#virNetworkDestroy>`__
+   -  `virStoragePoolDestroy <html/libvirt-libvirt-storage.html#virStoragePoolDestroy>`__
+
+Note: functions returning vir*Ptr (like the virDomainLookup functions)
+allocate memory which needs to be freed by the caller by the
+corresponding vir*Free function (e.g. virDomainFree for a virDomainPtr
+object).
+
+For more in-depth details of the storage related APIs see `the storage
+management page <storage.html>`__.
+
+The libvirt Drivers
+-------------------
+
+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 <html/libvirt-libvirt-host.html#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 drivers as a series of modules that can be plugged into
+the architecture depending on how libvirt is configured to be built.
+
+|The libvirt driver architecture|
+
+The driver architecture is also used to support other virtualization
+components such as storage, storage pools, host device, networking,
+network interfaces, and network filters.
+
+See the `libvirt drivers <drivers.html>`__ page for more information on
+hypervisor and storage specific drivers.
+
+Not all drivers support every virtualization function possible. The
+`libvirt API support matrix <hvsupport.html>`__ lists the various
+functions and support found in each driver by the version support was
+added into libvirt.
+
+Daemon and Remote Access
+------------------------
+
+Access to libvirt drivers is primarily handled by the libvirtd daemon
+through the `remote <remote.html>`__ driver via an
+`RPC <internals/rpc.html>`__. Some hypervisors do support client-side
+connections and responses, such as Test, OpenVZ, VMware, VirtualBox
+(vbox), ESX, Hyper-V, Xen, and Virtuozzo. 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 <html/libvirt-libvirt-host.html#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.
+
+The libvirt client `applications <apps.html>`__ use a `URI <uri.html>`__
+to obtain the ``virConnectPtr``. The ``virConnectPtr`` keeps track of
+the driver connection plus a variety of other connections (network,
+interface, storage, etc.). The ``virConnectPtr`` is then used as a
+parameter to other virtualization `functions <#Functions>`__. Depending
+upon the driver being used, calls will be routed through the remote
+driver to the libvirtd daemon. The daemon will reference the connection
+specific driver in order to retrieve the requested information and then
+pass back status and/or data through the connection back to the
+application. The application can then decide what to do with that data,
+such as display, write log data, etc. `Migration <migration.html>`__ is
+an example of many facets of the architecture in use.
+
+|The libvirt daemon and remote architecture|
+
+The key takeaway from the above diagram is that there is a remote driver
+which handles transactions for a majority of the drivers. The libvirtd
+daemon running on the host will receive transaction requests from the
+remote driver and will then query the hypervisor driver as specified in
+the ``virConnectPtr`` in order to fetch the data. The data will then be
+returned through the remote driver to the client application for
+processing.
+
+If you are interested in contributing to libvirt, read the
+`FAQ <https://wiki.libvirt.org/page/FAQ>`__ and
+`hacking <hacking.html>`__ guidelines to gain an understanding of basic
+rules and guidelines. In order to add new API functionality follow the
+instructions regarding `implementing a new API in
+libvirt <api_extension.html>`__.
+
+.. |first class objects exposed by the API| image:: libvirt-object-model.png
+.. |The libvirt driver architecture| image:: libvirt-driver-arch.png
+.. |The libvirt daemon and remote architecture| image:: libvirt-daemon-arch.png
diff --git a/docs/meson.build b/docs/meson.build
index b031bd6717..942cce6fdc 100644
--- a/docs/meson.build
+++ b/docs/meson.build
@@ -32,7 +32,6 @@ docs_assets = [
 
 docs_html_in_files = [
   '404',
-  'api',
   'apps',
   'architecture',
   'auditlog',
@@ -107,6 +106,7 @@ docs_rst_files = [
   'aclpolkit',
   'advanced-tests',
   'api_extension',
+  'api',
   'best-practices',
   'ci',
   'coding-style',
-- 
2.29.2




[Index of Archives]     [Virt Tools]     [Libvirt Users]     [Lib OS Info]     [Fedora Users]     [Fedora Desktop]     [Fedora SELinux]     [Big List of Linux Books]     [Yosemite News]     [KDE Users]     [Fedora Tools]

  Powered by Linux