Documented Coverage Collection.

doc/JobTemplate/CoverageCollection.rst

@@ -1,11 +1,35 @@
 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.
+This jobs runs the specified unit tests with activated code coverage collection (incl. branch coverage).
+
+It uses pytest, pytest-cov and coverage.py in a single job run, thus it uses one fixed Python version (usually latest).
+It generates HTML and Cobertura reports (XML), then it uploads the HTML report as an artifact and the jUnit test results
+(XML) to `Codecov <https://about.codecov.io/>`__ and `Codacy <https://www.codacy.com/>`__.
+
+Configuration options to ``pytest`` and ``coverage.py`` should be given via sections ``[tool.pytest.ini_options]`` and
+``[tool.coverage.*]`` in a ``pyproject.toml`` file.
+
+**Behavior:**
+
+1. Checkout repository
+2. Setup Python and install dependencies
+3. Extract configuration from ``pyproject.toml`` or ``.coveragerc``.
+4. Run unit tests and collect code coverage
+5. Convert coverage data to a Cobertura XML file
+6. Convert coverage data to a HTML report
+7. Publish Cobertura file to CodeCov
+8. Publish Cobertura file to Codacy
+
+**Preconditions:**
+
+* A CodeCov account was created.
+* A Codacy account was created.
+
+**Requirements:**
+
+Setup a secret (e.g. ``codacy_token``) in GitHub to handover the Codacy project token to the job.
+
 
 Instantiation
 *************
@@ -15,29 +39,118 @@ Simple Example
 
 .. code-block:: yaml
 
-   TBD
+   jobs:
+     Coverage:
+       uses: pyTooling/Actions/.github/workflows/CoverageCollection.yml@r0
+       with:
+         artifact: Coverage
+       secrets:
+         codacy_token: ${{ secrets.CODACY_PROJECT_TOKEN }}
 
 Complex Example
 ===============
 
-
-
 .. code-block:: yaml
 
-   TBD
+   jobs:
+     Coverage:
+       uses: pyTooling/Actions/.github/workflows/CoverageCollection.yml@r0
+       needs:
+         - Params
+       with:
+         python_version: ${{ fromJson(needs.Params.outputs.params).python_version }}
+         artifact: ${{ fromJson(needs.Params.outputs.params).artifacts.Coverage }}
+       secrets:
+         codacy_token: ${{ secrets.CODACY_PROJECT_TOKEN }}
 
 Template Parameters
 *******************
 
-TBD 1
-=====
+python_version
+==============
 
-TBD
+Python version used for running unit tests.
 
-TBD 1
-=====
++----------+----------+----------+
+| Required | Type     | Default  |
++==========+==========+==========+
+| optional | string   | 3.11     |
++----------+----------+----------+
+
+
+requirements
+============
+
+Python dependencies to be installed through pip.
+
++----------+----------+-------------------------------+
+| Required | Type     | Default                       |
++==========+==========+===============================+
+| optional | string   | ``-r tests/requirements.txt`` |
++----------+----------+-------------------------------+
+
+
+tests_directory
+===============
+
+Path to the directory containing tests (test working directory).
+
++----------+----------+-----------+
+| Required | Type     | Default   |
++==========+==========+===========+
+| optional | string   | ``tests`` |
++----------+----------+-----------+
+
+
+unittest_directory
+==================
+
+Path to the directory containing unit tests (relative to test_directory).
+
++----------+----------+-----------+
+| Required | Type     | Default   |
++==========+==========+===========+
+| optional | string   | ``unit``  |
++----------+----------+-----------+
+
+
+coverage_config
+===============
+
+Path to the ``.coveragerc`` file. Use ``pyproject.toml`` by default.
+
++----------+----------+--------------------+
+| Required | Type     | Default            |
++==========+==========+====================+
+| optional | string   | ``pyproject.toml`` |
++----------+----------+--------------------+
+
+
+artifact
+========
+
+Name of the coverage artifact.
+
++----------+----------+--------------+
+| Required | Type     | Default      |
++==========+==========+==============+
+| yes      | string   | — — — —      |
++----------+----------+--------------+
+
+Secrets
+*******
+
+codacy_token
+============
+
+Token to push result to codacy.
+
++----------+----------+--------------+
+| Required | Type     | Default      |
++==========+==========+==============+
+| yes      | string   | — — — —      |
++----------+----------+--------------+
 
-TBD
 
 Template Results
 ****************

doc/JobTemplate/PublishOnPyPI.rst

@@ -77,20 +77,36 @@ python_version
 
 Python version used for uploading the package contents via `twine` to PyPI.
 
-**Default:** 3.11
++----------+----------+----------+
+| Required | Type     | Default  |
++==========+==========+==========+
+| optional | string   | 3.11     |
++----------+----------+----------+
+
 
 requirements
 ============
 
 List of requirements to be installed for uploading the package contents to PyPI.
 
-**Default:** wheel, twine
++----------+----------+--------------+
+| Required | Type     | Default      |
++==========+==========+==============+
+| optional | string   | wheel, twine |
++----------+----------+--------------+
+
 
 artifact
 ========
 
 Name of the artifact containing the package(s).
 
++----------+----------+--------------+
+| Required | Type     | Default      |
++==========+==========+==============+
+| yes      | string   | — — — —      |
++----------+----------+--------------+
+
 Secrets
 *******
 
@@ -99,6 +115,12 @@ PYPI_TOKEN
 
 The token to access the package at PyPI for uploading new data.
 
++----------+----------+--------------+
+| Required | Type     | Default      |
++==========+==========+==============+
+| yes      | string   | — — — —      |
++----------+----------+--------------+
+
 Results
 *******