Restructured chapters.

doc/JobTemplate/Package/InstallPackage.rst

@@ -0,0 +1,22 @@
+.. _JOBTMPL/InstallPackage:
+
+InstallPackage
+##############
+
+.. todo:: InstallPackage:Needs documentation.
+
+**Behavior:**
+
+.. todo:: InstallPackage:Behavior needs documentation.
+
+**Dependencies:**
+
+.. todo:: InstallPackage:Dependencies needs documentation.
+
+Instantiation
+*************
+
+Simple Example
+==============
+
+.. todo:: InstallPackage:Simple example needs documentation.

doc/JobTemplate/Package/Package.rst

@@ -0,0 +1,106 @@
+.. _JOBTMPL/Package:
+
+Package
+#######
+
+This job packages the Python source code as a source package (``*.tar.gz``) and wheel package (``*.whl``) and uploads it
+as an artifact.
+
+**Behavior:**
+
+1. Checkout repository
+2. Setup Python and install dependencies
+3. Package Python sources:
+
+   * If parameter ``requirements`` is empty, use ``build`` package and run ``python build``.
+   * If parameter ``requirements`` is ``no-isolation``, use ``build`` package in *no-isolation* mode and run
+     ``python build``.
+   * If parameter ``requirements`` is non-empty, use ``setuptools`` package and run ``python setup.py``.
+
+**Dependencies:**
+
+* :gh:`actions/checkout`
+* :gh:`actions/setup-python`
+* :gh:`actions/upload-artifact`
+
+Instantiation
+*************
+
+Simple Example
+==============
+
+.. code-block:: yaml
+
+   jobs:
+     Package:
+       uses: pyTooling/Actions/.github/workflows/Package.yml@r5
+       with:
+         artifact: Package
+
+
+Complex Example
+===============
+
+.. code-block:: yaml
+
+   jobs:
+     Package:
+       uses: pyTooling/Actions/.github/workflows/Package.yml@r5
+       needs:
+         - Params
+         - Coverage
+       with:
+         python_version: ${{ needs.Params.outputs.python_version }}
+         requirements: -r build/requirements.txt
+         artifact: ${{ fromJson(needs.Params.outputs.artifact_names).package_all }}
+
+
+Parameters
+**********
+
+python_version
+==============
+
++----------------+----------+----------+----------+
+| Parameter Name | Required | Type     | Default  |
++================+==========+==========+==========+
+| python_version | optional | string   | 3.11     |
++----------------+----------+----------+----------+
+
+Python version.
+
+
+requirements
+============
+
++----------------+----------+----------+----------+
+| Parameter Name | Required | Type     | Default  |
++================+==========+==========+==========+
+| requirements   | optional | string   | ``""``   |
++----------------+----------+----------+----------+
+
+Python dependencies to be installed through pip; if empty, use pyproject.toml through build.
+
+
+artifact
+========
+
++----------------+----------+----------+----------+
+| Parameter Name | Required | Type     | Default  |
++================+==========+==========+==========+
+| artifact       | yes      | string   | — — — —  |
++----------------+----------+----------+----------+
+
+Name of the package artifact.
+
+
+Secrets
+*******
+
+This job template needs no secrets.
+
+
+Results
+*******
+
+This job template has no output parameters.

doc/JobTemplate/Package/PublishOnPyPI.rst

@@ -0,0 +1,139 @@
+.. _JOBTMPL/PublishOnPyPI:
+
+PublishOnPyPI
+#############
+
+Publish a source (``*.tar.gz``) package and/or wheel (``*.whl``) packages to `PyPI <https://pypi.org/>`__.
+
+**Behavior:**
+
+1. Download package artifact
+2. Publish source package(s) (``*.tar.gz``)
+3. Publish wheel package(s) (``*.whl``)
+4. Delete the artifact
+
+**Preconditions:**
+
+A PyPI account was created and the package name is either not occupied or the user has access rights for that package.
+
+**Requirements:**
+
+Setup a secret (e.g. ``PYPI_TOKEN``) in GitHub to handover the PyPI token to the job.
+
+**Dependencies:**
+
+* :gh:`actions/download-artifact`
+* :gh:`actions/setup-python`
+* :gh:`geekyeggo/delete-artifact`
+
+
+Instantiation
+*************
+
+Simple Example
+==============
+
+The following example demonstrates how to publish the artifact named ``Package`` to PyPI on every pipeline run triggered
+by a Git tag. A secret is forwarded from GitHub secrets to a job secret.
+
+.. code-block:: yaml
+
+   jobs:
+     # ...
+
+     PublishOnPyPI:
+       uses: pyTooling/Actions/.github/workflows/PublishOnPyPI.yml@r5
+       if: startsWith(github.ref, 'refs/tags')
+       with:
+         artifact: Package
+       secrets:
+         PYPI_TOKEN: ${{ secrets.PYPI_TOKEN }}
+
+Complex Example
+===============
+
+In this more complex example, the job depends on a parameter creation (``Params``) and packaging job (``Package``). The
+used Python version is overwritten by a parameter calculated in the ``Params`` jobs. Also the artifact name is managed
+by that job. Finally, the list of requirements is overwritten to load a list of requirements from ``dist/requirements.txt``.
+
+.. code-block:: yaml
+
+   jobs:
+     Params:
+       # ...
+
+     Package:
+       # ...
+
+     PublishOnPyPI:
+       uses: pyTooling/Actions/.github/workflows/PublishOnPyPI.yml@r5
+       if: startsWith(github.ref, 'refs/tags')
+       needs:
+         - Params
+         - Package
+       with:
+         python_version: ${{ needs.Params.outputs.python_version }}
+         requirements: -r dist/requirements.txt
+         artifact: ${{ fromJson(needs.Params.outputs.artifact_names).package_all }}
+       secrets:
+         PYPI_TOKEN: ${{ secrets.PYPI_TOKEN }}
+
+
+Parameters
+**********
+
+python_version
+==============
+
++----------------+----------+----------+----------+
+| Parameter Name | Required | Type     | Default  |
++================+==========+==========+==========+
+| python_version | optional | string   | ``3.11`` |
++----------------+----------+----------+----------+
+
+Python version used for uploading the package contents via `twine` to PyPI.
+
+
+requirements
+============
+
++----------------+----------+----------+-----------------+
+| Parameter Name | Required | Type     | Default         |
++================+==========+==========+=================+
+| requirements   | optional | string   | ``wheel twine`` |
++----------------+----------+----------+-----------------+
+
+List of requirements to be installed for uploading the package contents to PyPI.
+
+
+artifact
+========
+
++----------------+----------+----------+--------------+
+| Parameter Name | Required | Type     | Default      |
++================+==========+==========+==============+
+| artifact       | yes      | string   | — — — —      |
++----------------+----------+----------+--------------+
+
+Name of the artifact containing the package(s).
+
+
+Secrets
+*******
+
+PYPI_TOKEN
+==========
+
++----------------+----------+----------+--------------+
+| Secret Name    | Required | Type     | Default      |
++================+==========+==========+==============+
+| PYPI_TOKEN     | yes      | string   | — — — —      |
++----------------+----------+----------+--------------+
+
+The token to access the package at PyPI for uploading new data.
+
+
+Results
+*******
+
+This job template has no output parameters.

doc/JobTemplate/Package/index.rst

@@ -0,0 +1,17 @@
+.. _JOBTMPL/Packaging:
+
+Packaging
+#########
+
+The category *packaging* provides workflow templates implementing
+
+* :ref:`JOBTMPL/Package` -
+* :ref:`JOBTMPL/InstallPackage` -
+* :ref:`JOBTMPL/PublishOnPyPI` -
+
+.. toctree::
+   :hidden:
+
+   Package
+   InstallPackage
+   PublishOnPyPI