From 2e4f6f3e7ccc4e3d186c671375e05a3e354074bb Mon Sep 17 00:00:00 2001
From: Patrick Lehmann <Paebbels@gmail.com>
Date: Wed, 24 Sep 2025 15:18:27 +0200
Subject: [PATCH] Documented InstallPackage.

---
 doc/JobTemplate/Package/InstallPackage.rst | 93 ++++++++++++++++++++--
 1 file changed, 86 insertions(+), 7 deletions(-)

diff --git a/doc/JobTemplate/Package/InstallPackage.rst b/doc/JobTemplate/Package/InstallPackage.rst
index e63fb3e..e3c4201 100644
--- a/doc/JobTemplate/Package/InstallPackage.rst
+++ b/doc/JobTemplate/Package/InstallPackage.rst
@@ -46,9 +46,42 @@ the installation is verified. This aims for packaging and dependency mistakes in
 Instantiation
 *************
 
-.. todo::
+The following instantiation example creates a ``Install`` job derived from job template ``InstallPackage`` version
+`@r6`. It installs the Python package on various platforms using a precomputed job-matrix created by job
+``InstallParams``. This job uses the same ``Parameters`` job template as job ``UnitTestingParams``, which was used to
+define parameters for the packaging job ``Package``.
 
-   InstallPackage:: Needs instantiation instructions.
+.. code-block:: yaml
+
+   jobs:
+     UnitTestingParams:
+       uses: pyTooling/Actions/.github/workflows/Parameters.yml@r6
+       with:
+         package_name: myPackage
+
+     InstallParams:
+       uses: pyTooling/Actions/.github/workflows/Parameters.yml@r6
+       with:
+         package_name:        myPackage
+         python_version_list: ''
+
+     Package:
+       uses: pyTooling/Actions/.github/workflows/Package.yml@r6
+       needs:
+         - UnitTestingParams
+       with:
+         artifact: ${{ fromJson(needs.UnitTestingParams.outputs.artifact_names).package_all }}
+
+     Install:
+       uses: pyTooling/Actions/.github/workflows/InstallPackage.yml@r6
+       needs:
+         - UnitTestingParams
+         - InstallParams
+         - Package
+       with:
+         jobs:         ${{ needs.InstallParams.outputs.python_jobs }}
+         wheel:        ${{ fromJson(needs.UnitTestingParams.outputs.artifact_names).package_all }}
+         package_name: ${{ needs.UnitTestingParams.outputs.package_fullname }}
 
 
 .. _JOBTMPL/InstallPackage/Parameters:
@@ -58,9 +91,15 @@ Parameter Summary
 
 .. rubric:: Goto :ref:`input parameters <JOBTMPL/InstallPackage/Inputs>`
 
-.. todo::
-
-   InstallPackage:: Needs a parameter list.
++-------------------------------------------------------------------------+----------+----------+-----------------------------------------------------------------------------------------------------------------------------------+
+| Parameter Name                                                          | Required | Type     | Default                                                                                                                           |
++=========================================================================+==========+==========+===================================================================================================================================+
+| :ref:`JOBTMPL/InstallPackage/Input/jobs`                                | yes      | string   | — — — —                                                                                                                           |
++-------------------------------------------------------------------------+----------+----------+-----------------------------------------------------------------------------------------------------------------------------------+
+| :ref:`JOBTMPL/InstallPackage/Input/wheel`                               | yes      | string   | — — — —                                                                                                                           |
++-------------------------------------------------------------------------+----------+----------+-----------------------------------------------------------------------------------------------------------------------------------+
+| :ref:`JOBTMPL/InstallPackage/Input/package_name`                        | yes      | string   | — — — —                                                                                                                           |
++-------------------------------------------------------------------------+----------+----------+-----------------------------------------------------------------------------------------------------------------------------------+
 
 .. rubric:: Goto :ref:`secrets <JOBTMPL/InstallPackage/Secrets>`
 
@@ -76,9 +115,49 @@ This job template has no output parameters.
 Input Parameters
 ****************
 
-.. todo::
+.. _JOBTMPL/InstallPackage/Input/jobs:
 
-   InstallPackage:: Needs input parameter descriptions.
+jobs
+====
+
+:Type:            string
+:Required:        yes
+:Default Value:   — — — —
+:Possible Values: A JSON string with an array of dictionaries with the following key-value pairs:
+
+                  :sysicon: icon to display
+                  :system:  name of the system
+                  :runs-on: virtual machine image and base operating system
+                  :runtime: name of the runtime environment if not running natively on the VM image
+                  :shell:   name of the shell
+                  :pyicon:  icon for CPython or pypy
+                  :python:  Python version
+                  :envname: full name of the selected environment
+:Description:     A JSON encoded job matrix to run multiple Python job variations.
+
+
+.. _JOBTMPL/InstallPackage/Input/wheel:
+
+wheel
+=====
+
+:Type:            string
+:Required:        yes
+:Default Value:   — — — —
+:Possible Values: Any valid artifact name.
+:Description:     The artifact containing the packaged Python code as wheel.
+
+
+.. _JOBTMPL/InstallPackage/Input/package_name:
+
+package_name
+============
+
+:Type:            string
+:Required:        yes
+:Default Value:   — — — —
+:Possible Values: Any valid Python package, subpackage or module name.
+:Description:     The package or module containing the version information as a string in ``__version__``.
 
 
 .. _JOBTMPL/InstallPackage/Secrets: