[PATCH 04/17] docs: Convert 'goals' to rST

Mon Mar 7 15:59:24 UTC 2022

Signed-off-by: Peter Krempa <pkrempa at redhat.com>
---
 docs/goals.html.in | 64 ----------------------------------------------
 docs/goals.rst     | 56 ++++++++++++++++++++++++++++++++++++++++
 docs/meson.build   |  2 +-
 3 files changed, 57 insertions(+), 65 deletions(-)
 delete mode 100644 docs/goals.html.in
 create mode 100644 docs/goals.rst

diff --git a/docs/goals.html.in b/docs/goals.html.in
deleted file mode 100644
index f1639338ad..0000000000
--- a/docs/goals.html.in
+++ /dev/null
@@ -1,64 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE html>
-<html xmlns="http://www.w3.org/1999/xhtml">
-  <body>
-    <h1>Terminology and goals</h1>
-    <p>To avoid ambiguity about the terms used, here are the definitions
-       for some of the specific concepts used in libvirt documentation:</p>
-    <ul>
-      <li>a <strong>node</strong> is a single physical machine</li>
-      <li>an <strong>hypervisor</strong> is a layer of software allowing to
-    virtualize a node in a set of virtual machines with possibly different
-    configurations than the node itself</li>
-      <li>a <strong>domain</strong> is an instance of an operating system
-    (or subsystem in the case of container virtualization) running on a
-    virtualized machine provided by the hypervisor</li>
-    </ul>
-    <p>Now we can define the goal of libvirt: <b> to provide a common and
-    stable layer sufficient to securely manage domains on a node, possibly
-    remote</b>.</p>
-    <p> As a result, libvirt should provide all APIs needed to do the
-    management, such as: provision, create, modify, monitor, control, migrate
-    and stop the domains - within the limits of the support of the hypervisor
-    for those operations.
-    Not all hypervisors provide the same operations; but if an operation is
-    useful for domain management of even one specific hypervisor it is worth
-    providing in libvirt.
-    Multiple nodes
-    may be accessed with libvirt simultaneously, but the APIs are limited to
-    single node operations. Node resource operations which are needed
-    for the management and provisioning of domains are also in the scope of
-    the libvirt API, such as interface setup, firewall rules, storage management
-    and general provisioning APIs. Libvirt will also provide the state
-    monitoring APIs needed to implement management policies, obviously
-    checking domain state but also exposing local node resource consumption.
-    </p>
-    <p>This implies the following sub-goals:</p>
-    <ul>
-      <li>All API can be carried remotely though secure APIs</li>
-      <li>While most API will be generic in term of hypervisor or Host OS,
-    some API may be targeted to a single virtualization environment
-    as long as the semantic for the operations from a domain management
-    perspective is clear</li>
-      <li>the API should allow to do efficiently and cleanly all the operations
-    needed to manage domains on a node, including resource provisioning and
-    setup</li>
-      <li>the API will not try to provide high level virtualization policies or
-    multi-nodes management features like load balancing, but the API should be
-    sufficient so they can be implemented on top of libvirt</li>
-      <li>stability of the API is a big concern, libvirt should isolate
-    applications from the frequent changes expected at the lower level of the
-    virtualization framework</li>
-      <li>the node being managed may be on a different physical machine than
-    the management program using libvirt, to this effect libvirt supports
-    remote access, but should only do so by using secure protocols.</li>
-      <li>libvirt will provide APIs to enumerate, monitor and use the resources
-    available on the managed node, including CPUs, memory, storage, networking,
-    and NUMA partitions.</li>
-    </ul>
-    <p>So libvirt is intended to be a building block for higher level
-    management tools and for applications focusing on virtualization of a
-    single node (the only exception being domain migration between node
-    capabilities which involves more than one node).</p>
-  </body>
-</html>
diff --git a/docs/goals.rst b/docs/goals.rst
new file mode 100644
index 0000000000..7385f27b61
--- /dev/null
+++ b/docs/goals.rst
@@ -0,0 +1,56 @@
+=====================
+Terminology and goals
+=====================
+
+To avoid ambiguity about the terms used, here are the definitions for some of
+the specific concepts used in libvirt documentation:
+
+-  a **node** is a single physical machine
+-  an **hypervisor** is a layer of software allowing to virtualize a node in a
+   set of virtual machines with possibly different configurations than the node
+   itself
+-  a **domain** is an instance of an operating system (or subsystem in the case
+   of container virtualization) running on a virtualized machine provided by the
+   hypervisor
+
+Now we can define the goal of libvirt: **to provide a common and stable layer
+sufficient to securely manage domains on a node, possibly remote**.
+
+As a result, libvirt should provide all APIs needed to do the management, such
+as: provision, create, modify, monitor, control, migrate and stop the domains -
+within the limits of the support of the hypervisor for those operations. Not all
+hypervisors provide the same operations; but if an operation is useful for
+domain management of even one specific hypervisor it is worth providing in
+libvirt. Multiple nodes may be accessed with libvirt simultaneously, but the
+APIs are limited to single node operations. Node resource operations which are
+needed for the management and provisioning of domains are also in the scope of
+the libvirt API, such as interface setup, firewall rules, storage management and
+general provisioning APIs. Libvirt will also provide the state monitoring APIs
+needed to implement management policies, obviously checking domain state but
+also exposing local node resource consumption.
+
+This implies the following sub-goals:
+
+-  All API can be carried remotely though secure APIs
+-  While most API will be generic in term of hypervisor or Host OS, some API may
+   be targeted to a single virtualization environment as long as the semantic
+   for the operations from a domain management perspective is clear
+-  the API should allow to do efficiently and cleanly all the operations needed
+   to manage domains on a node, including resource provisioning and setup
+-  the API will not try to provide high level virtualization policies or
+   multi-nodes management features like load balancing, but the API should be
+   sufficient so they can be implemented on top of libvirt
+-  stability of the API is a big concern, libvirt should isolate applications
+   from the frequent changes expected at the lower level of the virtualization
+   framework
+-  the node being managed may be on a different physical machine than the
+   management program using libvirt, to this effect libvirt supports remote
+   access, but should only do so by using secure protocols.
+-  libvirt will provide APIs to enumerate, monitor and use the resources
+   available on the managed node, including CPUs, memory, storage, networking,
+   and NUMA partitions.
+
+So libvirt is intended to be a building block for higher level management tools
+and for applications focusing on virtualization of a single node (the only
+exception being domain migration between node capabilities which involves more
+than one node).
diff --git a/docs/meson.build b/docs/meson.build
index adb7ac091e..afed104014 100644
--- a/docs/meson.build
+++ b/docs/meson.build
@@ -53,7 +53,6 @@ docs_html_in_files = [
   'formatsecret',
   'formatstoragecaps',
   'formatstorageencryption',
-  'goals',
   'governance',
   'hooks',
   'index',
@@ -101,6 +100,7 @@ docs_rst_files = [
   'formatsnapshot',
   'formatstorage',
   'glib-adoption',
+  'goals',
   'hacking',
   'libvirt-go',
   'libvirt-go-xml',
-- 
2.35.1

