Render environment variables and actual CLI/fmf examples of plugin keys

Improves documentation by showin examples of keys with actual values.
This should help readers of HTML docs, but eventually, when ReST
rendering gets improved, it would end up in CLI help too.

Author: happz

docs/templates/plugins.rst.j2

@@ -2,16 +2,9 @@
 
 {% macro render_field(plugin_id, plugin_data_class, field_name) %}
     {% set _, option, _, _, metadata = container_field(plugin_data_class, field_name) %}
+    {% set envvar = metadata.envvar or "TMT_PLUGIN_%s_%s_%s" | format(STEP.upper(), plugin_id.upper(), field_name.replace('-', '_').upper()) %}
 
-    {% if metadata.metavar %}
-{{ option }}: ``{{ metadata.metavar }}``
-    {% elif metadata.default is boolean %}
-{{ option }}: ``true|false``
-    {% elif metadata.choices %}
-{{ option }}: ``{{ metadata.choices }}``
-    {% else %}
-{{ option }}:
-    {% endif %}
+{{ option }}
     {% if metadata.help %}
 {{ metadata.help | trim | indent(4, first=true) }}
     {% endif %}
@@ -41,6 +34,58 @@
             {{ raise_error(error_message) }}
         {% endif %}
     {% endif %}
+
+    Environment variable: ``{{ envvar }}``
+
+    In plan metadata:
+
+    .. code-block:: yaml
+
+       # how: {{ plugin_id }}
+       # ...
+
+    {% if metadata.metavar %}
+       {{ option }}: {{ metadata.metavar }}
+
+        {% for example in metadata.help_example_values %}
+       {{ option }}: {{ example }}
+        {% endfor %}
+    {% elif metadata.default is boolean %}
+       {{ option }}: true|false
+    {% else %}
+       {{ option }}:
+    {% endif %}
+
+    On command-line:
+
+    .. code-block:: shell
+
+       # tmt run ... {{ STEP }} --how {{ plugin_id }} ...
+
+    {% if metadata.metavar %}
+       {{ plugin_id }} --{{ option }} {{ metadata.metavar | shell_quote }} ...
+       export {{ envvar }}={{ metadata.metavar | shell_quote }}
+
+        {% for example in metadata.help_example_values %}
+       {{ plugin_id }} --{{ option }} {{ example | shell_quote }}
+        {% endfor %}
+        {% for example in metadata.help_example_values %}
+       export {{ envvar }}={{ example | shell_quote }}
+        {% endfor %}
+    {% elif metadata.default is boolean %}
+       {{ plugin_id }} --{{ option }}
+       export {{ envvar }}=1|0
+    {% else %}
+       {{ plugin_id }} --{{ option }} ...
+       export {{ envvar }}=...
+
+        {% for example in metadata.help_example_values %}
+       {{ plugin_id }} --{{ option }} {{ example | shell_quote }}
+        {% endfor %}
+        {% for example in metadata.help_example_values %}
+       export {{ envvar }}={{ example | shell_quote }}
+        {% endfor %}
+    {% endif %}
 {% endmacro %}
 
 .. _/plugins/{{ STEP }}:

tmt/container/__init__.py

@@ -96,6 +96,10 @@ class FieldMetadata(Generic[T]):
     #: Help text documenting the field.
     help: Optional[str] = None
 
+    #: Specific values that should be shown in the documentation as
+    #: interesting examples of the field usage.
+    help_example_values: list[str] = simple_field(default_factory=list)
+
     #: If field accepts a value, this string would represent it in documentation.
     #: This stores the metavar provided when field was created - it may be unset.
     #: py:attr:`metavar` provides the actual metavar to be used.
@@ -666,6 +670,7 @@ def field(
     envvar: Optional[str] = None,
     deprecated: Optional['tmt.options.Deprecated'] = None,
     help: Optional[str] = None,
+    help_example_values: Optional[list[str]] = None,
     show_default: bool = False,
     internal: bool = False,
     # Input data normalization - not needed, the field is a boolean
@@ -693,6 +698,7 @@ def field(
     envvar: Optional[str] = None,
     deprecated: Optional['tmt.options.Deprecated'] = None,
     help: Optional[str] = None,
+    help_example_values: Optional[list[str]] = None,
     show_default: bool = False,
     internal: bool = False,
     # Input data normalization
@@ -719,6 +725,7 @@ def field(
     envvar: Optional[str] = None,
     deprecated: Optional['tmt.options.Deprecated'] = None,
     help: Optional[str] = None,
+    help_example_values: Optional[list[str]] = None,
     show_default: bool = False,
     internal: bool = False,
     # Input data normalization
@@ -744,6 +751,7 @@ def field(
     envvar: Optional[str] = None,
     deprecated: Optional['tmt.options.Deprecated'] = None,
     help: Optional[str] = None,
+    help_example_values: Optional[list[str]] = None,
     show_default: bool = False,
     internal: bool = False,
     # Input data normalization
@@ -770,6 +778,7 @@ def field(
     envvar: Optional[str] = None,
     deprecated: Optional['tmt.options.Deprecated'] = None,
     help: Optional[str] = None,
+    help_example_values: Optional[list[str]] = None,
     show_default: bool = False,
     internal: bool = False,
     # Input data normalization
@@ -813,6 +822,8 @@ def field(
     :param help: the help string for the command-line option. Multiline strings
         can be used, :py:func:`textwrap.dedent` is applied before passing
         ``help`` to :py:func:`click.option`.
+    :param help_example_values: Specific values that should be shown in
+        the documentation as interesting examples of the field usage.
     :param show_default: show default value
         Passed directly to :py:func:`click.option`.
     :param internal: if set, the field is treated as internal-only, and will not
@@ -854,6 +865,7 @@ def field(
             'tmt': FieldMetadata(
                 internal=internal,
                 help=textwrap.dedent(help).strip() if help else None,
+                help_example_values=help_example_values or [],
                 _metavar=metavar,
                 default=default,
                 default_factory=default_factory,

tmt/steps/prepare/ansible.py

@@ -53,6 +53,7 @@ class PrepareAnsibleData(tmt.steps.prepare.PrepareStepData):
         option='--extra-args',
         metavar='ANSIBLE-PLAYBOOK-OPTIONS',
         help='Additional CLI options for ``ansible-playbook``.',
+        help_example_values=['-vvv'],
     )
 
     # ignore[override]: method violates a liskov substitution principle,

tmt/steps/report/reportportal.py

@@ -220,6 +220,7 @@ class ReportReportPortalData(tmt.steps.report.ReportStepData):
               Size limit in bytes for traceback log upload to ReportPortal.
               The default limit is {DEFAULT_TRACEBACK_SIZE_LIMIT}.
               """,
+        help_example_values=[str(DEFAULT_TRACEBACK_SIZE_LIMIT), '1MB'],
         normalize=tmt.utils.normalize_data_amount,
         serialize=lambda limit: str(limit),
         unserialize=lambda serialized: tmt.hardware.UNITS(serialized),

tmt/utils/templates.py

@@ -6,6 +6,7 @@
 """
 
 import re
+import shlex
 import textwrap
 from re import Match
 from typing import (
@@ -310,6 +311,21 @@ def _template_filter_web_git_url(  # type: ignore[reportUnusedFunction,unused-ig
     return web_git_url(url, ref, path)
 
 
+def _template_filter_shell_quote(  # type: ignore[reportUnusedFunction,unused-ignore]
+    s: str,
+) -> str:
+    """
+    Return a shell-escaped version of the string.
+
+    .. code-block:: jinja
+
+        # "foo bar" -> "'foo bar'"
+        {{ "foo bar" | shell_quote }}
+    """
+
+    return shlex.quote(s)
+
+
 TEMPLATE_FILTERS: dict[str, Callable[..., Any]] = {
     _name.replace('_template_filter_', ''): _obj
     for _name, _obj in locals().items()