Renamed artifacts.

.github/workflows/Parameters.yml

@@ -100,32 +100,6 @@ jobs:
           currentAlphaVersion = "3.12"
           currentAlphaRelease = "3.12.0-alpha.1"
 
-          artifact_names = {
-            "unittesting":   f"{name}-TestReport",
-            "codecoverage":  f"{name}-Coverage",
-            "statictyping":  f"{name}-Typing",
-            "package":       f"{name}-Package",
-            "documentation": f"{name}-Documentation",
-          }
-
-          # Deprecated structure
-          params = {
-            "python_version": python_version,
-            "artifacts": {
-              "unittesting": f"{artifact_names['unittesting']}",
-              "coverage":    f"{artifact_names['codecoverage']}",
-              "typing":      f"{artifact_names['statictyping']}",
-              "package":     f"{artifact_names['package']}",
-              "doc":         f"{artifact_names['documentation']}",
-            }
-          }
-
-          print("Parameters:")
-          print(f"  python_version: {python_version}")
-          print(f"  artifact_names ({len(artifact_names)}):")
-          for id, name in artifact_names.items():
-            print(f"    {id:>14}: {name}")
-
           if systems == "":
             print("::error title=Parameter::system_list is empty.")
           else:
@@ -238,16 +212,38 @@ jobs:
             for runtime, version in combinations if runtime not in data["sys"]
           ]
 
-          # Format jobs as list of dictionaries
-          buffer = ""
-          for job in jobs:
-            buffer += f"    {{ " + ", ".join([f"\"{key}\": \"{value}\"" for key, value in job.items()]) + f" }},\n"
+          artifact_names = {
+            "unittesting_xml":    f"{name}-TestReportSummary-XML",
+            "codecoverage_xml":   f"{name}-CodeCoverage-XML",
+            "codecoverage_html":  f"{name}-CodeCoverage-HTML",
+            "statictyping_html":  f"{name}-StaticTyping-HTML",
+            "package_all":        f"{name}-Packages",
+            "documentation_pdf":  f"{name}-Documentation-PDF",
+            "documentation_html": f"{name}-Documentation-HTML",
+          }
 
+          # Deprecated structure
+          params = {
+            "python_version": python_version,
+            "artifacts": {
+              "unittesting": f"{artifact_names['unittesting_xml']}",
+              "coverage":    f"{artifact_names['codecoverage_html']}",
+              "typing":      f"{artifact_names['statictyping_html']}",
+              "package":     f"{artifact_names['package_all']}",
+              "doc":         f"{artifact_names['documentation_html']}",
+            }
+          }
+
+          print("Parameters:")
+          print(f"  python_version: {python_version}")
+          print(f"  artifact_names ({len(artifact_names)}):")
+          for id, name in artifact_names.items():
+            print(f"    {id:>14}: {name}")
+
+          buffer = "".join([f"  {{ " + ", ".join([f"\"{key}\": \"{value}\"" for key, value in job.items()]) + f" }},\n" for job in jobs])
           print(dedent(f"""\
             Python jobs ({len(jobs)}):
-            [
-          {buffer}  ]
-          """))
+          {buffer}"""))
 
           # Write jobs to special file
           github_output = Path(getenv("GITHUB_OUTPUT"))

.github/workflows/_Checking_Parameters.yml

@@ -60,23 +60,30 @@ jobs:
       run:
         shell: python
     steps:
+      - name: Install dependencies
+        shell: bash
+        run: pip install pyTooling
       # Params_Default
       - name: Checking results from 'Params_Default'
         run: |
           from json import loads as json_loads
           from sys  import exit
 
+          from pyTooling.Common import zipdicts
+
           expectedPythonVersion = "3.11"
           expectedPythons = ["3.7", "3.8", "3.9", "3.10", "3.11"]
           expectedSystems = ["ubuntu", "windows", "macos"]
           expectedJobs =    [f"{system}:{python}" for system in expectedSystems for python in expectedPythons] + ["mingw64:3.10"]
           expectedName =    "Example"
           expectedArtifacts = {
-            "unittesting":   f"{expectedName}-TestReport",
-            "codecoverage":  f"{expectedName}-Coverage",
-            "statictyping":  f"{expectedName}-Typing",
-            "package":       f"{expectedName}-Package",
-            "documentation": f"{expectedName}-Documentation"
+            "unittesting_xml":    f"{expectedName}-TestReportSummary-XML",
+            "codecoverage_xml":   f"{expectedName}-CodeCoverage-XML",
+            "codecoverage_html":  f"{expectedName}-CodeCoverage-HTML",
+            "statictyping_html":  f"{expectedName}-StaticTyping-HTML",
+            "package_all":        f"{expectedName}-Packages",
+            "documentation_pdf":  f"{expectedName}-Documentation-PDF",
+            "documentation_html": f"{expectedName}-Documentation-HTML",
           }
 
           actualPythonVersion =            """${{ needs.Params_Default.outputs.python_version }}"""
@@ -94,9 +101,12 @@ jobs:
             errors += 1
           if len(actualArtifactNames) != len(expectedArtifacts):
             print(f"Number of 'artifact_names' does not match: {len(actualArtifactNames)} != {len(expectedArtifacts)}.")
-            for name in actualArtifactNames:
-              print(f"  {name}")
             errors += 1
+          else:
+            for key, actual, expected in zipdicts(actualArtifactNames, expectedArtifacts):
+              if actual != expected:
+                print(f"Artifact name '{key}' does not match: {actual} != {expected}.")
+                errors += 1
 
           if errors == 0:
             print(f"All checks PASSED.")
@@ -108,17 +118,21 @@ jobs:
           from json import loads as json_loads
           from sys  import exit
 
+          from pyTooling.Common import zipdicts
+
           expectedPythonVersion = "3.11"
           expectedPythons = ["3.9", "3.10", "pypy-3.8", "pypy-3.9"]
           expectedSystems = ["ubuntu", "windows", "macos"]
           expectedJobs =    [f"{system}:{python}" for system in expectedSystems for python in expectedPythons] + ["mingw64:3.10"]
           expectedName =    "Example"
           expectedArtifacts = {
-            "unittesting":   f"{expectedName}-TestReport",
-            "codecoverage":  f"{expectedName}-Coverage",
-            "statictyping":  f"{expectedName}-Typing",
-            "package":       f"{expectedName}-Package",
-            "documentation": f"{expectedName}-Documentation"
+            "unittesting_xml":    f"{expectedName}-TestReportSummary-XML",
+            "codecoverage_xml":   f"{expectedName}-CodeCoverage-XML",
+            "codecoverage_html":  f"{expectedName}-CodeCoverage-HTML",
+            "statictyping_html":  f"{expectedName}-StaticTyping-HTML",
+            "package_all":        f"{expectedName}-Packages",
+            "documentation_pdf":  f"{expectedName}-Documentation-PDF",
+            "documentation_html": f"{expectedName}-Documentation-HTML",
           }
 
           actualPythonVersion =            """${{ needs.Params_PythonVersions.outputs.python_version }}"""
@@ -136,9 +150,12 @@ jobs:
             errors += 1
           if len(actualArtifactNames) != len(expectedArtifacts):
             print(f"Number of 'artifact_names' does not match: {len(actualArtifactNames)} != {len(expectedArtifacts)}.")
-            for name in actualArtifactNames:
-              print(f"  {name}")
             errors += 1
+          else:
+            for key, actual, expected in zipdicts(actualArtifactNames, expectedArtifacts):
+              if actual != expected:
+                print(f"Artifact name '{key}' does not match: {actual} != {expected}.")
+                errors += 1
 
           if errors == 0:
             print(f"All checks PASSED.")
@@ -150,17 +167,21 @@ jobs:
           from json import loads as json_loads
           from sys  import exit
 
+          from pyTooling.Common import zipdicts
+
           expectedPythonVersion = "3.11"
           expectedPythons = ["3.7", "3.8", "3.9", "3.10", "3.11"]
           expectedSystems = ["windows"]
           expectedJobs =    [f"{system}:{python}" for system in expectedSystems for python in expectedPythons] + ["mingw32:3.10", "mingw64:3.10"]
           expectedName =    "Example"
           expectedArtifacts = {
-            "unittesting":   f"{expectedName}-TestReport",
-            "codecoverage":  f"{expectedName}-Coverage",
-            "statictyping":  f"{expectedName}-Typing",
-            "package":       f"{expectedName}-Package",
-            "documentation": f"{expectedName}-Documentation"
+            "unittesting_xml":    f"{expectedName}-TestReportSummary-XML",
+            "codecoverage_xml":   f"{expectedName}-CodeCoverage-XML",
+            "codecoverage_html":  f"{expectedName}-CodeCoverage-HTML",
+            "statictyping_html":  f"{expectedName}-StaticTyping-HTML",
+            "package_all":        f"{expectedName}-Packages",
+            "documentation_pdf":  f"{expectedName}-Documentation-PDF",
+            "documentation_html": f"{expectedName}-Documentation-HTML",
           }
 
           actualPythonVersion =            """${{ needs.Params_Systems.outputs.python_version }}"""
@@ -178,9 +199,12 @@ jobs:
             errors += 1
           if len(actualArtifactNames) != len(expectedArtifacts):
             print(f"Number of 'artifact_names' does not match: {len(actualArtifactNames)} != {len(expectedArtifacts)}.")
-            for name in actualArtifactNames:
-              print(f"  {name}")
             errors += 1
+          else:
+            for key, actual, expected in zipdicts(actualArtifactNames, expectedArtifacts):
+              if actual != expected:
+                print(f"Artifact name '{key}' does not match: {actual} != {expected}.")
+                errors += 1
 
           if errors == 0:
             print(f"All checks PASSED.")
@@ -192,17 +216,21 @@ jobs:
           from json import loads as json_loads
           from sys  import exit
 
+          from pyTooling.Common import zipdicts
+
           expectedPythonVersion = "3.11"
           expectedPythons = ["3.10"]
           expectedSystems = ["ubuntu", "windows", "macos"]
           expectedJobs =    [f"{system}:{python}" for system in expectedSystems for python in expectedPythons] + ["ubuntu:3.11", "ubuntu:3.12"]
           expectedName =    "Example"
           expectedArtifacts = {
-            "unittesting":   f"{expectedName}-TestReport",
-            "codecoverage":  f"{expectedName}-Coverage",
-            "statictyping":  f"{expectedName}-Typing",
-            "package":       f"{expectedName}-Package",
-            "documentation": f"{expectedName}-Documentation"
+            "unittesting_xml":    f"{expectedName}-TestReportSummary-XML",
+            "codecoverage_xml":   f"{expectedName}-CodeCoverage-XML",
+            "codecoverage_html":  f"{expectedName}-CodeCoverage-HTML",
+            "statictyping_html":  f"{expectedName}-StaticTyping-HTML",
+            "package_all":        f"{expectedName}-Packages",
+            "documentation_pdf":  f"{expectedName}-Documentation-PDF",
+            "documentation_html": f"{expectedName}-Documentation-HTML",
           }
 
           actualPythonVersion =            """${{ needs.Params_Include.outputs.python_version }}"""
@@ -220,9 +248,12 @@ jobs:
             errors += 1
           if len(actualArtifactNames) != len(expectedArtifacts):
             print(f"Number of 'artifact_names' does not match: {len(actualArtifactNames)} != {len(expectedArtifacts)}.")
-            for name in actualArtifactNames:
-              print(f"  {name}")
             errors += 1
+          else:
+            for key, actual, expected in zipdicts(actualArtifactNames, expectedArtifacts):
+              if actual != expected:
+                print(f"Artifact name '{key}' does not match: {actual} != {expected}.")
+                errors += 1
 
           if errors == 0:
             print(f"All checks PASSED.")
@@ -234,17 +265,21 @@ jobs:
           from json import loads as json_loads
           from sys  import exit
 
+          from pyTooling.Common import zipdicts
+
           expectedPythonVersion = "3.11"
           expectedPythons = ["3.10"]
           expectedSystems = ["ubuntu", "macos"]
           expectedJobs =    [f"{system}:{python}" for system in expectedSystems for python in expectedPythons]
           expectedName =    "Example"
           expectedArtifacts = {
-            "unittesting":   f"{expectedName}-TestReport",
-            "codecoverage":  f"{expectedName}-Coverage",
-            "statictyping":  f"{expectedName}-Typing",
-            "package":       f"{expectedName}-Package",
-            "documentation": f"{expectedName}-Documentation"
+            "unittesting_xml":    f"{expectedName}-TestReportSummary-XML",
+            "codecoverage_xml":   f"{expectedName}-CodeCoverage-XML",
+            "codecoverage_html":  f"{expectedName}-CodeCoverage-HTML",
+            "statictyping_html":  f"{expectedName}-StaticTyping-HTML",
+            "package_all":        f"{expectedName}-Packages",
+            "documentation_pdf":  f"{expectedName}-Documentation-PDF",
+            "documentation_html": f"{expectedName}-Documentation-HTML",
           }
 
           actualPythonVersion =            """${{ needs.Params_Exclude.outputs.python_version }}"""
@@ -262,9 +297,12 @@ jobs:
             errors += 1
           if len(actualArtifactNames) != len(expectedArtifacts):
             print(f"Number of 'artifact_names' does not match: {len(actualArtifactNames)} != {len(expectedArtifacts)}.")
-            for name in actualArtifactNames:
-              print(f"  {name}")
             errors += 1
+          else:
+            for key, actual, expected in zipdicts(actualArtifactNames, expectedArtifacts):
+              if actual != expected:
+                print(f"Artifact name '{key}' does not match: {actual} != {expected}.")
+                errors += 1
 
           if errors == 0:
             print(f"All checks PASSED.")
@@ -276,17 +314,21 @@ jobs:
           from json import loads as json_loads
           from sys  import exit
 
+          from pyTooling.Common import zipdicts
+
           expectedPythonVersion = "3.11"
           expectedPythons = ["3.10", "3.11"]
           expectedSystems = ["ubuntu", "windows"]
           expectedJobs =    [f"{system}:{python}" for system in expectedSystems for python in expectedPythons] + ["windows:3.8", "windows:3.9", "windows:3.12"]
           expectedName =    "Example"
           expectedArtifacts = {
-            "unittesting":   f"{expectedName}-TestReport",
-            "codecoverage":  f"{expectedName}-Coverage",
-            "statictyping":  f"{expectedName}-Typing",
-            "package":       f"{expectedName}-Package",
-            "documentation": f"{expectedName}-Documentation"
+            "unittesting_xml":    f"{expectedName}-TestReportSummary-XML",
+            "codecoverage_xml":   f"{expectedName}-CodeCoverage-XML",
+            "codecoverage_html":  f"{expectedName}-CodeCoverage-HTML",
+            "statictyping_html":  f"{expectedName}-StaticTyping-HTML",
+            "package_all":        f"{expectedName}-Packages",
+            "documentation_pdf":  f"{expectedName}-Documentation-PDF",
+            "documentation_html": f"{expectedName}-Documentation-HTML",
           }
 
           actualPythonVersion =            """${{ needs.Params_All.outputs.python_version }}"""
@@ -304,9 +346,12 @@ jobs:
             errors += 1
           if len(actualArtifactNames) != len(expectedArtifacts):
             print(f"Number of 'artifact_names' does not match: {len(actualArtifactNames)} != {len(expectedArtifacts)}.")
-            for name in actualArtifactNames:
-              print(f"  {name}")
             errors += 1
+          else:
+            for key, actual, expected in zipdicts(actualArtifactNames, expectedArtifacts):
+              if actual != expected:
+                print(f"Artifact name '{key}' does not match: {actual} != {expected}.")
+                errors += 1
 
           if errors == 0:
             print(f"All checks PASSED.")

doc/JobTemplate/index.rst

@@ -1,32 +1,97 @@
+.. _JOBTMPL:
+
 Overview
 ########
 
-**Global Templates**
+The following list categorizes all pre-defined job templates, which can be instantiated in a pipeline (GitHub Action
+Workflow). They can also serve as an example for creating or driving own job templates.
 
-* :ref:`JOBTMPL/Parameters`
+**Table of Contents:**
 
-**Unit Tests, Code Coverage, ...**
+.. hlist::
+   :columns: 2
 
-* :ref:`JOBTMPL/UnitTesting`
-* :ref:`JOBTMPL/CodeCoverage`
-* :ref:`JOBTMPL/StaticTypeChecking`
+   * **Global Templates**
 
-**Build and Packaging**
+     * :ref:`JOBTMPL/Parameters`
 
-* :ref:`JOBTMPL/Package`
+   * **Unit Tests, Code Coverage, Code Quality, ...**
 
-**Documentation**
+     * :ref:`JOBTMPL/UnitTesting`
+     * :ref:`JOBTMPL/CodeCoverage`
+     * :ref:`JOBTMPL/StaticTypeChecking`
+     * *code formatting (planned)*
+     * *coding style (planned)*
+     * *code linting (planned)*
 
-* :ref:`JOBTMPL/VerifyDocumentation`
-* :ref:`JOBTMPL/BuildTheDocs`
+   * **Build and Packaging**
 
-**Publishing**
+     * :ref:`JOBTMPL/Package`
 
-* :ref:`JOBTMPL/GitHubReleasePage`
-* :ref:`JOBTMPL/PyPI`
-* :ref:`JOBTMPL/PublishTestResults`
-* :ref:`JOBTMPL/PublishToGitHubPages`
+   * **Documentation**
 
-**Cleanups**
+     * :ref:`JOBTMPL/VerifyDocumentation`
+     * :ref:`JOBTMPL/BuildTheDocs`
 
-* :ref:`JOBTMPL/ArtifactCleanup`
+   * **Releasing, Publishing**
+
+     * :ref:`JOBTMPL/GitHubReleasePage`
+     * :ref:`JOBTMPL/PyPI`
+     * :ref:`JOBTMPL/PublishTestResults`
+     * :ref:`JOBTMPL/PublishToGitHubPages`
+
+   * **Cleanups**
+
+     * :ref:`JOBTMPL/ArtifactCleanup`
+
+
+Instantiation
+*************
+
+The job templates (GitHub Action *Reusable Workflows*) need to be stored in the same directory where normal pipelines
+(GitHub Action *Workflows*) are located: ``.github/workflows/<template>.yml``. These template files are distinguished
+from a normal pipeline by a ``on:workflow_call:`` section compared to an ``on:push`` section.
+
+**Job Template Definition:**
+
+The ``workflow_call`` allows the definition of input and output parameters.
+
+.. code-block:: yaml
+
+   on:
+     workflow_call:
+       inputs:
+         <Param1>:
+           # ...
+       outputs:
+         # ...
+
+   jobs:
+     <JobName>:
+       # ...
+
+**Job Template Instantiation:**
+
+When instantiating a template, a ``jobs:<Name>:uses`` is used to refer to a template file. Unfortunately, besides the
+GitHub SLUG (*<Organization>/<Repository>*), also the full path to the template needs to be gives, but still it can't be
+outside of ``.github/workflows`` to create a cleaner repository structure. Finally, the path contains a branch name
+postfixed by ``@<branch>`` (tags are still not supported by GitHub Actions). A ``jobs:<Name>:with:`` section can be used
+to handover input parameters to the template.
+
+.. code-block:: yaml
+
+   on:
+     push:
+     workflow_dispatch:
+
+   jobs:
+     <InstanceName>:
+       uses: <GitHubOrganization>/<Repository>/.github/workflows/<Template>.yml@v0
+       with:
+         <Param1>: <Value>
+
+
+Development
+***********
+
+.. todo:: JobTemplate:Development Needs documentation

doc/RepositoryStructure.rst

@@ -0,0 +1,50 @@
+Repository Structure
+####################
+
+pyTooling Actions assumes a certain repository structure and usage of technologies. Besides assumed directory or file
+names in default parameters to job templates, almost all can be overwritten if the target repository has a differing
+structure.
+
+* Python source code is located in a directory named after the Python package name.
+* All tests are located in a ``/tests`` directory and separated by testing approach.
+  * E.g. unit tests are located in a ``/tests/unit`` directory.
+* The package documentation is located in a ``/doc`` directory.
+  * Documentation is written with ReStructured Text (ReST) and translated using Sphinx.
+  * Documentation requirements are listed in a ``/doc/requirements.txt``.
+* Dependencies are listed in a ``/requirements.txt``.
+  * If the build process requires separate dependencies, a ``/build/requirements.txt`` is used.
+  * If the publishing/distribution process requires separate dependencies, a ``/dist/requirements.txt`` is used.
+* All Python project settings are stored in a ``pyproject.toml``.
+* The Python package is described in a ``setup.py``.
+* A repository overview is given in a ``README.md``.
+
+.. code-block::
+
+   <Repository>/
+     .github/
+       workflows/
+         Pipeline.yml
+       dependabot.yml
+     .vscode/
+       settings.json
+     build/
+       requirements.txt
+     dist/
+       requirements.txt
+     doc/
+       conf.py
+       index.rst
+       requirements.txt
+     <package>
+       __init__.py
+     tests/
+       unit/
+       requirements.txt
+     .editorconfig
+     .gitignore
+     LICENSE.md
+     pyproject.toml
+     README.md
+     requirements.txt
+     setup.py
+

doc/index.rst

@@ -38,35 +38,44 @@ This repository gathers reusable CI tooling for testing, packaging and distribut
 GitHub Action Job Templates
 ***************************
 
-**Global Templates**
+The following list categorizes all pre-defined job templates, which can be instantiated in a pipeline (GitHub Action
+Workflow):
 
-* :ref:`JOBTMPL/Parameters`
+.. hlist::
+   :columns: 2
 
-**Unit Tests, Code Coverage, ...**
+   * **Global Templates**
 
-* :ref:`JOBTMPL/UnitTesting`
-* :ref:`JOBTMPL/CodeCoverage`
-* :ref:`JOBTMPL/StaticTypeChecking`
+     * :ref:`JOBTMPL/Parameters`
 
-**Build and Packaging**
+   * **Unit Tests, Code Coverage, Code Quality, ...**
 
-* :ref:`JOBTMPL/Package`
+     * :ref:`JOBTMPL/UnitTesting`
+     * :ref:`JOBTMPL/CodeCoverage`
+     * :ref:`JOBTMPL/StaticTypeChecking`
+     * *code formatting (planned)*
+     * *coding style (planned)*
+     * *code linting (planned)*
 
-**Documentation**
+   * **Build and Packaging**
 
-* :ref:`JOBTMPL/VerifyDocumentation`
-* :ref:`JOBTMPL/BuildTheDocs`
+     * :ref:`JOBTMPL/Package`
 
-**Publishing**
+   * **Documentation**
 
-* :ref:`JOBTMPL/GitHubReleasePage`
-* :ref:`JOBTMPL/PyPI`
-* :ref:`JOBTMPL/PublishTestResults`
-* :ref:`JOBTMPL/PublishToGitHubPages`
+     * :ref:`JOBTMPL/VerifyDocumentation`
+     * :ref:`JOBTMPL/BuildTheDocs`
 
-**Cleanups**
+   * **Releasing, Publishing**
 
-* :ref:`JOBTMPL/ArtifactCleanup`
+     * :ref:`JOBTMPL/GitHubReleasePage`
+     * :ref:`JOBTMPL/PyPI`
+     * :ref:`JOBTMPL/PublishTestResults`
+     * :ref:`JOBTMPL/PublishToGitHubPages`
+
+   * **Cleanups**
+
+     * :ref:`JOBTMPL/ArtifactCleanup`
 
 
 Example Pipelines
@@ -132,6 +141,7 @@ License
    :hidden:
 
    Background
+   RepositoryStructure
    Releases
    Dependency