Generate plugin documentation from their sources

.gitignore

@@ -2,6 +2,13 @@
 
 /tmp/
 docs/code/autodocs/*.rst
+docs/plugins/discover.rst
+docs/plugins/execute.rst
+docs/plugins/finish.rst
+docs/plugins/prepare.rst
+docs/plugins/provision.rst
+docs/plugins/report.rst
+docs/plugins/test-checks.rst
 docs/_build
 docs/spec
 docs/stories

docs/Makefile

@@ -16,7 +16,7 @@ ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
 # the i18n builder cannot share the environment and doctrees with the others
 I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
 
-.PHONY: help generate-stories generate-autodocs clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest coverage gettext
+.PHONY: help generate-plugins plugins/*.rst generate-stories generate-autodocs clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest coverage gettext
 
 clean:
 	rm -rf $(BUILDDIR) stories spec code/autodocs/*.rst
@@ -53,7 +53,9 @@ TMTDIR        = $(REPODIR)/tmt
 SCRIPTSDIR    = scripts
 TEMPLATESDIR  = templates
 
-generate: spec stories generate-lint-checks generate-test-checks generate-stories generate-autodocs  ## Refresh all generated documentation sources
+PLUGINS_TEMPLATE := $(TEMPLATESDIR)/plugins.rst.j2
+
+generate: spec stories generate-lint-checks generate-plugins generate-stories generate-autodocs  ## Refresh all generated documentation sources
 
 spec:
 	mkdir -p spec
@@ -64,15 +66,33 @@ 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/test-checks.rst: $(SCRIPTSDIR)/generate-test-checks.py $(TEMPLATESDIR)/test-checks.rst.j2 $(TMTDIR)/checks/*.py
+plugins/discover.rst: $(SCRIPTSDIR)/generate-plugins.py $(PLUGINS_TEMPLATE) $(TMTDIR)/steps/discover/*.py
+	$(SCRIPTSDIR)/generate-plugins.py discover $(PLUGINS_TEMPLATE) $@
+
+plugins/execute.rst: $(SCRIPTSDIR)/generate-plugins.py $(PLUGINS_TEMPLATE) $(TMTDIR)/steps/execute/*.py
+	$(SCRIPTSDIR)/generate-plugins.py execute $(PLUGINS_TEMPLATE) $@
+
+plugins/finish.rst: $(SCRIPTSDIR)/generate-plugins.py $(PLUGINS_TEMPLATE) $(TMTDIR)/steps/finish/*.py
+	$(SCRIPTSDIR)/generate-plugins.py finish $(PLUGINS_TEMPLATE) $@
+
+plugins/prepare.rst: $(SCRIPTSDIR)/generate-plugins.py $(PLUGINS_TEMPLATE) $(TMTDIR)/steps/prepare/*.py
+	$(SCRIPTSDIR)/generate-plugins.py prepare $(PLUGINS_TEMPLATE) $@
+
+plugins/provision.rst: $(SCRIPTSDIR)/generate-plugins.py $(PLUGINS_TEMPLATE) $(TMTDIR)/steps/provision/*.py
+	$(SCRIPTSDIR)/generate-plugins.py provision $(PLUGINS_TEMPLATE) $@
+
+plugins/report.rst: $(SCRIPTSDIR)/generate-plugins.py $(PLUGINS_TEMPLATE) $(TMTDIR)/steps/report/*.py
+	$(SCRIPTSDIR)/generate-plugins.py report $(PLUGINS_TEMPLATE) $@
+
+plugins/test-checks.rst: $(SCRIPTSDIR)/generate-test-checks.py $(TEMPLATESDIR)/test-checks.rst.j2 $(TMTDIR)/checks/*.py
 	$(SCRIPTSDIR)/generate-test-checks.py $(TEMPLATESDIR)/test-checks.rst.j2 $@
 
 generate-lint-checks: spec spec/lint.rst  ## Generate documentation sources for lint checks
 
 generate-stories: stories $(TEMPLATESDIR)/story.rst.j2  ## Generate documentation sources for stories
 	$(SCRIPTSDIR)/generate-stories.py $(TEMPLATESDIR)/story.rst.j2
 
-generate-test-checks: spec spec/test-checks.rst  ## Generate documentation sources for test checks
+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
 
 generate-autodocs:  ## Generate autodocs from source docstrings
 	cd ../ && sphinx-apidoc --force --implicit-namespaces --no-toc -o docs/code/autodocs tmt

docs/code/index.rst

@@ -5,16 +5,16 @@
 
 In order to get a quick start with the ``tmt`` source code you
 might want look through the :ref:`classes` first to learn about
-the overall structure of the code. The :ref:`plugins` can help if
-you are planning to write a new plugin. To find detailed
+the overall structure of the code. The :ref:`plugin_introduction`
+can help if you are planning to write a new plugin. To find detailed
 information about individual classes, modules and packages inspect
 the documentation generated from sources linked below.
 
 .. toctree::
     :maxdepth: 2
 
     Class Overview <classes>
-    Plugin Introduction <plugins>
+    Plugin Introduction <plugin-introduction>
     tmt <autodocs/tmt>
 
 .. toctree::

docs/code/plugins.rst → docs/code/plugin-introduction.rst

@@ -1,4 +1,4 @@
-.. _plugins:
+.. _plugin_introduction:
 
 ===========================
     Plugin Introduction

docs/index.rst

@@ -29,6 +29,7 @@ Table of Contents
     Overview <overview>
     Guide <guide>
     Specification <spec>
+    Plugins <plugins/index>
     Examples <examples>
     Stories <stories>
     Questions <questions>

docs/plugins/index.rst

@@ -0,0 +1,24 @@
+.. _plugins:
+
+Plugins
+=======
+
+Here you will find documentation for plugins shipped with tmt.
+
+.. warning::
+
+    Please, be aware that the documentation below is a work in progress. We are
+    working on fixing it, adding missing bits and generally making it better.
+    Also, it was originaly used for command line help only, therefore the
+    formatting is often suboptional.
+
+.. toctree::
+    :maxdepth: 2
+
+    Discover <discover>
+    Provision <provision>
+    Prepare <prepare>
+    Execute <execute>
+    Finish <finish>
+    Report <report>
+    Test Checks <test-checks>

docs/scripts/generate-plugins.py

@@ -0,0 +1,72 @@
+#!/usr/bin/env python3
+
+import sys
+import textwrap
+
+import tmt.log
+import tmt.plugins
+import tmt.steps.discover
+import tmt.steps.execute
+import tmt.steps.finish
+import tmt.steps.prepare
+import tmt.steps.provision
+import tmt.steps.report
+import tmt.utils
+from tmt.utils import Path, render_template_file
+
+HELP = textwrap.dedent("""
+Usage: generate-plugins.py <STEP-NAME> <TEMPLATE-PATH> <OUTPUT-PATH>
+
+Generate pages for step plugins sources.
+""").strip()
+
+
+def main() -> None:
+    if len(sys.argv) != 4:
+        print(HELP)
+
+        sys.exit(1)
+
+    step_name = sys.argv[1]
+    template_filepath = Path(sys.argv[2])
+    output_filepath = Path(sys.argv[3])
+
+    # We will need a logger...
+    logger = tmt.log.Logger.create()
+    logger.add_console_handler()
+
+    # ... explore available plugins...
+    tmt.plugins.explore(logger)
+
+    if step_name == 'discover':
+        registry = tmt.steps.discover.DiscoverPlugin._supported_methods
+
+    elif step_name == 'execute':
+        registry = tmt.steps.execute.ExecutePlugin._supported_methods
+
+    elif step_name == 'finish':
+        registry = tmt.steps.finish.FinishPlugin._supported_methods
+
+    elif step_name == 'prepare':
+        registry = tmt.steps.prepare.PreparePlugin._supported_methods
+
+    elif step_name == 'provision':
+        registry = tmt.steps.provision.ProvisionPlugin._supported_methods
+
+    elif step_name == 'report':
+        registry = tmt.steps.report.ReportPlugin._supported_methods
+
+    else:
+        raise tmt.utils.GeneralError(f"Unhandled step name '{step_name}'.")
+
+    # ... and render the template.
+    output_filepath.write_text(render_template_file(
+        template_filepath,
+        STEP=step_name,
+        REGISTRY=registry,
+        container_fields=tmt.utils.container_fields,
+        container_field=tmt.utils.container_field))
+
+
+if __name__ == '__main__':
+    main()

docs/spec.rst

@@ -27,9 +27,7 @@ Level 1: Tests
     Metadata closely related to individual :ref:`/spec/tests` such
     as the :ref:`/spec/tests/test` script, directory
     :ref:`/spec/tests/path` or maximum :ref:`/spec/tests/duration`
-    which are stored directly with the test code. See
-    :ref:`/spec/test-checks` for the list of available test
-    :ref:`checks</spec/tests/check>`.
+    which are stored directly with the test code.
 
 Level 2: Plans
     :ref:`/spec/plans` are used to group relevant tests and enable
@@ -56,5 +54,4 @@ Level 3: Stories
     spec/stories
     spec/context
     spec/hardware
-    spec/test-checks
     spec/lint

docs/templates/plugins.rst.j2

@@ -0,0 +1,62 @@
+:tocdepth: 0
+
+.. _/plugins/{{ STEP }}:
+
+{{ STEP | capitalize }} Plugins
+{{ '=' * (8 + (STEP | length)) }}
+
+{% for PLUGIN_ID in REGISTRY.iter_plugin_ids() %}
+    {% set method = REGISTRY.get_plugin(PLUGIN_ID) %}
+    {% set PLUGIN = method.class_ %}
+
+.. _plugins/{{ STEP }}/{{ PLUGIN_ID | strip }}:
+
+{{ PLUGIN_ID }}
+{{ '^' * (PLUGIN_ID | length)}}
+
+{#
+    TODO: once we start getting reviewed and polished plugins, drop the warning
+    for those that would be done and ready. Probably with some temporary list
+    to which we would add their names.
+#}
+.. warning::
+
+    Please, be aware that the documentation below is a work in progress. We are
+    working on fixing it, adding missing bits and generally making it better.
+    Also, it was originaly used for command line help only, therefore the
+    formatting is often suboptional.
+
+{% if PLUGIN.__doc__ %}
+{{ PLUGIN.__doc__ | dedent | strip }}
+{% endif %}
+
+**Configuration**
+
+{% for field in container_fields(PLUGIN._data_class) %}
+    {% if (
+        field.name not in ('how', 'name', 'where', '_OPTIONLESS_FIELDS')
+        and field.internal != true
+        and (
+            not PLUGIN._data_class._OPTIONLESS_FIELDS
+            or field.name not in PLUGIN._data_class._OPTIONLESS_FIELDS
+        )
+     ) %}
+        {% set _, option, _, metadata = container_field(PLUGIN._data_class, field.name) %}
+
+        {% if metadata.metavar %}
+{{ option }}: ``{{ metadata.metavar }}``
+        {% elif metadata.default is boolean %}
+{{ option }}: ``true|false``
+        {% else %}
+{{ option }}:
+        {% endif %}
+        {% if metadata.help %}
+{{ metadata.help | strip | indent(4, first=true) }}
+        {% endif %}
+    {% endif %}
+{% endfor %}
+
+{% if not loop.last %}
+----
+{% endif %}
+{% endfor %}

docs/templates/test-checks.rst.j2

@@ -1,6 +1,6 @@
 :tocdepth: 0
 
-.. _/spec/test-checks:
+.. _/plugins/test-checks:
 
 Tests Checks
 ============
@@ -19,7 +19,7 @@ tmt.
 {% for PLUGIN_ID in REGISTRY.iter_plugin_ids() %}
     {% set PLUGIN = REGISTRY.get_plugin(PLUGIN_ID) %}
 
-.. _spec/test-checks/{{ PLUGIN_ID | strip }}:
+.. _plugins/test-checks/{{ PLUGIN_ID | strip }}:
 
 {{ PLUGIN_ID }}
 {{ '^' * (PLUGIN_ID | length)}}
@@ -37,7 +37,7 @@ tmt.
         {% if metadata.metavar %}
 {{ option }}: ``{{ metadata.metavar }}``
         {% elif metadata.default is boolean %}
-{{ option }}: ``true | false``
+{{ option }}: ``true|false``
         {% else %}
 {{ option }}: ...
         {% endif %}

spec/tests/check.fmf

@@ -14,7 +14,7 @@ description: |
     panic detection, core dump collection or collection of system
     logs.
 
-    See :ref:`/spec/test-checks` for the list of available checks.
+    See :ref:`/plugins/test-checks` for the list of available checks.
 
 example:
   - |

tmt/checks/__init__.py

@@ -97,6 +97,7 @@ class Check(
     how: str
     enabled: bool = field(
         default=True,
+        is_flag=True,
         help='Whether the check is enabled or not.')
 
     @cached_property

tmt/steps/__init__.py

@@ -251,10 +251,14 @@ class StepData(
     # TODO: we can easily add lists of keys for various verbosity levels...
     _KEYS_SHOW_ORDER = ['name', 'how']
 
-    name: str
-    how: str
-    order: int = tmt.utils.DEFAULT_PLUGIN_ORDER
-    summary: Optional[str] = None
+    name: str = field(help='The name of the step phase.')
+    how: str = field()
+    order: int = field(
+        default=tmt.utils.DEFAULT_PLUGIN_ORDER,
+        help='Order in which the phase should be handled.')
+    summary: Optional[str] = field(
+        default=None,
+        help='Concise summary describing purpose of the phase.')
 
     def to_spec(self) -> _RawStepData:
         """ Convert to a form suitable for saving in a specification file """