Documented Package.

.github/workflows/Package.yml

@@ -46,7 +46,6 @@ on:
         type: string
 
 jobs:
-
   Package:
     name: 📦 Package in Source and Wheel Format
     runs-on: "ubuntu-${{ inputs.ubuntu_image_version }}"

.gitignore

@@ -25,7 +25,7 @@ coverage.xml
 
 # Sphinx
 doc/_build/
-doc/pyDummy/**/*.*
+doc/myPackage/**/*.*
 !doc/myPackage/index.rst
 
 # BuildTheDocs

doc/JobTemplate/AllInOne/CompletePipeline.rst

@@ -193,6 +193,18 @@ It can be used for simple Python packages as well as namespace packages.
    * :ref:`pyTooling/Actions/.github/workflows/CheckDocumentation.yml <JOBTMPL/CheckDocumentation>`
    * :ref:`pyTooling/Actions/.github/workflows/StaticTypeCheck.yml <JOBTMPL/StaticTypeCheck>`
    * :ref:`pyTooling/Actions/.github/workflows/Package.yml <JOBTMPL/Package>`
+   
+     * :gh:`actions/checkout`
+     * :gh:`actions/setup-python`
+     * :gh:`pyTooling/upload-artifact`
+
+       * :gh:`actions/upload-artifact`
+
+     * pip
+
+       * :pypi:`build`
+       * :pypi:`wheel`
+
    * :ref:`pyTooling/Actions/.github/workflows/PublishTestResults.yml <JOBTMPL/PublishTestResults>`
    * :ref:`pyTooling/Actions/.github/workflows/PublishCoverageResults.yml <JOBTMPL/PublishCoverageResults>`
    * :ref:`pyTooling/Actions/.github/workflows/SphinxDocumentation.yml <JOBTMPL/SphinxDocumentation>`

doc/JobTemplate/Package/Package.rst

@@ -6,23 +6,46 @@ 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:**
+.. topic:: Features
 
-1. Checkout repository
-2. Setup Python and install dependencies
+   * Package source code as wheel and source distribution.
+   * Support packaging using :pypi:`build` (recommended) or :pypi:`setuptools`.
+
+.. topic:: 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``.
+      * If parameter :ref:`JOBTMPL/Package/Input/requirements` is empty, use :pypi:`build` for packaging and execute
+        ``python -m build ...``.
+      * If parameter :ref:`JOBTMPL/Package/Input/requirements` is ``no-isolation``, use :pypi:`build` for packaging in
+        *no-isolation* mode executing ``python -m build --no-isolation ...``.
+      * If parameter :ref:`JOBTMPL/Package/Input/requirements` is non-empty, use :pypi:`setuptools` for package and
+        execute ``python setup.py ...``.
 
-**Dependencies:**
+
+.. topic:: Job Execution
+
+   .. image:: ../../_static/pyTooling-Actions-Package.png
+      :width: 500px
+
+.. topic:: Dependencies
 
    * :gh:`actions/checkout`
    * :gh:`actions/setup-python`
+   * :gh:`pyTooling/upload-artifact`
+
      * :gh:`actions/upload-artifact`
 
+   * pip
+
+     * :pypi:`build`
+     * :pypi:`wheel`
+
+
+.. _JOBTMPL/Package/Instantiation:
+
 Instantiation
 *************
 
@@ -48,51 +71,114 @@ Complex Example
        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
-**********
+.. seealso::
+
+   :ref:`JOBTMPL/PublishOnPyPI`
+
+
+.. _JOBTMPL/Package/Parameters:
+
+Parameter Summary
+*****************
+
+.. rubric:: Goto :ref:`input parameters <JOBTMPL/Package/Inputs>`
+
++---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+
+| Parameter Name                                                      | Required | Type     | Default                                                           |
++=====================================================================+==========+==========+===================================================================+
+| :ref:`JOBTMPL/Package/Input/ubuntu_image_version`                   | no       | string   | ``'24.04'``                                                       |
++---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+
+| :ref:`JOBTMPL/Package/Input/python_version`                         | no       | string   | ``'3.13'``                                                        |
++---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+
+| :ref:`JOBTMPL/Package/Input/requirements`                           | no       | string   | ``''``                                                            |
++---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+
+| :ref:`JOBTMPL/Package/Input/artifact`                               | yes      | string   | — — — —                                                           |
++---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+
+
+.. rubric:: Goto :ref:`secrets <JOBTMPL/Package/Secrets>`
+
+This job template needs no secrets.
+
+.. rubric:: Goto :ref:`output parameters <JOBTMPL/Package/Outputs>`
+
+This job template has no output parameters.
+
+
+.. _JOBTMPL/Package/Inputs:
+
+Input Parameters
+****************
+
+.. _JOBTMPL/Package/Input/ubuntu_image_version:
+
+ubuntu_image_version
+====================
+
+:Type:            string
+:Required:        no
+:Default Value:   ``'24.04'``
+:Possible Values: See `actions/runner-images - Available Images <https://github.com/actions/runner-images?tab=readme-ov-file#available-images>`__
+                  for available Ubuntu image versions.
+:Description:     Version of the Ubuntu image used to run this job.
+
+                  .. note::
+
+                     Unfortunately, GitHub Actions has only a `limited set of functions <https://docs.github.com/en/actions/reference/workflows-and-actions/expressions#functions>`__,
+                     thus, the usual Ubuntu image name like ``'ubuntu-24.04'`` can't be split into image name and image
+                     version.
+
+
+.. _JOBTMPL/Package/Input/python_version:
 
 python_version
 ==============
 
-+----------------+----------+----------+----------+
-| Parameter Name | Required | Type     | Default  |
-+================+==========+==========+==========+
-| python_version | optional | string   | 3.11     |
-+----------------+----------+----------+----------+
+:Type:            string
+:Required:        no
+:Default Value:   ``'3.13'``
+:Possible Values: Any valid Python version conforming to the pattern ``<major>.<minor>`` or ``pypy-<major>.<minor>``. |br|
+                  See `actions/python-versions - available Python versions <https://github.com/actions/python-versions>`__
+                  and `actions/setup-python - configurable Python versions <https://github.com/actions/setup-python>`__.
+:Description:     Python version used as default for other jobs requiring a single Python version. |br|
+                  In case :ref:`JOBTMPL/Parameters/Input/python_version_list` is an empty string, this version is used
+                  to populate the version list.
 
-Python version.
 
+.. _JOBTMPL/Package/Input/requirements:
 
 requirements
 ============
 
-+----------------+----------+----------+----------+
-| Parameter Name | Required | Type     | Default  |
-+================+==========+==========+==========+
-| requirements   | optional | string   | ``""``   |
-+----------------+----------+----------+----------+
+:Type:            string
+:Required:        no
+:Default Value:   ``''``
+:Possible Values: Any valid list of parameters for ``pip install``. |br|
+                  Either a requirements file can be referenced using ``'-r path/to/requirements.txt'``, or a list of
+                  packages can be specified using a space separated list like ``'build wheel'``.
+:Behavior:        If the value is an empty string, :pypi:`build` is used for packaging. |br|
+                  if the value is ``no-isolation``, :ypy:`build` is used in *no-isolation* mode for packaging. |br|
+                  otherwise, a list of requirements is assumed and :pypi:`setuptools` is used for packaging.
+:Description:     Python dependencies to be installed through *pip*.
 
-Python dependencies to be installed through pip; if empty, use pyproject.toml through build.
 
+.. _JOBTMPL/Package/Input/artifact:
 
 artifact
 ========
 
-+----------------+----------+----------+----------+
-| Parameter Name | Required | Type     | Default  |
-+================+==========+==========+==========+
-| artifact       | yes      | string   | — — — —  |
-+----------------+----------+----------+----------+
+:Type:            string
+:Required:        yes
+:Possible Values: Any valid artifact name.
+:Description:     Name of the artifact containing the unittest report summary in XML format.
 
-Name of the package artifact.
 
+.. _JOBTMPL/Package/Secrets:
 
 Secrets
 *******
@@ -100,7 +186,17 @@ Secrets
 This job template needs no secrets.
 
 
-Results
+.. _JOBTMPL/Package/Outputs:
+
+Outputs
 *******
 
 This job template has no output parameters.
+
+
+.. _JOBTMPL/Package/Optimizations:
+
+Optimizations
+*************
+
+This template offers no optimizations (reduced job runtime).

doc/index.rst

@@ -205,7 +205,7 @@ License
    :caption: pyDummy Example
    :hidden:
 
-   pyDummy/pyDummy
+   myPackage/myPackage
    unittests/index
    coverage/index
    CodeCoverage