Add HW requirement support matrix to docs

Generated from HW requriement stories and their links, it should be the
most up-to-date picture of what's supported by plugins shipped with tmt.

docs/Makefile

@@ -29,6 +29,9 @@ stories:
 spec/lint.rst: $(SCRIPTSDIR)/generate-lint-checks.py $(TEMPLATESDIR)/lint-checks.rst.j2 $(TMTDIR)/base.py
 	$(SCRIPTSDIR)/generate-lint-checks.py $(TEMPLATESDIR)/lint-checks.rst.j2 $@
 
+spec/hardware-matrix.rst: spec $(TEMPLATESDIR)/hardware-matrix.rst.j2
+	$(SCRIPTSDIR)/generate-hardware-matrix.py $(TEMPLATESDIR)/hardware-matrix.rst.j2 $@
+
 code/template-filters.rst: $(SCRIPTSDIR)/generate-template-filters.py $(TEMPLATESDIR)/template-filters.rst.j2 $(TMTDIR)/utils.py
 	$(SCRIPTSDIR)/generate-template-filters.py $(TEMPLATESDIR)/template-filters.rst.j2 $@
 
@@ -57,7 +60,9 @@ generate-lint-checks: spec spec/lint.rst  ## Generate documentation sources for
 
 generate-template-filters: code/template-filters.rst  ## Generate documentation sources for Jinja2 template filters
 
-generate-stories: stories $(TEMPLATESDIR)/story.rst.j2  ## Generate documentation sources for stories
+generate-hardware-matrix: spec/hardware-matrix.rst  ## Generate HW requirement support matrix
+
+generate-stories: stories $(TEMPLATESDIR)/story.rst.j2 generate-hardware-matrix  ## Generate documentation sources for stories
 	$(SCRIPTSDIR)/generate-stories.py $(TEMPLATESDIR)/story.rst.j2
 
 generate-plugins: plugins/discover.rst plugins/execute.rst plugins/finish.rst plugins/prepare.rst plugins/provision.rst plugins/report.rst plugins/test-checks.rst  ## Generate documentation sources for plugins

docs/_static/custom.css

@@ -0,0 +1,5 @@
+@import 'css/theme.css';
+
+/* Used for HW requirement support matrix */
+.supported   { color: green; }
+.unsupported { color: red; }

docs/conf.py

@@ -229,6 +229,9 @@ def _load_theme(
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ['_static']
 
+# Include custom style.
+html_style = 'custom.css'
+
 # Add any extra paths that contain custom files (such as robots.txt or
 # .htaccess) here, relative to this directory. These files are copied
 # directly to the root of the documentation.

docs/scripts/generate-hardware-matrix.py

@@ -0,0 +1,84 @@
+#!/usr/bin/env python3
+
+import sys
+import textwrap
+
+import tmt.plugins
+import tmt.steps.provision
+from tmt.utils import Path, render_template_file
+
+HELP = textwrap.dedent("""
+Usage: generate-hardware-matrix.py <TEMPLATE-PATH> <OUTPUT-PATH>
+
+Generate page with HW requirement support matrix from stories.
+""").strip()
+
+
+def main() -> None:
+    if len(sys.argv) != 3:
+        print(HELP)
+
+        sys.exit(1)
+
+    template_filepath = Path(sys.argv[1])
+    output_filepath = Path(sys.argv[2])
+
+    # We will need a logger...
+    logger = tmt.Logger.create()
+    logger.add_console_handler()
+
+    # Explore available *export* plugins - do not import other plugins, we don't need them.
+    tmt.plugins._explore_packages(logger)
+
+    known_methods = sorted(
+        tmt.steps.provision.ProvisionPlugin._supported_methods.iter_plugin_ids())
+
+    tree = tmt.Tree(logger=logger, path=Path.cwd())
+
+    logger.info('Generating reST file for HW requirement support matrix')
+
+    matrix: dict[str, dict[str, tuple[bool, str]]] = {}
+    notes: list[str] = []
+
+    for story in tree.stories(logger=logger, names=['^/spec/hardware/.*'], whole=True):
+        hw_requirement = story.name.replace('/spec/hardware/', '')
+
+        if hw_requirement == 'arch':
+            continue
+
+        matrix[hw_requirement] = {
+            method: (False, int) for method in known_methods
+            }
+
+        if not story.link:
+            pass
+
+        for link in story.link.get(relation='implemented-by'):
+            implemented_by_method = Path(link.target).stem
+
+            if implemented_by_method == 'mrack':
+                implemented_by_method = 'beaker'
+
+            elif implemented_by_method == 'testcloud':
+                implemented_by_method = 'virtual.testcloud'
+
+            if implemented_by_method not in matrix[hw_requirement]:
+                raise Exception(f'{implemented_by_method} unknown')
+
+            if link.note:
+                notes.append(link.note)
+
+                matrix[hw_requirement][implemented_by_method] = (True, len(notes))
+
+            else:
+                matrix[hw_requirement][implemented_by_method] = (True, None)
+
+    output_filepath.write_text(render_template_file(
+        template_filepath,
+        LOGGER=logger,
+        MATRIX=matrix,
+        NOTES=notes))
+
+
+if __name__ == '__main__':
+    main()

docs/templates/hardware-matrix.rst.j2

@@ -0,0 +1,42 @@
+{#
+    A Jinja2 template for rendering HW requirement support matrix in tmt's own docs.
+#}
+
+Support matrix
+^^^^^^^^^^^^^^
+
+Below you can find a matrix documenting which hardware requirement are
+supported by plugins bundled with tmt.
+
+.. role:: supported
+
+.. role:: unsupported
+
+.. list-table::
+   :header-rows: 1
+
+   * - Requirement
+    {% for plugin in MATRIX['memory'].keys() %}
+        {% if plugin == 'virtual.testcloud' %}
+     - ``virtual``
+         {% else %}
+     - ``{{ plugin }}``
+         {% endif %}
+    {% endfor %}
+
+{% for requirement, plugins in MATRIX.items() %}
+   * - :ref:`{{ requirement }}</spec/hardware/{{ requirement }}>`
+    {% for plugin, (enabled, note_id) in plugins.items() %}
+        {% if enabled %}
+     - :supported:`yes`{% if note_id %} [{{ note_id }}]_{% endif %}
+
+        {% else %}
+     - :unsupported:`no`
+
+        {% endif %}
+    {% endfor %}
+{% endfor %}
+
+{% for note in NOTES %}
+.. [{{ loop.index}}] {{ note }}
+{% endfor %}

docs/templates/story.rst.j2

@@ -226,3 +226,8 @@
 * {{ printable_relation(link) }} ``{{ link.target }}``
 {% endif %}
 {% endfor %}
+
+{# Include HW requirement matrix when generating the main HW story #}
+{% if STORY.name == '/spec/hardware'%}
+.. include:: hardware-matrix.rst
+{% endif %}