.gitignore | 1 + docs/Makefile.am | 9 +++-- docs/apibuild.py | 2 ++ docs/storage.html.in | 14 ++++++++ docs/storagebackendstatus.py | 64 ++++++++++++++++++++++++++++++++++++ 5 files changed, 88 insertions(+), 2 deletions(-) create mode 100644 docs/storagebackendstatus.py
Since it helps a user to know which of the storage backends support what
operation, include an autogenerated matrix showing it in the docs.
---
.gitignore | 1 +
docs/Makefile.am | 9 +++--
docs/apibuild.py | 2 ++
docs/storage.html.in | 14 ++++++++
docs/storagebackendstatus.py | 64 ++++++++++++++++++++++++++++++++++++
5 files changed, 88 insertions(+), 2 deletions(-)
create mode 100644 docs/storagebackendstatus.py
diff --git a/.gitignore b/.gitignore
index 82495e8692..06875abebd 100644
--- a/.gitignore
+++ b/.gitignore
@@ -58,6 +58,7 @@
/configure.lineno
/conftest.*
/docs/aclperms.htmlinc
+/docs/storagebackendstatus.htmlinc
/docs/apibuild.py.stamp
/docs/devhelp/libvirt.devhelp
/docs/hvsupport.html.in
diff --git a/docs/Makefile.am b/docs/Makefile.am
index 1cdb584b0b..526821b1d3 100644
--- a/docs/Makefile.am
+++ b/docs/Makefile.am
@@ -195,6 +195,7 @@ EXTRA_DIST= \
$(kbase_html_in) $(kbase_html) \
aclperms.htmlinc \
hvsupport.pl \
+ storagebackendstatus.py \
$(schema_DATA)
acl_generated = aclperms.htmlinc
@@ -209,7 +210,8 @@ MAINTAINERCLEANFILES = \
$(addprefix $(srcdir)/,$(devhelphtml)) \
$(addprefix $(srcdir)/,$(internals_html)) \
$(addprefix $(srcdir)/,$(kbase_html)) \
- $(srcdir)/hvsupport.html.in $(srcdir)/aclperms.htmlinc
+ $(srcdir)/hvsupport.html.in $(srcdir)/aclperms.htmlinc \
+ $(srcdir)/storagebackendstatus.htmlinc
timestamp="$(shell if test -n "$$SOURCE_DATE_EPOCH"; \
then \
@@ -230,6 +232,9 @@ web: $(dot_html) $(internals_html) $(kbase_html) \
hvsupport.html: $(srcdir)/hvsupport.html.in
+storagebackendstatus.htmlinc: $(srcdir)/storagebackendstatus.py
+ $(PYTHON) $< >$@
+
$(srcdir)/hvsupport.html.in: $(srcdir)/hvsupport.pl $(api_DATA) \
$(top_srcdir)/src/libvirt_public.syms \
$(top_srcdir)/src/libvirt_qemu.syms $(top_srcdir)/src/libvirt_lxc.syms \
@@ -256,7 +261,7 @@ MAINTAINERCLEANFILES += \
convert -rotate 90 $< $@
%.html.tmp: %.html.in site.xsl subsite.xsl page.xsl \
- $(acl_generated)
+ $(acl_generated) storagebackendstatus.htmlinc
$(AM_V_GEN)name=`echo $@ | sed -e 's/.tmp//'`; \
dir=`dirname $@` ; \
if test "$$dir" = "."; \
diff --git a/docs/apibuild.py b/docs/apibuild.py
index dbdc1c95af..31944b8176 100755
--- a/docs/apibuild.py
+++ b/docs/apibuild.py
@@ -2010,6 +2010,8 @@ class docBuilder:
self.includes = includes + list(lxc_included_files.keys())
elif name == "libvirt-admin":
self.includes = includes + list(admin_included_files.keys())
+ else:
+ self.includes = includes
self.modules = {}
self.headers = {}
self.idx = index()
diff --git a/docs/storage.html.in b/docs/storage.html.in
index e0e4edec1e..2e4f662222 100644
--- a/docs/storage.html.in
+++ b/docs/storage.html.in
@@ -826,5 +826,19 @@
<h3>Valid volume format types</h3>
<p>The valid volume types are the same as for the directory pool.</p>
+
+ <h2>Storage Pool Types implementation status</h2>
+
+ <p>
+ The storage backends have different level of support of the various pool and volume actions.
+ Here is a matrix of the current support for each of them.
+ </p>
+
+ <p>
+ <strong>Note:</strong> some functions like Start and Stop will not trigger an exception when
+ called on a backend that doesn't implement them.
+ </p>
+
+ <div id="include" filename="storagebackendstatus.htmlinc"/>
</body>
</html>
diff --git a/docs/storagebackendstatus.py b/docs/storagebackendstatus.py
new file mode 100644
index 0000000000..d105fea626
--- /dev/null
+++ b/docs/storagebackendstatus.py
@@ -0,0 +1,64 @@
+import os
+import os.path
+import re
+
+srcdir = os.path.abspath((os.environ.get("srcdir", os.path.join("..", "src"))))
+
+def get_allowed_functions():
+ functions = []
+ with open(os.path.join(srcdir, 'storage', 'storage_backend.h'), 'r') as handle:
+ content = ''.join(handle.readlines())
+ definition = re.search('struct _virStorageBackend {([^}]+)}', content)
+ if definition is not None:
+ functions = re.findall('virStorageBackend[^ ]+ ([^;]+)', definition.group(1))
+ return functions
+
+class Backend:
+ def __init__(self, name, code):
+ self.name = name
+ self.functions = [member[1:] for member in re.findall('.([^ ]+) = ', code) if member != '.type']
+
+def get_backends():
+ backends = []
+ for root, dirs, files in os.walk(os.path.join(srcdir, 'storage')):
+ storage_impls = [os.path.join(root, f) for f in files if re.match('storage_backend_[^.]+.c', f)]
+ for impl in storage_impls:
+ handle = open(impl, 'r')
+ content = ''.join(handle.readlines())
+ handle.close()
+ chunks = re.findall('virStorageBackend virStorageBackend([^ ]+) = {([^}]*)}', content)
+ backends.extend([Backend(chunk[0], chunk[1]) for chunk in chunks])
+ return backends
+
+def main():
+ functions = get_allowed_functions()
+ backends = get_backends()
+
+ headers = '\n'.join(['<th>%s</th>' % backend.name for backend in backends])
+ rows = []
+ for func in functions:
+ cell_template = '<td style="text-align: center">%s</td>'
+ support = [cell_template % ('✔' if func in backend.functions else '') for backend in backends]
+ rows.append('\n'.join(['<tr>', '<td>%s</td>' % func] + support + ['</tr>']))
+
+ print('''<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE html>
+<html xmlns="http://www.w3.org/1999/xhtml">
+<body>
+<table class='top_table'>
+<thead>
+<tr>
+<th>
+</th>
+%s
+</tr>
+</thead>
+<tbody>
+%s
+</tbody>
+</table>
+</body>
+</html>''' % (headers, '\n'.join(rows)))
+
+if __name__ == '__main__':
+ main()
--
2.22.0
--
libvir-list mailing list
libvir-list@redhat.com
https://www.redhat.com/mailman/listinfo/libvir-list
On 8/27/19 11:17 AM, Cedric Bosdonnat wrote: > Since it helps a user to know which of the storage backends support what > operation, include an autogenerated matrix showing it in the docs. > --- > .gitignore | 1 + > docs/Makefile.am | 9 +++-- > docs/apibuild.py | 2 ++ > docs/storage.html.in | 14 ++++++++ > docs/storagebackendstatus.py | 64 ++++++++++++++++++++++++++++++++++++ > 5 files changed, 88 insertions(+), 2 deletions(-) > create mode 100644 docs/storagebackendstatus.py > > diff --git a/docs/storage.html.in b/docs/storage.html.in > index e0e4edec1e..2e4f662222 100644 > --- a/docs/storage.html.in > +++ b/docs/storage.html.in > @@ -826,5 +826,19 @@ > > <h3>Valid volume format types</h3> > <p>The valid volume types are the same as for the directory pool.</p> > + > + <h2>Storage Pool Types implementation status</h2> > + > + <p> > + The storage backends have different level of support of the various pool and volume actions. > + Here is a matrix of the current support for each of them. > + </p> > + > + <p> > + <strong>Note:</strong> some functions like Start and Stop will not trigger an exception when > + called on a backend that doesn't implement them. > + </p> > + > + <div id="include" filename="storagebackendstatus.htmlinc"/> > </body> > </html> I feel like this belongs to hvsupport.html better. Do you have any objection to that? Michal -- libvir-list mailing list libvir-list@redhat.com https://www.redhat.com/mailman/listinfo/libvir-list
On Tue, 2019-08-27 at 16:38 +0200, Michal Privoznik wrote: > On 8/27/19 11:17 AM, Cedric Bosdonnat wrote: > > Since it helps a user to know which of the storage backends support > > what > > operation, include an autogenerated matrix showing it in the docs. > > --- > > .gitignore | 1 + > > docs/Makefile.am | 9 +++-- > > docs/apibuild.py | 2 ++ > > docs/storage.html.in | 14 ++++++++ > > docs/storagebackendstatus.py | 64 > > ++++++++++++++++++++++++++++++++++++ > > 5 files changed, 88 insertions(+), 2 deletions(-) > > create mode 100644 docs/storagebackendstatus.py > > > > diff --git a/docs/storage.html.in b/docs/storage.html.in > > index e0e4edec1e..2e4f662222 100644 > > --- a/docs/storage.html.in > > +++ b/docs/storage.html.in > > @@ -826,5 +826,19 @@ > > > > <h3>Valid volume format types</h3> > > <p>The valid volume types are the same as for the directory > > pool.</p> > > + > > + <h2>Storage Pool Types implementation status</h2> > > + > > + <p> > > + The storage backends have different level of support of the > > various pool and volume actions. > > + Here is a matrix of the current support for each of them. > > + </p> > > + > > + <p> > > + <strong>Note:</strong> some functions like Start and Stop > > will not trigger an exception when > > + called on a backend that doesn't implement them. > > + </p> > > + > > + <div id="include" filename="storagebackendstatus.htmlinc"/> > > </body> > > </html> > > I feel like this belongs to hvsupport.html better. Do you have any > objection to that? On one hand hvsupport.html indeed lists all the status of each hypervisor. But on the other hand we have a page dedicated to storage... Both options don't seem stupid to me. -- Cedric -- libvir-list mailing list libvir-list@redhat.com https://www.redhat.com/mailman/listinfo/libvir-list
On 8/27/19 5:43 PM, Cedric Bosdonnat wrote: > On Tue, 2019-08-27 at 16:38 +0200, Michal Privoznik wrote: >> On 8/27/19 11:17 AM, Cedric Bosdonnat wrote: >>> Since it helps a user to know which of the storage backends support >>> what >>> operation, include an autogenerated matrix showing it in the docs. >>> --- >>> .gitignore | 1 + >>> docs/Makefile.am | 9 +++-- >>> docs/apibuild.py | 2 ++ >>> docs/storage.html.in | 14 ++++++++ >>> docs/storagebackendstatus.py | 64 >>> ++++++++++++++++++++++++++++++++++++ >>> 5 files changed, 88 insertions(+), 2 deletions(-) >>> create mode 100644 docs/storagebackendstatus.py >>> >>> diff --git a/docs/storage.html.in b/docs/storage.html.in >>> index e0e4edec1e..2e4f662222 100644 >>> --- a/docs/storage.html.in >>> +++ b/docs/storage.html.in >>> @@ -826,5 +826,19 @@ >>> >>> <h3>Valid volume format types</h3> >>> <p>The valid volume types are the same as for the directory >>> pool.</p> >>> + >>> + <h2>Storage Pool Types implementation status</h2> >>> + >>> + <p> >>> + The storage backends have different level of support of the >>> various pool and volume actions. >>> + Here is a matrix of the current support for each of them. >>> + </p> >>> + >>> + <p> >>> + <strong>Note:</strong> some functions like Start and Stop >>> will not trigger an exception when >>> + called on a backend that doesn't implement them. >>> + </p> >>> + >>> + <div id="include" filename="storagebackendstatus.htmlinc"/> >>> </body> >>> </html> >> >> I feel like this belongs to hvsupport.html better. Do you have any >> objection to that? > > On one hand hvsupport.html indeed lists all the status of each > hypervisor. But on the other hand we have a page dedicated to > storage... Both options don't seem stupid to me. I prefer the hvsupport page because that's where we list which APIs are supported by which driver and this kind of does the same. For instance, at hvsupport I find that virStorageVolWipe() is implemented by storage driver but then I'd need to swith to a different page to check what storage backends atually support vol wipe. And to satisfy readers which already opened storage.html we can put a link to hvsupport.html#virStorageDriver or even to the matrix you're adding. On the other hand, we can do the same for hvsupport.html so I'll leave that up to you. Michal -- libvir-list mailing list libvir-list@redhat.com https://www.redhat.com/mailman/listinfo/libvir-list
© 2016 - 2024 Red Hat, Inc.