[libvirt] [PATCH] Generate status of the backend implementation in storage.html
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
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
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
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
participants (2)
-
Cedric Bosdonnat -
Michal Privoznik