Added Sphinx based documentation.

(cherry picked from commit f9f5dd5117a14ba31a3a9113a1de2c12c624dffb)

.btd.yml

@@ -0,0 +1,9 @@
+input: doc
+output: _build
+requirements: requirements.txt
+target: gh-pages
+formats: [ html ]
+images:
+  base: btdi/sphinx:pytooling
+  latex: btdi/latex
+theme: https://codeload.GitHub.com/buildthedocs/sphinx.theme/tar.gz/v1

.editorconfig

@@ -0,0 +1,30 @@
+root = true
+
+[*]
+charset = utf-8
+# end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+indent_style = tab
+indent_size = 2
+tab_width = 2
+
+
+[*.py]
+indent_style = tab
+indent_size = 2
+
+[*.{yml,yaml}]
+indent_style = space
+indent_size = 2
+
+[*.{json,ini}]
+indent_style = tab
+indent_size = 2
+
+[*.md]
+trim_trailing_whitespace = false
+
+[*.rst]
+indent_style = space
+indent_size = 3

.gitignore

@@ -0,0 +1,37 @@
+# Python cache and object files
+__pycache__/
+*.py[cod]
+
+# Coverage.py
+.coverage
+.cov
+coverage.xml
+/report/coverage
+
+# mypy
+/report/typing
+
+# pytest
+/report/unit
+
+# setuptools
+/build/**/*.*
+/dist/**/*.*
+/*.egg-info
+
+# Dependencies
+!requirements.txt
+
+# Sphinx
+doc/_build/
+doc/pyTooling/**/*.*
+!doc/pyTooling/index.rst
+
+# BuildTheDocs
+doc/_theme/**/*.*
+
+# IntelliJ project files
+/.idea/workspace.xml
+
+# Git files
+!.git*

Actions/__init__.py

@@ -0,0 +1,37 @@
+# ==================================================================================================================== #
+#             _____           _ _               ____                                                                   #
+#  _ __  _   |_   _|__   ___ | (_)_ __   __ _  / ___|___  _ __ ___  _ __ ___   ___  _ __                               #
+# | '_ \| | | || |/ _ \ / _ \| | | '_ \ / _` || |   / _ \| '_ ` _ \| '_ ` _ \ / _ \| '_ \                              #
+# | |_) | |_| || | (_) | (_) | | | | | | (_| || |__| (_) | | | | | | | | | | | (_) | | | |                             #
+# | .__/ \__, ||_|\___/ \___/|_|_|_| |_|\__, (_)____\___/|_| |_| |_|_| |_| |_|\___/|_| |_|                             #
+# |_|    |___/                          |___/                                                                          #
+# ==================================================================================================================== #
+# Authors:                                                                                                             #
+#   Patrick Lehmann                                                                                                    #
+#                                                                                                                      #
+# License:                                                                                                             #
+# ==================================================================================================================== #
+# Copyright 2017-2022 Patrick Lehmann - Bötzingen, Germany                                                             #
+#                                                                                                                      #
+# Licensed under the Apache License, Version 2.0 (the "License");                                                      #
+# you may not use this file except in compliance with the License.                                                     #
+# You may obtain a copy of the License at                                                                              #
+#                                                                                                                      #
+#   http://www.apache.org/licenses/LICENSE-2.0                                                                         #
+#                                                                                                                      #
+# Unless required by applicable law or agreed to in writing, software                                                  #
+# distributed under the License is distributed on an "AS IS" BASIS,                                                    #
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.                                             #
+# See the License for the specific language governing permissions and                                                  #
+# limitations under the License.                                                                                       #
+#                                                                                                                      #
+# SPDX-License-Identifier: Apache-2.0                                                                                  #
+# ==================================================================================================================== #
+#
+"""Placeholder"""
+__author__ =    "Patrick Lehmann"
+__email__ =     "Paebbels@gmail.com"
+__copyright__ = "2017-2022, Patrick Lehmann"
+__license__ =   "Apache License, Version 2.0"
+__version__ =   "0.4.4"
+__keywords__ =  []

doc/Action/Releaser.rst

@@ -0,0 +1,3 @@
+Releaser
+########
+

doc/Action/With-post-step.rst

@@ -0,0 +1,3 @@
+with-post-step
+##############
+

doc/Action/index.rst

@@ -0,0 +1,4 @@
+Overview
+########
+
+

doc/Dependency.rst

@@ -0,0 +1,12 @@
+Dependencies
+############
+
+* Parameters
+
+  * *None*
+
+* PublishOnPyPI
+
+  * actions/download-artifact
+  * actions/setup-python
+  * geekyeggo/delete-artifact

doc/Introduction.rst

@@ -0,0 +1,3 @@
+Introduction
+############
+

doc/JobTemplate/ArtifactCleanUp.rst

@@ -0,0 +1,39 @@
+ArtifactCleanUp
+###############
+
+Instantiation
+*************
+
+Simple Example
+==============
+
+.. code-block:: yaml
+
+   TBD
+
+Complex Example
+===============
+
+
+
+.. code-block:: yaml
+
+   TBD
+
+Template Parameters
+*******************
+
+TBD 1
+=====
+
+TBD
+
+TBD 1
+=====
+
+TBD
+
+Template Results
+****************
+
+*None*

doc/JobTemplate/BuildTheDocs.rst

@@ -0,0 +1,39 @@
+BuildTheDocs
+############
+
+Instantiation
+*************
+
+Simple Example
+==============
+
+.. code-block:: yaml
+
+   TBD
+
+Complex Example
+===============
+
+
+
+.. code-block:: yaml
+
+   TBD
+
+Template Parameters
+*******************
+
+TBD 1
+=====
+
+TBD
+
+TBD 1
+=====
+
+TBD
+
+Template Results
+****************
+
+*None*

doc/JobTemplate/CoverageCollection.rst

@@ -0,0 +1,45 @@
+CoverageCollection
+##################
+
+collect code coverage data (incl. branch coverage)
+    with `pytest`/`pytest-cov`/`coverage.py` using a single version of Python (latest). It generates HTML and Cobertura
+    (XML)reports, upload the HTML report as an artifact, and upload the test results to Codecov and Codacy. Configuration
+    options to `pytest` and `coverage.py` should be given via section `[tool.pytest.ini_options]` and `[tool.coverage.*]`
+    in a `pyproject.toml` file.
+
+Instantiation
+*************
+
+Simple Example
+==============
+
+.. code-block:: yaml
+
+   TBD
+
+Complex Example
+===============
+
+
+
+.. code-block:: yaml
+
+   TBD
+
+Template Parameters
+*******************
+
+TBD 1
+=====
+
+TBD
+
+TBD 1
+=====
+
+TBD
+
+Template Results
+****************
+
+*None*

doc/JobTemplate/Package.rst

@@ -0,0 +1,41 @@
+Package
+#######
+
+generate source and wheel packages, and upload them as an artifact.
+
+Instantiation
+*************
+
+Simple Example
+==============
+
+.. code-block:: yaml
+
+   TBD
+
+Complex Example
+===============
+
+
+
+.. code-block:: yaml
+
+   TBD
+
+Template Parameters
+*******************
+
+TBD 1
+=====
+
+TBD
+
+TBD 1
+=====
+
+TBD
+
+Template Results
+****************
+
+*None*

doc/JobTemplate/Parameters.rst

@@ -0,0 +1,139 @@
+Parameters
+##########
+
+The `Parameters` job template is a workaround for the limitations of GitHub Actions to handle global variables in
+GitHub Actions workflows (see [actions/runner#480](https://github.com/actions/runner/issues/480)).
+
+It generates output parameters with artifact names and a job matrix to be used in later running jobs.
+
+Instantiation
+*************
+
+Simple Example
+==============
+
+The following instantiation example creates a job `Params` derived from job template `Parameters` version `r0`. It only
+requires a `name` parameter to create the artifact names.
+
+.. code-block:: yaml
+
+   name: Pipeline
+
+   on:
+     push:
+     workflow_dispatch:
+
+   jobs:
+     Params:
+       uses: pyTooling/Actions/.github/workflows/Parameters.yml@r0
+       with:
+         name: pyTooling
+
+Complex Example
+===============
+
+The following instantiation example creates 3 jobs from the same template, but with differing input parameters. The
+first job `UnitTestingParams` might be used to create a job matrix of unit tests. It creates the cross of default
+systems (Windows, Ubuntu, MacOS, MinGW64) and the given list of Python versions including some mypy versions. In
+addition a list of excludes (marked as :deletetion:`deletion`) and includes (marked as :additions:`additions`) is handed
+over resulting in the following combinations:
+
++---------+-------------+-------------+-------------+--------------+-------------------------+---------+----------+------------------------------+------------------------------+
+| Version | 3.7         | 3.8         | 3.9         | 3.10         | 3.11                    | 3.12.a1 | mypy-3.7 | mypy-3.8                     | mypy-3.9                     |
++=========+=============+=============+=============+==============+=========================+=========+==========+==============================+==============================+
+| Windows | windows:3.7 | windows:3.8 | windows:3.9 | windows:3.10 |                         |         |          | :deletion:`windows:mypy-3.8` | :deletion:`windows:mypy-3.9` |
++---------+-------------+-------------+-------------+--------------+-------------------------+---------+----------+------------------------------+------------------------------+
+| Ubuntu  | ubuntu:3.7  | ubuntu:3.8  | ubuntu:3.9  | ubuntu:3.10  | :addition:`ubuntu:3.11` |         |          | ubuntu:mypy-3.8              | ubuntu:mypy-3.9              |
++---------+-------------+-------------+-------------+--------------+-------------------------+---------+----------+------------------------------+------------------------------+
+| MacOS   | macos:3.7   | macos:3.8   | macos:3.9   | macos:3.10   | :addition:`macos:3.11`  |         |          | macos:mypy-3.8               | macos:mypy-3.9               |
++---------+-------------+-------------+-------------+--------------+-------------------------+---------+----------+------------------------------+------------------------------+
+| MSYS    |             |             |             |              |                         |         |          |                              |                              |
++---------+-------------+-------------+-------------+--------------+-------------------------+---------+----------+------------------------------+------------------------------+
+| MinGW32 |             |             |             |              |                         |         |          |                              |                              |
++---------+-------------+-------------+-------------+--------------+-------------------------+---------+----------+------------------------------+------------------------------+
+| MinGW64 |             |             |             | mingw64:3.10 |                         |         |          |                              |                              |
++---------+-------------+-------------+-------------+--------------+-------------------------+---------+----------+------------------------------+------------------------------+
+| Clang32 |             |             |             |              |                         |         |          |                              |                              |
++---------+-------------+-------------+-------------+--------------+-------------------------+---------+----------+------------------------------+------------------------------+
+| Clang64 |             |             |             |              |                         |         |          |                              |                              |
++---------+-------------+-------------+-------------+--------------+-------------------------+---------+----------+------------------------------+------------------------------+
+| UCRT64  |             |             |             |              |                         |         |          |                              |                              |
++---------+-------------+-------------+-------------+--------------+-------------------------+---------+----------+------------------------------+------------------------------+
+
+
+
+.. code-block:: yaml
+
+   name: Pipeline
+
+   on:
+     push:
+     workflow_dispatch:
+
+   jobs:
+     UnitTestingParams:
+       uses: pyTooling/Actions/.github/workflows/Parameters.yml@r0
+       with:
+         name: pyTooling
+         python_version_list: "3.7 3.8 3.9 3.10 pypy-3.8 pypy-3.9"
+         include_list: "ubuntu:3.11 macos:3.11"
+         exclude_list: "windows:pypy-3.8 windows:pypy-3.9"
+
+     PerformanceTestingParams:
+       uses: pyTooling/Actions/.github/workflows/Parameters.yml@r0
+       with:
+         name: pyTooling
+         python_version_list: "3.10 3.11"
+         system_list: "ubuntu windows macos"
+
+     PlatformTestingParams:
+       uses: pyTooling/Actions/.github/workflows/Parameters.yml@dev
+       with:
+         name: pyTooling
+         python_version_list: "3.10"
+         system_list: "ubuntu windows macos mingw32 mingw64 clang64 ucrt64"
+
+Template Parameters
+*******************
+
+Name
+======
+The name of the library or package.
+
+ It's used to create artifact names.
+
+
+python_version_list
+===================
+
+TBD
+
+
+system_list
+===========
+
+TBD
+
+
+include_list
+============
+
+TBD
+
+exclude_list
+============
+
+TBD
+
+Template Results
+****************
+
+Params
+======
+
+
+Jobs
+====
+
+
+

doc/JobTemplate/PublishOnPyPI.rst

@@ -0,0 +1,86 @@
+PublishOnPyPI
+#############
+
+Publish a source (``*.tar.gz``) and wheel (``*.whl``) packages to `PyPI <https://pypi.org/>`__.
+
+Instantiation
+*************
+
+Simple Example
+==============
+
+.. code-block:: yaml
+
+   jobs:
+     # ...
+
+     PublishOnPyPI:
+       uses: pyTooling/Actions/.github/workflows/PublishOnPyPI.yml@r0
+       if: startsWith(github.ref, 'refs/tags')
+       with:
+         artifact: Package
+       secrets:
+         PYPI_TOKEN: ${{ secrets.PYPI_TOKEN }}
+
+Complex Example
+===============
+
+.. code-block:: yaml
+
+   jobs:
+     # ...
+
+     PublishOnPyPI:
+       uses: pyTooling/Actions/.github/workflows/PublishOnPyPI.yml@r0
+       if: startsWith(github.ref, 'refs/tags')
+       needs:
+         - Params
+         - Package
+       with:
+         python_version: ${{ fromJson(needs.Params.outputs.params).python_version }}
+         requirements: -r dist/requirements.txt
+         artifact: ${{ fromJson(needs.Params.outputs.params).artifacts.Package }}
+       secrets:
+         PYPI_TOKEN: ${{ secrets.PYPI_TOKEN }}
+
+Template Parameters
+*******************
+
+python_version
+==============
+
+Python version used for uploading the package contents via `twine` to PyPI.
+
+**Default:** 3.11
+
+requirements
+============
+
+List of requirements to be installed for uploading the package contents to PyPI.
+
+**Default:** wheel, twine
+
+artifact
+========
+
+Name of the artifact containing the package(s).
+
+Secrets
+*******
+
+PYPI_TOKEN
+==========
+
+The token to access the package at PyPI for uploading new data.
+
+Template Results
+****************
+
+*None*
+
+Dependencies
+************
+
+* actions/download-artifact
+* actions/setup-python
+* geekyeggo/delete-artifact

doc/JobTemplate/PublishTestResults.rst

@@ -0,0 +1,39 @@
+PublishTestResults
+##################
+
+Instantiation
+*************
+
+Simple Example
+==============
+
+.. code-block:: yaml
+
+   TBD
+
+Complex Example
+===============
+
+
+
+.. code-block:: yaml
+
+   TBD
+
+Template Parameters
+*******************
+
+TBD 1
+=====
+
+TBD
+
+TBD 1
+=====
+
+TBD
+
+Template Results
+****************
+
+*None*

doc/JobTemplate/PublishToGitHubPages.rst

@@ -0,0 +1,39 @@
+PublishToGitHubPages
+####################
+
+Instantiation
+*************
+
+Simple Example
+==============
+
+.. code-block:: yaml
+
+   TBD
+
+Complex Example
+===============
+
+
+
+.. code-block:: yaml
+
+   TBD
+
+Template Parameters
+*******************
+
+TBD 1
+=====
+
+TBD
+
+TBD 1
+=====
+
+TBD
+
+Template Results
+****************
+
+*None*

doc/JobTemplate/Release.rst

@@ -0,0 +1,41 @@
+Release
+#######
+
+publish GitHub Release.
+
+Instantiation
+*************
+
+Simple Example
+==============
+
+.. code-block:: yaml
+
+   TBD
+
+Complex Example
+===============
+
+
+
+.. code-block:: yaml
+
+   TBD
+
+Template Parameters
+*******************
+
+TBD 1
+=====
+
+TBD
+
+TBD 1
+=====
+
+TBD
+
+Template Results
+****************
+
+*None*

doc/JobTemplate/StaticTypeCheck.rst

@@ -0,0 +1,65 @@
+StaticTypeCheck
+###############
+
+collect static type check result with `mypy`, and
+    optionally upload results as an HTML report.
+    Example `commands`:
+
+    1. Regular package
+
+      ```yml
+      commands: mypy --html-report htmlmypy -p ToolName
+      ```
+
+    2. Parent namespace package
+
+      ```yml
+      commands: |
+        touch Parent/__init__.py
+        mypy --html-report htmlmypy -p ToolName
+      ```
+
+    3. Child namespace package
+
+      ```yml
+      commands: |
+        cd Parent
+        mypy --html-report ../htmlmypy -p ToolName
+      ```
+
+Instantiation
+*************
+
+Simple Example
+==============
+
+.. code-block:: yaml
+
+   TBD
+
+Complex Example
+===============
+
+
+
+.. code-block:: yaml
+
+   TBD
+
+Template Parameters
+*******************
+
+TBD 1
+=====
+
+TBD
+
+TBD 1
+=====
+
+TBD
+
+Template Results
+****************
+
+*None*

doc/JobTemplate/UnitTesting.rst

@@ -0,0 +1,43 @@
+UnitTesting
+###########
+
+run unit test with `pytest` using multiple versions of Python, and
+    optionally upload results as XML reports. Configuration options to `pytest` should be given via section
+   `[tool.pytest.ini_options]` in a `pyproject.toml` file.
+
+Instantiation
+*************
+
+Simple Example
+==============
+
+.. code-block:: yaml
+
+   TBD
+
+Complex Example
+===============
+
+
+
+.. code-block:: yaml
+
+   TBD
+
+Template Parameters
+*******************
+
+TBD 1
+=====
+
+TBD
+
+TBD 1
+=====
+
+TBD
+
+Template Results
+****************
+
+*None*

doc/JobTemplate/VerifyDocs.rst

@@ -0,0 +1,41 @@
+VerifyDocs
+##########
+
+extract code examples from the README and test these code snippets.
+
+Instantiation
+*************
+
+Simple Example
+==============
+
+.. code-block:: yaml
+
+   TBD
+
+Complex Example
+===============
+
+
+
+.. code-block:: yaml
+
+   TBD
+
+Template Parameters
+*******************
+
+TBD 1
+=====
+
+TBD
+
+TBD 1
+=====
+
+TBD
+
+Template Results
+****************
+
+*None*

doc/JobTemplate/index.rst

@@ -0,0 +1,4 @@
+Overview
+########
+
+

doc/License.rst

@@ -0,0 +1,136 @@
+.. Note:: This is a local copy of the `Apache License Version 2.0 <http://www.apache.org/licenses/LICENSE-2.0>`_.
+
+Apache License 2.0
+##################
+
+Version 2.0, January 2004
+
+**TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION**
+
+
+1. Definitions.
+===============
+**"License"** shall mean the terms and conditions for use, reproduction, and distribution as defined by Sections 1 through 9 of this document.
+
+**"Licensor"** shall mean the copyright owner or entity authorized by the copyright owner that is granting the License.
+
+**"Legal Entity"** shall mean the union of the acting entity and all other entities that control, are controlled by, or are under common control with that
+entity. For the purposes of this definition, **"control"** means (i) the power, direct or indirect, to cause the direction or management of such entity, whether
+by contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the outstanding shares, or (iii) beneficial ownership of such entity.
+
+**"You"** (or **"Your"**) shall mean an individual or Legal Entity exercising permissions granted by this License.
+
+**"Source"** form shall mean the preferred form for making modifications, including but not limited to software source code, documentation source, and
+configuration files.
+
+**"Object"** form shall mean any form resulting from mechanical transformation or translation of a Source form, including but not limited to compiled object
+code, generated documentation, and conversions to other media types.
+
+**"Work"** shall mean the work of authorship, whether in Source or Object form, made available under the License, as indicated by a copyright notice that is
+included in or attached to the work (an example is provided in the Appendix below).
+
+**"Derivative Works"** shall mean any work, whether in Source or Object form, that is based on (or derived from) the Work and for which the editorial revisions,
+annotations, elaborations, or other modifications represent, as a whole, an original work of authorship. For the purposes of this License, Derivative Works
+shall not include works that remain separable from, or merely link (or bind by name) to the interfaces of, the Work and Derivative Works thereof.
+
+**"Contribution"** shall mean any work of authorship, including the original version of the Work and any modifications or additions to that Work or Derivative
+Works thereof, that is intentionally submitted to Licensor for inclusion in the Work by the copyright owner or by an individual or Legal Entity authorized to
+submit on behalf of the copyright owner. For the purposes of this definition, **"submitted"** means any form of electronic, verbal, or written communication
+sent to the Licensor or its representatives, including but not limited to communication on electronic mailing lists, source code control systems, and issue
+tracking systems that are managed by, or on behalf of, the Licensor for the purpose of discussing and improving the Work, but excluding communication that is
+conspicuously marked or otherwise designated in writing by the copyright owner as **"Not a Contribution."**
+
+**"Contributor"** shall mean Licensor and any individual or Legal Entity on behalf of whom a Contribution has been received by Licensor and subsequently
+incorporated within the Work.
+
+2. Grant of Copyright License.
+==============================
+Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free,
+irrevocable copyright license to reproduce, prepare Derivative Works of, publicly display, publicly perform, sublicense, and distribute the Work and such
+Derivative Works in Source or Object form.
+
+3. Grant of Patent License.
+===========================
+Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free,
+irrevocable (except as stated in this section) patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Work, where such
+license applies only to those patent claims licensable by such Contributor that are necessarily infringed by their Contribution(s) alone or by combination of
+their Contribution(s) with the Work to which such Contribution(s) was submitted. If You institute patent litigation against any entity (including a cross-claim
+or counterclaim in a lawsuit) alleging that the Work or a Contribution incorporated within the Work constitutes direct or contributory patent infringement, then
+any patent licenses granted to You under this License for that Work shall terminate as of the date such litigation is filed.
+
+4. Redistribution.
+==================
+You may reproduce and distribute copies of the Work or Derivative Works thereof in any medium, with or without modifications, and in Source or Object form,
+provided that You meet the following conditions:
+
+* You must give any other recipients of the Work or Derivative Works a copy of this License; and
+* You must cause any modified files to carry prominent notices stating that You changed the files; and
+* You must retain, in the Source form of any Derivative Works that You distribute, all copyright, patent, trademark, and attribution notices from the Source
+  form of the Work, excluding those notices that do not pertain to any part of the Derivative Works; and
+* If the Work includes a **"NOTICE"** text file as part of its distribution, then any Derivative Works that You distribute must include a readable copy of the
+  attribution notices contained within such NOTICE file, excluding those notices that do not pertain to any part of the Derivative Works, in at least one of the
+  following places: within a NOTICE text file distributed as part of the Derivative Works; within the Source form or documentation, if provided along with the
+  Derivative Works; or, within a display generated by the Derivative Works, if and wherever such third-party notices normally appear. The contents of the NOTICE
+  file are for informational purposes only and do not modify the License. You may add Your own attribution notices within Derivative Works that You distribute,
+  alongside or as an addendum to the NOTICE text from the Work, provided that such additional attribution notices cannot be construed as modifying the License.
+
+You may add Your own copyright statement to Your modifications and may provide additional or different license terms and conditions for use, reproduction, or
+distribution of Your modifications, or for any such Derivative Works as a whole, provided Your use, reproduction, and distribution of the Work otherwise
+complies with the conditions stated in this License.
+
+5. Submission of Contributions.
+===============================
+Unless You explicitly state otherwise, any Contribution intentionally submitted for inclusion in the Work by You to the Licensor shall be under the terms and
+conditions of this License, without any additional terms or conditions. Notwithstanding the above, nothing herein shall supersede or modify the terms of any
+separate license agreement you may have executed with Licensor regarding such Contributions.
+
+6. Trademarks.
+==============
+This License does not grant permission to use the trade names, trademarks, service marks, or product names of the Licensor, except as required for reasonable
+and customary use in describing the origin of the Work and reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty.
+==========================
+Unless required by applicable law or agreed to in writing, Licensor provides the Work (and each Contributor provides its Contributions) on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT,
+MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are solely responsible for determining the appropriateness of using or redistributing the Work and
+assume any risks associated with Your exercise of permissions under this License.
+
+8. Limitation of Liability.
+===========================
+In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate
+and grossly negligent acts) or agreed to in writing, shall any Contributor be liable to You for damages, including any direct, indirect, special, incidental, or
+consequential damages of any character arising as a result of this License or out of the use or inability to use the Work (including but not limited to damages
+for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if such Contributor has been
+advised of the possibility of such damages.
+
+9. Accepting Warranty or Additional Liability.
+==============================================
+While redistributing the Work or Derivative Works thereof, You may choose to offer, and charge a fee for, acceptance of support, warranty, indemnity, or other
+liability obligations and/or rights consistent with this License. However, in accepting such obligations, You may act only on Your own behalf and on Your sole
+responsibility, not on behalf of any other Contributor, and only if You agree to indemnify, defend, and hold each Contributor harmless for any liability
+incurred by, or claims asserted against, such Contributor by reason of your accepting any such warranty or additional liability.
+
+----------------------------------------------------------------------------------------------------------------------------------------------------------------
+
+**Appendix: How to apply the Apache License to your work**
+
+To apply the Apache License to your work, attach the following boilerplate notice, with the fields enclosed by brackets "[]" replaced with your own identifying
+information. (Don't include the brackets!) The text should be enclosed in the appropriate comment syntax for the file format. We also recommend that a file or
+class name and description of purpose be included on the same "printed page" as the copyright notice for easier identification within third-party archives.
+
+.. code-block:: none
+
+  Copyright [yyyy] [name of copyright owner]
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.

doc/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

doc/TODO.rst

@@ -0,0 +1,4 @@
+TODOs
+#####
+
+.. todolist::

doc/conf.py

@@ -0,0 +1,253 @@
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+from importlib.util import find_spec
+from sys import path as sys_path
+from os.path import abspath
+from pathlib import Path
+from json import loads
+
+from pyTooling.Packaging import extractVersionInformation
+
+ROOT = Path(__file__).resolve().parent
+
+sys_path.insert(0, abspath("."))
+sys_path.insert(0, abspath(".."))
+#sys_path.insert(0, abspath("../pyTooling"))
+sys_path.insert(0, abspath("_extensions"))
+
+
+# ==============================================================================
+# Project information and versioning
+# ==============================================================================
+# The version info for the project you're documenting, acts as replacement for
+# |version| and |release|, also used in various other places throughout the
+# built documents.
+project = "Actions"
+
+packageInformationFile = Path(f"../{project}/__init__.py")
+versionInformation = extractVersionInformation(packageInformationFile)
+
+author =    versionInformation.Author
+copyright = versionInformation.Copyright
+version =   ".".join(versionInformation.Version.split(".")[:2])  # e.g. 2.3    The short X.Y version.
+release =   versionInformation.Version
+
+
+# ==============================================================================
+# Miscellaneous settings
+# ==============================================================================
+# The master toctree document.
+master_doc = "index"
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ["_templates"]
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = [
+	"_build",
+	"_theme",
+	"Thumbs.db",
+	".DS_Store"
+]
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = "manni"
+
+
+# ==============================================================================
+# Restructured Text settings
+# ==============================================================================
+prologPath = "prolog.inc"
+try:
+	with open(prologPath, "r") as prologFile:
+		rst_prolog = prologFile.read()
+except Exception as ex:
+	print(f"[ERROR:] While reading '{prologPath}'.")
+	print(ex)
+	rst_prolog = ""
+
+
+# ==============================================================================
+# Options for HTML output
+# ==============================================================================
+html_context = {}
+ctx = ROOT / "context.json"
+if ctx.is_file():
+	html_context.update(loads(ctx.open('r').read()))
+
+if (ROOT / "_theme").is_dir():
+	html_theme_path = ["."]
+	html_theme = "_theme"
+	html_theme_options = {
+		"logo_only": True,
+		"home_breadcrumbs": False,
+		"vcs_pageview_mode": 'blob',
+#		"body_max_width": None
+#		"navigation_depth": 5,
+	}
+elif find_spec("sphinx_rtd_theme") is not None:
+	html_theme = "sphinx_rtd_theme"
+	html_theme_options = {
+		"logo_only": True,
+		"vcs_pageview_mode": 'blob',
+#		"navigation_depth": 5,
+	}
+else:
+	html_theme = "alabaster"
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ["_static"]
+
+html_logo = str(Path(html_static_path[0]) / "logo.png")
+html_favicon = str(Path(html_static_path[0]) / "icon.png")
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = "ActionsDoc"
+
+# If not None, a 'Last updated on:' timestamp is inserted at every page
+# bottom, using the given strftime format.
+# The empty string is equivalent to '%b %d, %Y'.
+html_last_updated_fmt = "%d.%m.%Y"
+
+# ==============================================================================
+# Python settings
+# ==============================================================================
+modindex_common_prefix = [
+	f"{project}."
+]
+
+# ==============================================================================
+# Options for LaTeX / PDF output
+# ==============================================================================
+from textwrap import dedent
+
+latex_elements = {
+	# The paper size ('letterpaper' or 'a4paper').
+	"papersize": "a4paper",
+
+	# The font size ('10pt', '11pt' or '12pt').
+	#'pointsize': '10pt',
+
+	# Additional stuff for the LaTeX preamble.
+	"preamble": dedent(r"""
+		% ================================================================================
+		% User defined additional preamble code
+		% ================================================================================
+		% Add more Unicode characters for pdfLaTeX.
+		% - Alternatively, compile with XeLaTeX or LuaLaTeX.
+		% - https://GitHub.com/sphinx-doc/sphinx/issues/3511
+		%
+		\ifdefined\DeclareUnicodeCharacter
+			\DeclareUnicodeCharacter{2265}{$\geq$}
+			\DeclareUnicodeCharacter{21D2}{$\Rightarrow$}
+		\fi
+
+
+		% ================================================================================
+		"""),
+
+	# Latex figure (float) alignment
+	#'figure_align': 'htbp',
+}
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title,
+#  author, documentclass [howto, manual, or own class]).
+latex_documents = [
+	( master_doc,
+		"Actions.tex",
+		"The pyTooling Actions Documentation",
+		"Patrick Lehmann",
+		"manual"
+	),
+]
+
+
+# ==============================================================================
+# Extensions
+# ==============================================================================
+extensions = [
+# Standard Sphinx extensions
+	"sphinx.ext.coverage",
+	"sphinx.ext.extlinks",
+	"sphinx.ext.intersphinx",
+	"sphinx.ext.todo",
+	"sphinx.ext.graphviz",
+	"sphinx.ext.mathjax",
+	"sphinx.ext.ifconfig",
+	"sphinx.ext.viewcode",
+# SphinxContrib extensions
+	"sphinxcontrib.mermaid",
+# Other extensions
+	"sphinx_fontawesome",
+]
+
+
+# ==============================================================================
+# Sphinx.Ext.InterSphinx
+# ==============================================================================
+intersphinx_mapping = {
+	"python":   ("https://docs.python.org/3", None),
+}
+
+
+# ==============================================================================
+# Sphinx.Ext.AutoDoc
+# ==============================================================================
+# see: https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#configuration
+#autodoc_default_options = {
+#	"private-members": True,
+#	"special-members": True,
+#	"inherited-members": True,
+#	"exclude-members": "__weakref__"
+#}
+#autodoc_class_signature = "separated"
+autodoc_member_order = "bysource"       # alphabetical, groupwise, bysource
+autodoc_typehints = "both"
+#autoclass_content = "both"
+
+
+# ==============================================================================
+# Sphinx.Ext.ExtLinks
+# ==============================================================================
+extlinks = {
+	"gh":      ("https://GitHub.com/%s", "gh:"),
+	"ghissue": ("https://GitHub.com/pyTooling/Actions/issues/%s", "issue #"),
+	"ghpull":  ("https://GitHub.com/pyTooling/Actions/pull/%s", "pull request #"),
+	"ghsrc":   ("https://GitHub.com/pyTooling/Actions/blob/main/%s", ""),
+	"wiki":    ("https://en.wikipedia.org/wiki/%s", ""),
+}
+
+
+# ==============================================================================
+# Sphinx.Ext.Graphviz
+# ==============================================================================
+graphviz_output_format = "svg"
+
+
+# ==============================================================================
+# SphinxContrib.Mermaid
+# ==============================================================================
+mermaid_params = [
+	'--backgroundColor', 'transparent',
+]
+mermaid_verbose = True
+
+
+# ==============================================================================
+# Sphinx.Ext.ToDo
+# ==============================================================================
+# If true, `todo` and `todoList` produce output, else they produce nothing.
+todo_include_todos = True
+todo_link_only = True
+
+
+# ==============================================================================
+# Sphinx.Ext.Coverage
+# ==============================================================================
+coverage_show_missing_items = True

doc/index.rst

@@ -0,0 +1,120 @@
+.. include:: shields.inc
+
+.. raw:: latex
+
+   \part{Introduction}
+
+.. only:: html
+
+   |  |SHIELD:svg:pyTooling-github| |SHIELD:svg:pyTooling-src-license| |SHIELD:svg:pyTooling-ghp-doc| |SHIELD:svg:pyTooling-doc-license|
+   |  |SHIELD:svg:pyTooling-tag| |SHIELD:svg:pyTooling-date|
+
+.. Disabled shields: |SHIELD:svg:pyTooling-gitter|
+
+.. only:: latex
+
+   |SHIELD:png:pyTooling-github| |SHIELD:png:pyTooling-src-license| |SHIELD:png:pyTooling-ghp-doc| |SHIELD:png:pyTooling-doc-license|
+   |SHIELD:png:pyTooling-tag| |SHIELD:png:pyTooling-date|
+
+.. Disabled shields: |SHIELD:svg:pyTooling-gitter|
+
+--------------------------------------------------------------------------------
+
+pyTooling Actions Documentation
+###############################
+
+**pyTooling Actions** are reusable steps and workflows for GitHub Actions easing the creation and maintenance of
+workflows for Python projects on GitHub.
+
+GitHub Actions workflows, actions and documentation are mostly focused on JavaScript/TypeScript as the scripting
+language for writing reusable CI code.
+However, Python being equally popular and capable, usage of JS/TS might be bypassed, with some caveats.
+This repository gathers reusable CI tooling for testing, packaging and distributing Python projects and documentation.
+
+Introduction
+************
+
+
+
+Package Details
+***************
+
+
+Contributors
+************
+
+* `Patrick Lehmann <https://GitHub.com/Paebbels>`__
+* `Unai Martinez-Corral <https://GitHub.com/umarcor>`__ (Maintainer)
+* `and more... <https://GitHub.com/pyTooling/Actions/graphs/contributors>`__
+
+
+License
+*******
+
+.. only:: html
+
+   This Python package (source code) is licensed under `Apache License 2.0 <Code-License.html>`__. |br|
+   The accompanying documentation is licensed under `Creative Commons - Attribution 4.0 (CC-BY 4.0) <Doc-License.html>`__.
+
+.. only:: latex
+
+   This Python package (source code) is licensed under **Apache License 2.0**. |br|
+   The accompanying documentation is licensed under **Creative Commons - Attribution 4.0 (CC-BY 4.0)**.
+
+
+------------------------------------
+
+.. |docdate| date:: %b %d, %Y - %H:%M
+
+.. only:: html
+
+   This document was generated on |docdate|.
+
+.. toctree::
+   :caption: Overview
+   :hidden:
+
+   Introduction
+   Dependency
+
+.. raw:: latex
+
+   \part{Main Documentation}
+
+.. toctree::
+   :caption: Job Templates
+   :hidden:
+
+   JobTemplate/index
+   JobTemplate/Parameters
+   JobTemplate/CoverageCollection
+   JobTemplate/UnitTesting
+   JobTemplate/StaticTypeCheck
+   JobTemplate/PublishTestResults
+   JobTemplate/Package
+   JobTemplate/PublishOnPyPI
+   JobTemplate/VerifyDocs
+   JobTemplate/BuildTheDocs
+   JobTemplate/PublishToGitHubPages
+   JobTemplate/Release
+   JobTemplate/ArtifactCleanUp
+
+.. toctree::
+   :caption: Actions
+   :hidden:
+
+   Action/index
+   Action/Releaser
+
+.. raw:: latex
+
+   \part{Appendix}
+
+.. toctree::
+   :caption: Appendix
+   :hidden:
+
+   License
+   Doc-License
+   genindex
+   TODO

doc/make.bat

@@ -0,0 +1,36 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=.
+set BUILDDIR=_build
+set SPHINXOPTS=-v
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.http://sphinx-doc.org/
+	exit /b 1
+)
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

doc/prolog.inc

@@ -0,0 +1,59 @@
+.. # Load pre-defined aliases and graphical characters like © from docutils
+   # <file> is used to denote the special path
+   # <Python>\Lib\site-packages\docutils\parsers\rst\include
+.. include:: <isonum.txt>
+.. include:: <mmlalias.txt>
+
+.. # define a hard line break for HTML
+.. |br| raw:: html
+
+   <br />
+
+.. # define horizontal line for HTML
+.. |hr| raw:: html
+
+   <hr />
+
+.. # define additional CSS based styles and ReST roles for HTML
+.. raw:: html
+
+   <style type="text/css">
+     span.bolditalic {font-weight: bold; font-style: italic; }
+     span.underline {text-decoration: underline; }
+     span.strike {text-decoration: line-through; }
+     span.xlarge {font-size: x-large; }
+     span.colorred {color: #CC0000; }
+     span.colorgreen {color: #009933; }
+     span.colorblue {color: #0066FF; }
+     span.colorpurple {color: #9900CC; }
+   </style>
+
+.. role:: bolditalic
+   :class: bolditalic
+
+.. role:: underline
+   :class: underline
+
+.. role:: strike
+   :class: strike
+
+.. role:: xlarge
+   :class: xlarge
+
+.. role:: red
+   :class: colorred
+.. role:: green
+   :class: colorgreen
+.. role:: blue
+   :class: colorblue
+.. role:: purple
+   :class: colorpurple
+
+.. role:: deletion
+   :class: colorred strike
+.. role:: addition
+   :class: colorgreen
+
+.. role:: pycode(code)
+   :language: python
+   :class: highlight

doc/requirements.txt

@@ -0,0 +1,23 @@
+-r ../requirements.txt
+
+pyTooling>=2.5.0
+
+# Enforce latest version on ReadTheDocs
+sphinx>=5.3.0
+
+# Sphinx Extenstions
+#sphinx.ext.coverage
+#sphinxcontrib-actdiag>=0.8.5
+sphinxcontrib-mermaid>=0.7.1
+#sphinxcontrib-seqdiag>=0.8.5
+#sphinxcontrib-textstyle>=0.2.1
+#sphinxcontrib-spelling>=2.2.0
+autoapi
+sphinx_fontawesome>=0.0.6
+sphinx_autodoc_typehints>=1.19.4
+# changelog>=0.3.5
+
+# BuildTheDocs Extensions (mostly patched Sphinx extensions)
+
+# For pyTooling.Configuration.YAML documentation
+ruamel.yaml>=0.17

doc/shields.inc

@@ -0,0 +1,74 @@
+.. # Use http://b64.io/ to encode any image to base64. Then replace `/` with
+   # `%2F` and `+` with `%2B` (or use http://meyerweb.com/eric/tools/dencoder/).
+   # Beware that `?logo=data:image/png;base64,` must also be converted to
+   # percent encoding so that the URL is properly parsed.
+
+.. # Sourcecode link to GitHub
+.. |SHIELD:svg:pyTooling-github| image:: https://img.shields.io/badge/pyTooling-Actions-63bf7f.svg?longCache=true&style=flat-square&longCache=true&logo=GitHub
+   :alt: Sourcecode on GitHub
+   :height: 22
+   :target: https://GitHub.com/pyTooling/pyTooling
+.. |SHIELD:png:pyTooling-github| image:: https://raster.shields.io/badge/pyTooling-Actions-63bf7f.svg?longCache=true&style=flat-square&longCache=true&logo=GitHub
+   :alt: Sourcecode on GitHub
+   :height: 22
+   :target: https://GitHub.com/pyTooling/pyTooling
+
+.. # Sourcecode license
+.. |SHIELD:svg:pyTooling-src-license| image:: https://img.shields.io/pypi/l/pyTooling?longCache=true&style=flat-square&logo=Apache&label=code
+   :alt: Code license
+   :height: 22
+   :target: Code-License.html
+.. |SHIELD:png:pyTooling-src-license| image:: https://img.shields.io/pypi/l/pyTooling?longCache=true&style=flat-square&logo=Apache&label=code
+   :alt: Code license
+   :height: 22
+   :target: https://GitHub.com/pyTooling/Actions/blob/main/LICENSE.md
+
+.. # GitHub tag
+.. |SHIELD:svg:pyTooling-tag| image:: https://img.shields.io/github/v/tag/pyTooling/Actions?longCache=true&style=flat-square&logo=GitHub&include_prereleases
+   :alt: GitHub tag (latest SemVer incl. pre-release
+   :height: 22
+   :target: https://GitHub.com/pyTooling/Actions/tags
+.. |SHIELD:png:pyTooling-tag| image:: https://raster.shields.io/github/v/tag/pyTooling/Actions?longCache=true&style=flat-square&logo=GitHub&include_prereleases
+   :alt: GitHub tag (latest SemVer incl. pre-release
+   :height: 22
+   :target: https://GitHub.com/pyTooling/Actions/tags
+
+.. # GitHub release date
+.. |SHIELD:svg:pyTooling-date| image:: https://img.shields.io/github/release-date/pyTooling/Actions?longCache=true&style=flat-square&logo=GitHub
+   :alt: GitHub release date
+   :height: 22
+   :target: https://GitHub.com/pyTooling/Actions/releases
+.. |SHIELD:png:pyTooling-date| image:: https://raster.shields.io/github/release-date/pyTooling/Actions?longCache=true&style=flat-square&logo=GitHub
+   :alt: GitHub release date
+   :height: 22
+   :target: https://GitHub.com/pyTooling/Actions/releases
+
+.. # Documentation license
+.. |SHIELD:svg:pyTooling-doc-license| image:: https://img.shields.io/badge/doc-CC--BY%204.0-green?longCache=true&style=flat-square&logo=CreativeCommons&logoColor=fff
+   :alt: Documentation License
+   :height: 22
+   :target: License.html
+.. |SHIELD:png:pyTooling-doc-license| image:: https://raster.shields.io/badge/doc-CC--BY%204.0-green?longCache=true&style=flat-square&logo=CreativeCommons&logoColor=fff
+   :alt: Documentation License
+   :height: 22
+   :target: https://GitHub.com/pyTooling/Actions/blob/main/doc/License.rst
+
+.. # GHPages - read now
+.. |SHIELD:svg:pyTooling-ghp-doc| image:: https://img.shields.io/website?longCache=true&style=flat-square&label=pyTooling.github.io%2FpyTooling&logo=GitHub&logoColor=fff&up_color=blueviolet&up_message=Read%20now%20%E2%9E%9A&url=https%3A%2F%2FpyTooling.github.io%2FpyTooling%2Findex.html
+   :alt: Documentation - Read Now!
+   :height: 22
+   :target: https://pyTooling.github.io/pyTooling/
+.. |SHIELD:png:pyTooling-ghp-doc| image:: https://raster.shields.io/website?longCache=true&style=flat-square&label=pyTooling.github.io%2FpyTooling&logo=GitHub&logoColor=fff&up_color=blueviolet&up_message=Read%20now%20%E2%9E%9A&url=https%3A%2F%2FpyTooling.github.io%2FpyTooling%2Findex.html
+   :alt: Documentation - Read Now!
+   :height: 22
+   :target: https://pyTooling.github.io/pyTooling/
+
+.. # Gitter
+.. |SHIELD:svg:pyTooling-gitter| image:: https://img.shields.io/badge/chat-on%20gitter-4db797.svg?longCache=true&style=flat-square&logo=gitter&logoColor=e8ecef
+   :alt: Documentation License
+   :height: 22
+   :target: https://gitter.im/hdl/community
+.. |SHIELD:png:pyTooling-gitter| image:: https://raster.shields.io/badge/chat-on%20gitter-4db797.svg?longCache=true&style=flat-square&logo=gitter&logoColor=e8ecef
+   :alt: Documentation License
+   :height: 22
+   :target: https://gitter.im/hdl/community