Deduplicate the finish step documentation (#3536)

Signed-off-by: mcasquer <[email protected]>
Co-authored-by: Petr Šplíchal <[email protected]>

Author: mcasquer

docs/plugins/finish-header.inc.rst

@@ -0,0 +1,4 @@
+The :ref:`/spec/plans/finish` step plugins implement actions to be
+performed after the test execution has been completed. These can
+be useful for finishing tasks such as an additional guest cleanup
+or uploading specific logs to an external server.

spec/plans/finish.fmf

@@ -2,57 +2,19 @@ summary: Finishing tasks
 
 description:
     Additional actions to be performed after the test execution
-    has been completed.  Counterpart of the ``prepare`` step
-    useful for various cleanup actions. Use the
-    :ref:`/spec/core/order` attribute to select in which order
-    finishing tasks should happen if there are multiple configs.
-    Default order is ``50``.
+    has been completed. Counterpart of the
+    :ref:`/spec/plans/prepare` step, useful for various cleanup
+    actions. For more information about available options see the
+    :ref:`/plugins/finish` section.
 
 example: |
     finish:
-        how: shell
+      - how: shell
         script: upload-logs.sh
-
-/shell:
-    summary:
-        Perform finishing tasks using shell (bash) scripts
-    description:
-        Execute arbitrary shell commands to finish the testing.
-
-        Default shell options are applied to the script, see the
-        :ref:`/spec/tests/test` key specification for more
-        details.
-
-    example: |
-        finish:
-            how: shell
-            script:
-            - upload-logs.sh || true
-            - rm -rf /tmp/temporary-files
-    link:
-      - implemented-by: /tmt/steps/finish/shell.py
-
-/ansible:
-    summary:
-        Perform finishing tasks using ansible
-    description: |
-        One or more playbooks can be provided as a list under the
-        ``playbook`` attribute.  Each of them will be applied
-        using ``ansible-playbook`` in the given order. The path
-        must be relative to the metadata tree root.
-
-        Remote playbooks can be referenced as well as the local ones,
-        and both kinds can be used at the same time.
-
-    example: |
-        finish:
-            how: ansible
-            playbook:
-                - playbooks/common.yml
-                - playbooks/os/rhel7.yml
-                - https://foo.bar/rhel7-final-touches.yml
-    link:
-      - implemented-by: /tmt/steps/finish/ansible.py
+      - how: ansible
+        playbook: playbooks/cleanup.yaml
+link:
+    - implemented-by: /tmt/steps/finish
 
 /where:
     summary: Perform finishing tasks on selected guests

tmt/steps/finish/ansible.py

@@ -9,7 +9,14 @@ class FinishAnsible(
     tmt.steps.finish.FinishPlugin[tmt.steps.finish.FinishStepData], PrepareAnsible
 ):
     """
-    Perform finishing tasks using ansible
+    Perform finishing tasks using ansible.
+
+    One or more playbooks can be provided as a list under the ``playbook``
+    attribute.  Each of them will be applied using ``ansible-playbook`` in
+    the given order. The path must be relative to the metadata tree root.
+
+    Remote playbooks can be referenced as well as the local ones,
+    and both kinds can be used at the same time.
 
     .. warning::
 
@@ -39,13 +46,14 @@ class FinishAnsible(
         finish:
             how: ansible
             playbook:
-              - playbook/one.yml
-              - playbook/two.yml
-              - playbook/three.yml
+              - playbooks/common.yml
+              - playbooks/os/rhel9.yml
+              - https://foo.bar/rhel9-final-touches.yml
 
-    The playbook path should be relative to the metadata tree root.
-    Use 'order' attribute to select in which order finishing tasks
-    should happen if there are multiple configs. Default order is '50'.
+    The playbook path should be relative to the metadata tree root. Use
+    the :ref:`/spec/core/order` attribute to select in which order
+    finishing tasks should happen if there are multiple configs. Default
+    order is ``50``.
     """
 
     # We are reusing "prepare" step for "finish",

tmt/steps/finish/shell.py

@@ -41,7 +41,12 @@ def to_spec(self) -> dict[str, Any]:  # type: ignore[override]
 @tmt.steps.provides_method('shell')
 class FinishShell(tmt.steps.finish.FinishPlugin[FinishShellData]):
     """
-    Perform finishing tasks using shell (bash) scripts
+    Perform finishing tasks using shell (bash) scripts.
+
+    Execute arbitrary shell commands to finish the testing.
+    Default shell options are applied to the script, see the
+    :ref:`/spec/tests/test` key specification for more
+    details.
 
     Example config:
 
@@ -53,8 +58,9 @@ class FinishShell(tmt.steps.finish.FinishPlugin[FinishShellData]):
               - upload-logs.sh || true
               - rm -rf /tmp/temporary-files
 
-    Use the 'order' attribute to select in which order finishing tasks
-    should happen if there are multiple configs. Default order is '50'.
+    Use the :ref:`/spec/core/order` attribute to select in which order
+    finishing tasks should happen if there are multiple configs. Default
+    order is ``50``.
     """
 
     _data_class = FinishShellData