Reworked more documentation sections.

doc/Deveopment.rst

@@ -0,0 +1,4 @@
+Development
+###########
+
+.. todo:: Development - Explain how to write new job templates.

doc/Instantiation.rst

@@ -0,0 +1,110 @@
+Instantiantion
+##############
+
+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>
+
+
+Example Pipelines
+*****************
+
+Documentation Only (Sphinx)
+===========================
+
+.. code-block:: yaml
+
+   name: Pipeline
+
+   on:
+     push:
+     workflow_dispatch:
+
+   jobs:
+     BuildTheDocs:
+       uses: pyTooling/Actions/.github/workflows/BuildTheDocs.yml@r0
+       with:
+         artifact: Documentation
+
+     PublishToGitHubPages:
+       uses: pyTooling/Actions/.github/workflows/PublishToGitHubPages.yml@r0
+       needs:
+         - BuildTheDocs
+       with:
+         doc: Documentation
+
+     ArtifactCleanUp:
+       name: 🗑️ Artifact Cleanup
+       needs:
+         - BuildTheDocs
+         - PublishToGitHubPages
+       runs-on: ubuntu-latest
+
+       steps:
+         - name: 🗑️ Delete artifacts
+           uses: geekyeggo/delete-artifact@v2
+           with:
+             name: Documentation
+
+
+Simple Package
+==============
+
+
+Package with Unit Tests
+=======================
+
+
+Package with Code Coverage
+==========================
+
+Complex Pipeline
+================
+
+
+Further Reference Examples
+**************************
+
+Find further usage cases in the following list of projects:
+
+- `edaa-org/pyEDAA.ProjectModel <https://github.com/edaa-org/pyEDAA.ProjectModel/tree/main/.github/workflows>`__
+- `edaa-org/pySVModel <https://github.com/edaa-org/pySVModel/tree/main/.github/workflows>`__
+- `VHDL/pyVHDLModel <https://github.com/VHDL/pyVHDLModel/tree/main/.github/workflows>`__

doc/JobTemplate/Parameters.rst

@@ -368,7 +368,7 @@ The supported artifacts are:
        needs:
          - Params
        with:
-         artifact: ${{ fromJson(needs.UnitTestingParams.outputs.artifact_names).codecoverage_html }}
+         artifact: ${{ fromJson(needs.Params.outputs.artifact_names).codecoverage_html }}
 
 
 Params

doc/JobTemplate/index.rst

@@ -48,30 +48,6 @@ Workflow). They can also serve as an example for creating or driving own job tem
 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
@@ -89,9 +65,3 @@ to handover input parameters to the template.
        uses: <GitHubOrganization>/<Repository>/.github/workflows/<Template>.yml@v0
        with:
          <Param1>: <Value>
-
-
-Development
-***********
-
-.. todo:: JobTemplate:Development Needs documentation

doc/Releases.rst

@@ -4,6 +4,13 @@ Releases Management
 Releases
 ********
 
+r1
+==
+
+.. note:: Upcoming next release based in `v1.x.y`.
+
+.. attention:: This release introduces breaking changes.
+
 r0
 ==
 
@@ -52,7 +59,7 @@ Each merge-commit is tagged with a semantic version.
 Tagging
 *******
 
-See context in `#5 <https://github.com/pyTooling/Actions/issues/5>`__.
+See context in :ghissue:`#5 Tagging/versioning of this repo <5>`.
 
 Tag new releases in the ``main`` branch using a semver compatible value, starting with ``v``:
 

doc/RepositoryStructure.rst

@@ -6,16 +6,28 @@ names in default parameters to job templates, almost all can be overwritten if t
 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.
+
+  * A ``<package>/__init__.py`` should be provided with global package information like: version number, author,
+    copyrights, license, maintainer, ...
+
+* All tests are located in a ``/tests`` directory and further divided into subdirectories 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.
+  * To reduce duplication of dependencies, dependency files should recursively call each other with ``-r <path>``.
+
 * All Python project settings are stored in a ``pyproject.toml``.
 * The Python package is described in a ``setup.py``.
+* Packages are build with ``build`` instead of ``setuptools``.
 * A repository overview is given in a ``README.md``.
 
 .. code-block::
@@ -47,4 +59,3 @@ structure.
      README.md
      requirements.txt
      setup.py
-

doc/index.rst

@@ -88,12 +88,6 @@ Minimal required modifications are the following:
 - Set the ``name`` input of job ``Parameters``.
 - Specify the ``commands`` input of job ``StaticTypeCheck``.
 
-Find further usage cases in the following list of projects:
-
-- `edaa-org/pyEDAA.ProjectModel <https://github.com/edaa-org/pyEDAA.ProjectModel/tree/main/.github/workflows>`__
-- `edaa-org/pySVModel <https://github.com/edaa-org/pySVModel/tree/main/.github/workflows>`__
-- `VHDL/pyVHDLModel <https://github.com/VHDL/pyVHDLModel/tree/main/.github/workflows>`__
-
 
 GitHub Actions
 **************
@@ -137,13 +131,15 @@ License
    This document was generated on |docdate|.
 
 .. toctree::
-   :caption: Overview
+   :caption: Introduction
    :hidden:
 
    Background
    RepositoryStructure
-   Releases
+   Instantiation
+   Deveopment
    Dependency
+   Releases
 
 .. raw:: latex