Add HW requirement support matrix to docs (teemtee#3025)

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.

.gitignore

@@ -10,6 +10,7 @@ docs/plugins/prepare.rst
 docs/plugins/provision.rst
 docs/plugins/report.rst
 docs/plugins/test-checks.rst
+docs/plugins/hardware-matrix.rst
 docs/_build
 docs/spec
 docs/stories

docs/Makefile

@@ -108,6 +108,11 @@ plugins/report.rst: $(call plugins-dependencies)
 plugins/test-checks.rst: $(call plugins-checks-dependencies)
  $(call build-plugins)
 
+plugins/hardware-matrix.rst: $(SCRIPTSDIR)/generate-hardware-matrix.py \
+ $(TEMPLATESDIR)/hardware-matrix.rst.j2 \
+ $(shell find $(REPODIR)/spec/hardware -name '*.fmf')
+ $(SCRIPTSDIR)/generate-hardware-matrix.py $(TEMPLATESDIR)/hardware-matrix.rst.j2 $@
+
 spec/lint.rst: $(SCRIPTSDIR)/generate-lint-checks.py \
  $(TEMPLATESDIR)/lint-checks.rst.j2 \
  $(TMTDIR)/base.py
@@ -121,15 +126,17 @@ generate-autodocs: ## Generate autodocs from source docstrings
 
 generate-lint-checks: spec spec/lint.rst ## Generate documentation sources for lint checks
 
-generate-plugins: $(PLUGIN_TARGETS) ## Generate documentation sources for plugins
+generate-plugins: $(PLUGIN_TARGETS) generate-hardware-matrix ## Generate documentation sources for plugins
+
+generate-hardware-matrix: plugins/hardware-matrix.rst ## Generate HW requirement support matrix
 
 generate-stories: stories $(TEMPLATESDIR)/story.rst.j2 ## Generate documentation sources for stories
  $(SCRIPTSDIR)/generate-stories.py $(TEMPLATESDIR)/story.rst.j2
 
 generate-template-filters: code/template-filters.rst ## Generate documentation sources for Jinja2 template filters
 
 clean: ## Remove all generated content
- rm -rf _build $(GENERATED_DIRECTORIES) code/autodocs/*.rst code/template-filters.rst $(PLUGIN_TARGETS) $(LOGO_DST)
+ rm -rf _build $(GENERATED_DIRECTORIES) code/autodocs/*.rst code/template-filters.rst plugins/hardware-matrix.rst $(PLUGIN_TARGETS) $(LOGO_DST)
 
 ##
 ## Help!

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

@@ -155,7 +155,7 @@ def _load_theme(
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
-exclude_patterns = ['_build', '**/*.inc.rst']
+exclude_patterns = ['_build', '**/*.inc.rst', 'plugins/hardware-matrix.rst']
 
 # The reST default role (used for this markup: `text`) to use for all
 # documents.
@@ -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/plugins/provision-header.inc.rst

@@ -16,3 +16,5 @@ Following plugins fully implement hard reboot:
 * :ref:`plugins/provision/beaker`
 * :ref:`plugins/provision/container`
 * :ref:`virtual<plugins/provision/virtual.testcloud>`
+
+.. include:: hardware-matrix.rst

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(f'``{hw_requirement}`` with ``{implemented_by_method}``: {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,44 @@
+{#
+ A Jinja2 template for rendering HW requirement support matrix in tmt's own docs.
+#}
+
+.. _/plugins/provision/hardware-requirement-support-matrix:
+
+Hardware requirement support
+----------------------------
+
+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 }}{# djlint:off #}</spec/hardware/{# djlint:on H025 #}{{ 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 %}

spec/hardware/main.fmf

@@ -10,6 +10,10 @@ description: |
  requirements. For example one consistent way how to specify
  `at least 2 GB of RAM` for all supported provisioners.
 
+ The current state of support of HW requirements among plugins
+ bundled with tmt is available at
+ :ref:`/plugins/provision/hardware-requirement-support-matrix`.
+
  Introduction
  ^^^^^^^^^^^^