[PATCH 21/29] docs: Convert 'formatstoragecaps' page to rST
Peter Krempa
pkrempa at redhat.com
Mon Mar 28 12:10:36 UTC 2022
Note that if we want to preserve the link from the code block hilighting
'virConnectGetStoragePoolCapabilities' we'd need to re-stylize it as rST
doesn't support nesting of links into preformatted code blocks.
Signed-off-by: Peter Krempa <pkrempa at redhat.com>
---
docs/formatstoragecaps.html.in | 95 ----------------------------------
docs/formatstoragecaps.rst | 81 +++++++++++++++++++++++++++++
docs/meson.build | 2 +-
3 files changed, 82 insertions(+), 96 deletions(-)
delete mode 100644 docs/formatstoragecaps.html.in
create mode 100644 docs/formatstoragecaps.rst
diff --git a/docs/formatstoragecaps.html.in b/docs/formatstoragecaps.html.in
deleted file mode 100644
index a9ecc371fa..0000000000
--- a/docs/formatstoragecaps.html.in
+++ /dev/null
@@ -1,95 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE html>
-<html xmlns="http://www.w3.org/1999/xhtml">
- <body>
- <h1>Storage Pool Capabilities XML format</h1>
-
- <ul id="toc"></ul>
-
- <h2><a id="Overview">Overview</a></h2>
-
- <p>The Storage Pool Capabilities XML will provide the information
- to determine what types of Storage Pools exist, whether the pool is
- supported, and if relevant the source format types, the required
- source elements, and the target volume format types. </p>
-
- <h2><a id="elements">Element and attribute overview</a></h2>
-
- <p>A query interface was added to the virConnect API's to retrieve the
- XML listing of the set of Storage Pool Capabilities
- (<span class="since">Since 5.2.0</span>):</p>
-
-<pre>
-<a href="/html/libvirt-libvirt-storage.html#virConnectGetStoragePoolCapabilities">virConnectGetStoragePoolCapabilities</a>
-</pre>
-
- <p>The root element that emulator capability XML document starts with is
- named <code>storagepoolCapabilities</code>. There will be any number of
- <code>pool</code> child elements with two attributes <code>type</code>
- and <code>supported</code>. Each <code>pool</code> element may have
- a <code>poolOptions</code> or <code>volOptions</code> subelements to
- describe the available features. Sample XML output is:</p>
-
-<pre>
-<storagepoolCapabilities>
- <pool type='dir' supported='yes'>
- <volOptions>
- <defaultFormat type='raw'</>
- <enum name='targetFormatType'>
- <value>none</value>
- <value>raw</value>
- ...
- </enum>
- </volOptions>
- </pool>
- <pool type='fs' supported='yes'>
- <poolOptions>
- <defaultFormat type='auto'</>
- <enum name='sourceFormatType'>
- <value>auto</value>
- <value>ext2</value>
- ...
- </enum>
- </poolOptions>
- <volOptions>
- <defaultFormat type='raw'</>
- <enum name='targetFormatType'>
- <value>none</value>
- <value>raw</value>
- ...
- </enum>
- </volOptions>
- </pool>
- ...
-</storagepoolCapabilities>
-</pre>
-
- <p>The following section describes subelements of the
- <code>poolOptions</code> and <code>volOptions</code> subelements </p>:
-
- <dl>
- <dt><code>defaultFormat</code></dt>
- <dd>For the <code>poolOptions</code>, the <code>type</code> attribute
- describes the default format name used for the pool source. For the
- <code>volOptions</code>, the <code>type</code> attribute describes
- the default volume name used for each volume.
- </dd>
- <dl>
- <dt><code>enum</code></dt>
- <dd>Each enum uses a name from the list below with any number of
- <code>value</code> value subelements describing the valid values.
- <dl>
- <dt><code>sourceFormatType</code></dt>
- <dd>Lists all the possible <code>poolOptions</code> source
- pool format types.
- </dd>
- <dt><code>targetFormatType</code></dt>
- <dd>Lists all the possible <code>volOptions</code> target volume
- format types.
- </dd>
- </dl>
- </dd>
- </dl>
- </dl>
- </body>
-</html>
diff --git a/docs/formatstoragecaps.rst b/docs/formatstoragecaps.rst
new file mode 100644
index 0000000000..32cd392931
--- /dev/null
+++ b/docs/formatstoragecaps.rst
@@ -0,0 +1,81 @@
+.. role:: since
+
+====================================
+Storage Pool Capabilities XML format
+====================================
+
+.. contents::
+
+Overview
+--------
+
+The Storage Pool Capabilities XML will provide the information to determine what
+types of Storage Pools exist, whether the pool is supported, and if relevant the
+source format types, the required source elements, and the target volume format
+types.
+
+Element and attribute overview
+------------------------------
+
+A query interface was added to the virConnect API's to retrieve the XML listing
+of the set of Storage Pool Capabilities ( :since:`Since 5.2.0` ):
+
+::
+
+ virConnectGetStoragePoolCapabilities
+
+The root element that emulator capability XML document starts with is named
+``storagepoolCapabilities``. There will be any number of ``pool`` child elements
+with two attributes ``type`` and ``supported``. Each ``pool`` element may have a
+``poolOptions`` or ``volOptions`` subelements to describe the available
+features. Sample XML output is:
+
+::
+
+ <storagepoolCapabilities>
+ <pool type='dir' supported='yes'>
+ <volOptions>
+ <defaultFormat type='raw'</>
+ <enum name='targetFormatType'>
+ <value>none</value>
+ <value>raw</value>
+ ...
+ </enum>
+ </volOptions>
+ </pool>
+ <pool type='fs' supported='yes'>
+ <poolOptions>
+ <defaultFormat type='auto'</>
+ <enum name='sourceFormatType'>
+ <value>auto</value>
+ <value>ext2</value>
+ ...
+ </enum>
+ </poolOptions>
+ <volOptions>
+ <defaultFormat type='raw'</>
+ <enum name='targetFormatType'>
+ <value>none</value>
+ <value>raw</value>
+ ...
+ </enum>
+ </volOptions>
+ </pool>
+ ...
+ </storagepoolCapabilities>
+
+The following section describes subelements of the ``poolOptions`` and
+``volOptions`` subelements
+
+``defaultFormat``
+ For the ``poolOptions``, the ``type`` attribute describes the default format
+ name used for the pool source. For the ``volOptions``, the ``type`` attribute
+ describes the default volume name used for each volume.
+``enum``
+ Each enum uses a name from the list below with any number of ``value`` value
+ subelements describing the valid values.
+
+ ``sourceFormatType``
+ Lists all the possible ``poolOptions`` source pool format types.
+ ``targetFormatType``
+ Lists all the possible ``volOptions`` target volume format types.
diff --git a/docs/meson.build b/docs/meson.build
index bb1359aacd..b911292480 100644
--- a/docs/meson.build
+++ b/docs/meson.build
@@ -25,7 +25,6 @@ docs_html_in_files = [
'formatnetwork',
'formatnode',
'formatnwfilter',
- 'formatstoragecaps',
'formatstorageencryption',
'hooks',
'index',
@@ -88,6 +87,7 @@ docs_rst_files = [
'formatsecret',
'formatsnapshot',
'formatstorage',
+ 'formatstoragecaps',
'glib-adoption',
'goals',
'governance',
--
2.35.1
More information about the libvir-list
mailing list