pyTooling/Actions
1
0
Fork 0
mirror of https://github.com/pyTooling/Actions.git synced 2026-02-12 02:56:56 +08:00
Code Issues Packages Projects Releases Wiki Activity

Update documentation according to latest changes.

Browse Source
This commit is contained in:
Patrick Lehmann
2025-09-22 09:19:09 +02:00
parent 8ecefcec59
commit f684e67bca
12 changed files with 1240 additions and 726 deletions
Download Patch File Download Diff File Expand all files Collapse all files

92
doc/Glossary.rst
View File

@@ -6,53 +6,53 @@ Glossary
Bandit
Bandit is a tool designed to find common security issues in Python code.
:Source Code: `https://github.com/PyCQA/bandit/`__
:Package: `https://pypi.org/project/bandit/`__
:Documentation: `https://bandit.readthedocs.io/`__
:Source Code: `github.com/PyCQA/bandit/ <https://github.com/PyCQA/bandit/>`__
:Package: `pypi.org/project/bandit/ <https://pypi.org/project/bandit/>`__
:Documentation: `bandit.readthedocs.io/ <https://bandit.readthedocs.io/>`__
build
A simple, correct Python build frontend.
:Source Code: `https://github.com/pypa/build/`__
:Package: `https://pypi.org/project/build/`__
:Documentation: `https://build.pypa.io/`__
:Source Code: `github.com/pypa/build/ <https://github.com/pypa/build/>`__
:Package: `pypi.org/project/build/ <https://pypi.org/project/build/>`__
:Documentation: `build.pypa.io/ <https://build.pypa.io/>`__
Codacy
.. todo:: Add description of Codacy.
:Service: `Codacy.com <https://www.codacy.com/>`__
:Cloud Service: `Codacy.com <https://www.codacy.com/>`__
CodeCov
.. todo:: Add description of CodeCov.
:Service: `Codecov.io <https://about.codecov.io/>`__
:Cloud Service: `Codecov.io <https://about.codecov.io/>`__
Coverage.py
The code coverage tool for Python.
:Source Code: `https://github.com/nedbat/coveragepy/`__
:Package: `https://pypi.org/project/coverage/`__
:Documentation: `https://coverage.readthedocs.io/`__
:Source Code: `github.com/nedbat/coveragepy/ <https://github.com/nedbat/coveragepy/>`__
:Package: `pypi.org/project/coverage/ <https://pypi.org/project/coverage/>`__
:Documentation: `coverage.readthedocs.io/ <https://coverage.readthedocs.io/>`__
delete-artifact
A GitHub Action to deletes artifacts within the workflow run.
:Source Code: `https://github.com/GeekyEggo/delete-artifact/`__
:Marketplace: `https://github.com/marketplace/actions/delete-artifact/`__
:README: `https://github.com/GeekyEggo/delete-artifact/blob/main/README.md`__
:Source Code: `github.com/GeekyEggo/delete-artifact/ <https://github.com/GeekyEggo/delete-artifact/>`__
:Marketplace: `github.com/marketplace/actions/delete-artifact/ <https://github.com/marketplace/actions/delete-artifact/>`__
:README: `github.com/GeekyEggo/delete-artifact ⭢ README.md <https://github.com/GeekyEggo/delete-artifact/blob/main/README.md>`__
docstr_coverage
Docstring coverage analysis and rating for Python.
:Source Code: `https://github.com/HunterMcGushion/docstr_coverage/`__
:Package: `https://pypi.org/project/docstr_coverage/`__
:Documentation: `https://docstr-coverage.readthedocs.io/`__
:Source Code: `github.com/HunterMcGushion/docstr_coverage/ <https://github.com/HunterMcGushion/docstr_coverage/>`__
:Package: `pypi.org/project/docstr_coverage/ <https://pypi.org/project/docstr_coverage/>`__
:Documentation: `docstr-coverage.readthedocs.io/ <https://docstr-coverage.readthedocs.io/>`__
gh
GitHub’s official command line tool.
:Source Code: `https://github.com/cli/cli/`__
:Documentation: `https://cli.github.com/manual/`__
:Source Code: `github.com/cli/cli/ <https://github.com/cli/cli/>`__
:Documentation: `cli.github.com/manual/ <https://cli.github.com/manual/>`__
GitHub Pages
GitHub Pages is a static site hosting service that takes HTML, CSS, and JavaScript files straight from a repository
@@ -63,66 +63,66 @@ Glossary
interrogate
Explain yourself! Interrogate a codebase for docstring coverage.
:Source Code: `https://github.com/econchick/interrogate/`__
:Package: `https://pypi.org/project/interrogate/`__
:Documentation: `https://interrogate.readthedocs.io/`__
:Source Code: `github.com/econchick/interrogate/ <https://github.com/econchick/interrogate/>`__
:Package: `pypi.org/project/interrogate/ <https://pypi.org/project/interrogate/>`__
:Documentation: `interrogate.readthedocs.io/ <https://interrogate.readthedocs.io/>`__
MikTeX
MiKTeX is a modern TeX distribution for Windows, Linux and macOS.
:Source Code: `https://github.com/MiKTeX/miktex/`__
:Documentation: `https://miktex.org/`__
:Source Code: `github.com/MiKTeX/miktex/ <https://github.com/MiKTeX/miktex/>`__
:Documentation: `miktex.org/ <https://miktex.org/>`__
mypy
Optional static typing for Python.
:Source Code: `https://github.com/python/mypy/`__
:Package: `https://pypi.org/project/mypy/`__
:Documentation: `https://www.mypy-lang.org/`__
:Source Code: `github.com/python/mypy/ <https://github.com/python/mypy/>`__
:Package: `pypi.org/project/mypy/ <https://pypi.org/project/mypy/>`__
:Documentation: `www.mypy-lang.org/ <https://www.mypy-lang.org/>`__
pyEDAA.Reports
A collection of various (EDA tool-specific) report data formats.
:Source Code: `https://github.com/edaa-org/pyEDAA.Reports/`__
:Package: `https://pypi.org/project/pyEDAA.Reports/`__
:Documentation: `https://edaa-org.github.io/pyEDAA.Reports/`__
:Source Code: `github.com/edaa-org/pyEDAA.Reports/ <https://github.com/edaa-org/pyEDAA.Reports/>`__
:Package: `pypi.org/project/pyEDAA.Reports/ <https://pypi.org/project/pyEDAA.Reports/>`__
:Documentation: `edaa-org.github.io/pyEDAA.Reports/ <https://edaa-org.github.io/pyEDAA.Reports/>`__
pip
The Python package installer.
:Source Code: `https://github.com/pypa/pip/`__
:Package: `https://pypi.org/project/pip/`__
:Documentation: `https://pip.pypa.io/`__
:Source Code: `github.com/pypa/pip/ <https://github.com/pypa/pip/>`__
:Package: `pypi.org/project/pip/ <https://pypi.org/project/pip/>`__
:Documentation: `pip.pypa.io/ <https://pip.pypa.io/>`__
PyPI
Find, install and publish Python packages with the Python Package Index.
:URL: `PyPI.org <https://pypi.org/>`__
:Cloud Service: `PyPI.org <https://pypi.org/>`__
pytest
The pytest framework makes it easy to write small tests, yet scales to support complex functional testing.
:Source Code: `https://github.com/pytest-dev/pytest/`__
:Package: `https://pypi.org/project/pytest/`__
:Documentation: `https://pytest.org/`__
:Source Code: `github.com/pytest-dev/pytest/ <https://github.com/pytest-dev/pytest/>`__
:Package: `pypi.org/project/pytest/ <https://pypi.org/project/pytest/>`__
:Documentation: `pytest.org/ <https://pytest.org/>`__
Sphinx
The Sphinx documentation generator.
:Source Code: `https://github.com/sphinx-doc/sphinx/`__
:Package: `https://pypi.org/project/sphinx/`__
:Documentation: `https://www.sphinx-doc.org/`__
:Source Code: `github.com/sphinx-doc/sphinx/ <https://github.com/sphinx-doc/sphinx/>`__
:Package: `pypi.org/project/sphinx/ <https://pypi.org/project/sphinx/>`__
:Documentation: `www.sphinx-doc.org/ <https://www.sphinx-doc.org/>`__
Test Reporter
Displays test results from popular testing frameworks directly in GitHub.
:Source Code: `https://github.com/dorny/test-reporter/`__
:Marketplace: `https://github.com/marketplace/actions/test-reporter/`__
:README: `https://github.com/dorny/test-reporter/blob/main/README.md`__
:Source Code: `github.com/dorny/test-reporter/ <https://github.com/dorny/test-reporter/>`__
:Marketplace: `github.com/marketplace/actions/test-reporter/ <https://github.com/marketplace/actions/test-reporter/>`__
:README: `github.com/dorny/test-reporter ⭢ README.md <https://github.com/dorny/test-reporter/blob/main/README.md>`__
twine
Utilities for interacting with PyPI.
:Source Code: `https://github.com/pypa/twine/`__
:Package: `https://pypi.org/project/twine/`__
:Documentation: `https://twine.readthedocs.io/`__
:Source Code: `github.com/pypa/twine/ <https://github.com/pypa/twine/>`__
:Package: `pypi.org/project/twine/ <https://pypi.org/project/twine/>`__
:Documentation: `twine.readthedocs.io/ <https://twine.readthedocs.io/>`__

202
doc/JobTemplate/Quality/StaticTypeCheck.rst
View File

@@ -6,18 +6,18 @@
StaticTypeCheck
###############
This job template runs a static type check using `mypy <https://mypy-lang.org/>`__ and collects the results. These
results can be converted to a HTML report and uploaded as an artifact.
This job template runs a static type check using :term:`mypy` and collects the results. These results can be converted
to a HTML report and uploaded as an artifact.
.. topic:: Features
* Run static type check using mypy.
* Run static type check using :term:`mypy`.
.. topic:: Behavior
1. Checkout repository
2. Setup Python and install dependencies
3. Run type checking command(s).
3. Run type checking.
4. Upload type checking report as an artifact
.. topic:: Job Execution
@@ -61,8 +61,9 @@ directory ``report/typing``.
StaticTypeCheck:
uses: pyTooling/Actions/.github/workflows/StaticTypeCheck.yml@r5
with:
html_report: 'htmlmpyp'
artifact: 'TypeChecking'
cobertura_artifact: 'TypeChecking-Cobertura'
junit_artifact: 'TypeChecking-JUnit'
html_artifact: 'TypeChecking-HTML'
.. grid-item::
:columns: 6
@@ -74,7 +75,9 @@ directory ``report/typing``.
strict = true
pretty = true
html_report = "htmlmpyp"
html_report = "report/typing/html"
junit_xml = "report/typing/StaticTypingSummary.xml"
cobertura_xml_report = "report/typing"
Complex Example
@@ -104,8 +107,8 @@ precompute the artifact's name.
- Params
with:
python_version: ${{ needs.Params.outputs.python_version }}
report: ${{ needs.ConfigParams.outputs.typing_report_html_directory }}
artifact: ${{ fromJson(needs.Params.outputs.artifact_names).statictyping_html }}
junit_report: ${{ needs.ConfigParams.outputs.typing_report_junit }}
junit_artifact: ${{ fromJson(needs.Params.outputs.artifact_names).statictyping_junit }}
.. _JOBTMPL/StaticTypeCheck/Parameters:
@@ -115,23 +118,29 @@ Parameter Summary
.. rubric:: Goto :ref:`input parameters <JOBTMPL/StaticTypeCheck/Inputs>`
+---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+
| Parameter Name | Required | Type | Default |
+=====================================================================+==========+==========+===================================================================+
| :ref:`JOBTMPL/StaticTypeCheck/Input/ubuntu_image_version` | no | string | ``'24.04'`` |
+---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+
| :ref:`JOBTMPL/StaticTypeCheck/Input/python_version` | no | string | ``'3.13'`` |
+---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+
| :ref:`JOBTMPL/StaticTypeCheck/Input/requirements` | no | string | ``'-r tests/requirements.txt'`` |
+---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+
| :ref:`JOBTMPL/StaticTypeCheck/Input/html_report` | no | string | ``'report/typing'`` |
+---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+
| :ref:`JOBTMPL/StaticTypeCheck/Input/junit_report` | no | string | ``'StaticTypingSummary.xml'`` |
+---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+
| :ref:`JOBTMPL/StaticTypeCheck/Input/html_artifact` | no | string | ``''`` |
+---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+
| :ref:`JOBTMPL/StaticTypeCheck/Input/junit_artifact` | no | string | ``''`` |
+---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+
+---------------------------------------------------------------------+----------+----------------+------------------------------------------------------------------------------------------------------------------------------------------+
| Parameter Name | Required | Type | Default |
+=====================================================================+==========+================+==========================================================================================================================================+
| :ref:`JOBTMPL/StaticTypeCheck/Input/ubuntu_image_version` | no | string | ``'24.04'`` |
+---------------------------------------------------------------------+----------+----------------+------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`JOBTMPL/StaticTypeCheck/Input/python_version` | no | string | ``'3.13'`` |
+---------------------------------------------------------------------+----------+----------------+------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`JOBTMPL/StaticTypeCheck/Input/requirements` | no | string | ``'-r tests/requirements.txt'`` |
+---------------------------------------------------------------------+----------+----------------+------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`JOBTMPL/StaticTypeCheck/Input/mypy_options` | no | string | ``''`` |
+---------------------------------------------------------------------+----------+----------------+------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`JOBTMPL/StaticTypeCheck/Input/cobertura_report` | no | string (JSON) | :jsoncode:`{"fullpath": "report/typing/cobertura.xml", "directory": "report/typing", "filename": "cobertura.xml"}` |
+---------------------------------------------------------------------+----------+----------------+------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`JOBTMPL/StaticTypeCheck/Input/junit_report` | no | string (JSON) | :jsoncode:`{"fullpath": "report/typing/StaticTypingSummary.xml", "directory": "report/typing", "filename": "StaticTypingSummary.xml"}` |
+---------------------------------------------------------------------+----------+----------------+------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`JOBTMPL/StaticTypeCheck/Input/html_report` | no | string (JSON) | :jsoncode:`{"directory": "report/typing/html"}` |
+---------------------------------------------------------------------+----------+----------------+------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`JOBTMPL/StaticTypeCheck/Input/cobertura_artifact` | no | string | ``''`` |
+---------------------------------------------------------------------+----------+----------------+------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`JOBTMPL/StaticTypeCheck/Input/junit_artifact` | no | string | ``''`` |
+---------------------------------------------------------------------+----------+----------------+------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`JOBTMPL/StaticTypeCheck/Input/html_artifact` | no | string | ``''`` |
+---------------------------------------------------------------------+----------+----------------+------------------------------------------------------------------------------------------------------------------------------------------+
.. rubric:: Goto :ref:`secrets <JOBTMPL/StaticTypeCheck/Secrets>`
@@ -171,16 +180,56 @@ requirements
:Description: Python dependencies to be installed through *pip*.
.. _JOBTMPL/StaticTypeCheck/Input/html_report:
.. _JOBTMPL/StaticTypeCheck/Input/mypy_options:
html_report
===========
mypy_options
============
:Type: string
:Required: no
:Default Value: ``'report/typing'``
:Possible Values: Any valid directory or subdirectory path.
:Description: The directory containing the generated HTML report.
:Default Value: ``''``
:Possible Values: Any valid command line options for :term:`mypy`.
:Description: Additional options handed over to mypy as ``mypy ${mypy_options}``.
.. _JOBTMPL/StaticTypeCheck/Input/cobertura_report:
cobertura_report
================
:Type: string (JSON)
:Required: no
:Default Value:
.. code-block:: json
{ "directory": "reports/typing",
"filename": "cobertura.xml",
"fullpath": "reports/typing/cobertura.xml"
}
:Possible Values: Any valid JSON string containing a JSON object with fields:
:directory: Directory or sub-directory where the type checking report in Cobertura XML format will be
saved.
:filename: Filename of the generated type checking report in Cobertura XML format. |br|
Currently, this filename is hardcoded within :term:`mypy` as :file:`cobertura.xml`.
:fullpath: The concatenation of both previous fields using the ``/`` separator.
:Description: Directory, filename and fullpath as JSON object where the type checking report in Cobertura XML format
will be saved. |br|
This path is configured in :file:`pyproject.toml` and can be extracted by
:ref:`JOBTMPL/ExtractConfiguration`.
:Example:
.. code-block:: yaml
ConfigParams:
uses: pyTooling/Actions/.github/workflows/ExtractConfiguration.yml@r5
UnitTesting:
uses: pyTooling/Actions/.github/workflows/StaticTypeCheck.yml@r5
needs:
- ConfigParams
with:
...
cobertura_report: ${{ needs.ConfigParams.outputs.statictyping_cobertura }}
.. _JOBTMPL/StaticTypeCheck/Input/junit_report:
@@ -188,23 +237,84 @@ html_report
junit_report
============
:Type: string
:Type: string (JSON)
:Required: no
:Default Value: ``'StaticTypingSummary.xml'``
:Possible Values: Any valid file name for mypy's JUnit XML report.
:Description: File name for the JUnit XML file.
:Default Value:
.. code-block:: json
{ "directory": "reports/typing",
"filename": "StaticTypingSummary.xml",
"fullpath": "reports/typing/StaticTypingSummary.xml"
}
:Possible Values: Any valid JSON string containing a JSON object with fields:
:directory: Directory or sub-directory where the type checking report in JUnit XML format will be
saved.
:filename: Filename of the generated type checking report in JUnit XML format. |br|
Any valid file name for mypy's JUnit XML report.
:fullpath: The concatenation of both previous fields using the ``/`` separator.
:Description: Directory, filename and fullpath as JSON object where the type checking report in JUnit XML format
will be saved. |br|
This path is configured in :file:`pyproject.toml` and can be extracted by
:ref:`JOBTMPL/ExtractConfiguration`.
:Example:
.. code-block:: yaml
ConfigParams:
uses: pyTooling/Actions/.github/workflows/ExtractConfiguration.yml@r5
UnitTesting:
uses: pyTooling/Actions/.github/workflows/StaticTypeCheck.yml@r5
needs:
- ConfigParams
with:
...
junit_report: ${{ needs.ConfigParams.outputs.statictyping_junit }}
.. _JOBTMPL/StaticTypeCheck/Input/html_artifact:
.. _JOBTMPL/StaticTypeCheck/Input/html_report:
html_artifact
=============
html_report
===========
:Type: string (JSON)
:Required: no
:Default Value:
.. code-block:: json
{ "directory": "reports/typing/html"
}
:Possible Values: Any valid JSON string containing a JSON object with fields:
:directory: Directory or sub-directory where the type checking report in HTML format will be saved.
:Description: Directory as JSON object where the type checking report in HTML format will be saved. |br|
This path is configured in :file:`pyproject.toml` and can be extracted by
:ref:`JOBTMPL/ExtractConfiguration`.
:Example:
.. code-block:: yaml
ConfigParams:
uses: pyTooling/Actions/.github/workflows/ExtractConfiguration.yml@r5
UnitTesting:
uses: pyTooling/Actions/.github/workflows/StaticTypeCheck.yml@r5
needs:
- ConfigParams
with:
...
html_report: ${{ needs.ConfigParams.outputs.statictyping_html }}
.. _JOBTMPL/StaticTypeCheck/Input/cobertura_artifact:
cobertura_artifact
==================
:Type: string
:Required: no
:Default Value: ``''``
:Possible Values: Any valid artifact name.
:Description: Name of the artifact containing the HTML report.
:Description: Name of the artifact containing the Cobertura XML report.
.. _JOBTMPL/StaticTypeCheck/Input/junit_artifact:
@@ -219,6 +329,18 @@ junit_artifact
:Description: Name of the artifact containing the JUnit XML report.
.. _JOBTMPL/StaticTypeCheck/Input/html_artifact:
html_artifact
=============
:Type: string
:Required: no
:Default Value: ``''``
:Possible Values: Any valid artifact name.
:Description: Name of the artifact containing the HTML report.
.. _JOBTMPL/StaticTypeCheck/Secrets:
Secrets

970
doc/JobTemplate/Setup/ExtractConfiguration.rst
View File

File diff suppressed because it is too large Load Diff

184
doc/JobTemplate/Setup/Parameters.rst
View File

@@ -208,17 +208,21 @@ This job template needs no secrets.
.. rubric:: Goto :ref:`output parameters <JOBTMPL/Parameters/Outputs>`
+---------------------------------------------------------------------+----------+-------------------------------------------------------------------+
| Result Name | Type | Description |
+=====================================================================+==========+===================================================================+
| :ref:`JOBTMPL/Parameters/Output/python_version` | string | |
+---------------------------------------------------------------------+----------+-------------------------------------------------------------------+
| :ref:`JOBTMPL/Parameters/Output/python_jobs` | string | |
+---------------------------------------------------------------------+----------+-------------------------------------------------------------------+
| :ref:`JOBTMPL/Parameters/Output/artifact_names` | string | |
+---------------------------------------------------------------------+----------+-------------------------------------------------------------------+
| :ref:`JOBTMPL/Parameters/Output/params` | string | **deprecated** |
+---------------------------------------------------------------------+----------+-------------------------------------------------------------------+
+---------------------------------------------------------------------+----------------+-------------------------------------------------------------------+
| Result Name | Type | Description |
+=====================================================================+================+===================================================================+
| :ref:`JOBTMPL/Parameters/Output/python_version` | string | |
+---------------------------------------------------------------------+----------------+-------------------------------------------------------------------+
| :ref:`JOBTMPL/Parameters/Output/package_fullname` | string | |
+---------------------------------------------------------------------+----------------+-------------------------------------------------------------------+
| :ref:`JOBTMPL/Parameters/Output/package_directory` | string | |
+---------------------------------------------------------------------+----------------+-------------------------------------------------------------------+
| :ref:`JOBTMPL/Parameters/Output/artifact_basename` | string | |
+---------------------------------------------------------------------+----------------+-------------------------------------------------------------------+
| :ref:`JOBTMPL/Parameters/Output/artifact_names` | string (JSON) | |
+---------------------------------------------------------------------+----------------+-------------------------------------------------------------------+
| :ref:`JOBTMPL/Parameters/Output/python_jobs` | string (JSON) | |
+---------------------------------------------------------------------+----------------+-------------------------------------------------------------------+
.. _JOBTMPL/Parameters/Inputs:
@@ -591,6 +595,87 @@ python_version
python_version: ${{ needs.Params.outputs.python_version }}
.. _JOBTMPL/Parameters/Output/package_fullname:
package_fullname
================
:Type: string
:Description: Returns the full package name composed from :ref:`JOBTMPL/Parameters/Input/package_namespace`
and :ref:`JOBTMPL/Parameters/Input/package_name`.
:Example: ``myFramework.Extension``
.. _JOBTMPL/Parameters/Output/package_directory:
package_directory
=================
:Type: string
:Description: Returns the full package path composed from :ref:`JOBTMPL/Parameters/Input/package_namespace`
and :ref:`JOBTMPL/Parameters/Input/package_name`.
:Example: ``myFramework/Extension``
.. _JOBTMPL/Parameters/Output/artifact_basename:
artifact_basename
=================
:Type: string
:Description: Returns the basename (prefix) of all :ref:`artifact names <JOBTMPL/Parameters/Output/artifact_names>` |br|.
The basename is either :ref:`JOBTMPL/Parameters/Input/name` if set, otherwise its
:ref:`JOBTMPL/Parameters/Output/package_fullname`.
:Example: ``myFramework.Extension``
.. _JOBTMPL/Parameters/Output/artifact_names:
artifact_names
==============
:Type: string (JSON)
:Description: Returns a JSON dictionary of artifact names sharing a common prefix (see :ref:`JOBTMPL/Parameters/Input/name`). |br|
As artifacts are handed from jo to job, a consistent naming scheme is advised to avoid duplications
and naming artifacts by hand. This technique solves again the problem of global variables in GitHub
Action YAMl files and the need for assigning the same value (here artifact name) to multiple jobs
templates.
The supported artifacts are:
:unittesting_xml: UnitTesting XML summary report
:unittesting_html: UnitTesting HTML summary report
:perftesting_xml: PerformanceTesting XML summary report
:benchtesting_xml: Benchmarking XML summary report
:apptesting_xml: ApplicationTesting XML summary report
:codecoverage_sqlite: Code Coverage internal database (SQLite)
:codecoverage_xml: Code Coverage Cobertura XML report
:codecoverage_json: Code Coverage Coverage.py JSON report
:codecoverage_html: Code Coverage HTML report
:statictyping_cobertura: Static Type Checking Cobertura XML report
:statictyping_junit: Static Type Checking JUnit XML report
:statictyping_html: Static Type Checking HTML report
:package_all: Packaged Python project (multiple formats)
:documentation_html: Documentation in HTML format
:documentation_latex: Documentation in LaTeX format
:documentation_pdf: Documentation in PDF format
:Example:
.. code-block:: yaml
jobs:
Params:
uses: pyTooling/Actions/.github/workflows/Parameters.yml@r5
with:
name: pyTooling
Coverage:
uses: pyTooling/Actions/.github/workflows/UnitTesting.yml@r5
needs:
- Params
with:
unittest_xml_artifact: ${{ fromJson(needs.Params.outputs.artifact_names).unittesting_xml }}
.. _JOBTMPL/Parameters/Output/python_jobs:
python_jobs
@@ -600,14 +685,14 @@ python_jobs
:Description: Returns a JSON array of job descriptions, wherein each job description is a dictionary providing the
following key-value pairs:
* ``sysicon`` - icon to display
* ``system`` - name of the system
* ``runs-on`` - virtual machine image and base operating system
* ``runtime`` - name of the runtime environment if not running natively on the VM image
* ``shell`` - name of the shell
* ``pyicon`` - icon for CPython or pypy
* ``python`` - Python version
* ``envname`` - full name of the selected environment
:sysicon: icon to display
:system: name of the system
:runs-on: virtual machine image and base operating system
:runtime: name of the runtime environment if not running natively on the VM image
:shell: name of the shell
:pyicon: icon for CPython or pypy
:python: Python version
:envname: full name of the selected environment
:Example:
.. code-block:: yaml
@@ -683,67 +768,6 @@ python_jobs
{"sysicon": "🪟🟨", "system": "msys2", "runs-on": "windows-2025", "runtime": "UCRT64", "shell": "msys2 {0}", "pyicon": "🟢", "python": "3.12", "envname": "Windows+MSYS2 (x86-64) - UCRT64" }
]
.. _JOBTMPL/Parameters/Output/artifact_names:
artifact_names
==============
:Type: string (JSON)
:Description: Returns a JSON dictionary of artifact names sharing a common prefix (see :ref:`JOBTMPL/Parameters/Input/name`). |br|
As artifacts are handed from jo to job, a consistent naming scheme is advised to avoid duplications
and naming artifacts by hand. This technique solves again the problem of global variables in GitHub
Action YAMl files and the need for assigning the same value (here artifact name) to multiple jobs
templates.
The supported artifacts are:
* ``unittesting_xml`` - UnitTesting XML summary report
* ``unittesting_html`` - UnitTesting HTML summary report
* ``perftesting_xml`` - PerformanceTesting XML summary report
* ``benchtesting_xml`` - Benchmarking XML summary report
* ``apptesting_xml`` - ApplicationTesting XML summary report
* ``codecoverage_sqlite`` - Code Coverage internal database (SQLite)
* ``codecoverage_xml`` - Code Coverage XML report
* ``codecoverage_json`` - Code Coverage JSON report
* ``codecoverage_html`` - Code Coverage HTML report
* ``statictyping_html`` - Static Type Checking HTML report
* ``package_all`` - Packaged Python project (multiple formats)
* ``documentation_html`` - Documentation in HTML format
* ``documentation_latex`` - Documentation in LaTeX format
* ``documentation_pdf`` - Documentation in PDF format
:Example:
.. code-block:: yaml
jobs:
Params:
uses: pyTooling/Actions/.github/workflows/Parameters.yml@r5
with:
name: pyTooling
Coverage:
uses: pyTooling/Actions/.github/workflows/UnitTesting.yml@r5
needs:
- Params
with:
unittest_xml_artifact: ${{ fromJson(needs.Params.outputs.artifact_names).unittesting_xml }}
.. _JOBTMPL/Parameters/Output/params:
params
======
.. attention:: ``params`` is deprecated.
:Type: string (JSON)
:Description: Returns a JSON dictionary of artifact names. |br|
Use :ref:`JOBTMPL/Parameters/Output/artifact_names` as a more powerful replacement.
:Replacements: * ``params['unittesting']`` |rarr| ``artifact_names['unittesting_xml']``
* ``params['coverage']`` |rarr| ``artifact_names['codecoverage_xml']``
* ``params['typing']`` |rarr| ``artifact_names['statictyping_html']``
* ``params['package']`` |rarr| ``artifact_names['package_all']``
* ``params['doc']`` |rarr| ``artifact_names['documentation_html']``
.. _JOBTMPL/Parameters/Optimizations:

356
doc/JobTemplate/Testing/UnitTesting.rst
View File

@@ -77,17 +77,9 @@ the :ref:`JOBTMPL/ExtractConfiguration` job template is used to extract these se
.. code-block:: yaml
name: Pipeline
on:
push:
workflow_dispatch:
jobs:
ConfigParams:
uses: pyTooling/Actions/.github/workflows/ExtractConfiguration.yml@r5
with:
package_name: myPackage
UnitTestingParams:
uses: pyTooling/Actions/.github/workflows/Parameters.yml@r5
@@ -100,26 +92,11 @@ the :ref:`JOBTMPL/ExtractConfiguration` job template is used to extract these se
- ConfigParams
- UnitTestingParams
with:
jobs: ${{ needs.UnitTestingParams.outputs.python_jobs }}
requirements: "-r tests/unit/requirements.txt"
unittest_report_xml_directory: ${{ needs.ConfigParams.outputs.unittest_report_xml_directory }}
unittest_report_xml_filename: ${{ needs.ConfigParams.outputs.unittest_report_xml_filename }}
unittest_xml_artifact: ${{ fromJson(needs.UnitTestingParams.outputs.artifact_names).unittesting_xml }}
coverage_sqlite_artifact: ${{ fromJson(needs.UnitTestingParams.outputs.artifact_names).codecoverage_sqlite }}
.. code-block:: yaml
jobs:
Params:
# ...
UnitTesting:
uses: pyTooling/Actions/.github/workflows/UnitTesting.yml@r5
needs:
- Params
with:
jobs: ${{ needs.Params.outputs.python_jobs }}
artifact: ${{ fromJson(needs.Params.outputs.artifact_names).unittesting }}
jobs: ${{ needs.UnitTestingParams.outputs.python_jobs }}
requirements: '-r tests/unit/requirements.txt'
unittest_report_xml: ${{ needs.ConfigParams.outputs.unittest_report_xml }}
unittest_xml_artifact: ${{ fromJson(needs.UnitTestingParams.outputs.artifact_names).unittesting_xml }}
coverage_sqlite_artifact: ${{ fromJson(needs.UnitTestingParams.outputs.artifact_names).codecoverage_sqlite }}
.. seealso::
@@ -138,67 +115,69 @@ the :ref:`JOBTMPL/ExtractConfiguration` job template is used to extract these se
Parameter Summary
*****************
.. # |unittest_report_xml| code-block:: json
{ "directory": "report/unit",
"filename": "TestReportSummary.xml",
"fullpath": "report/unit/TestReportSummary.xml"
}
.. rubric:: Goto :ref:`input parameters <JOBTMPL/UnitTesting/Inputs>`
+-------------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+
| Parameter Name | Required | Type | Default |
+=========================================================================+==========+==========+===================================================================+
| :ref:`JOBTMPL/UnitTesting/Input/jobs` | yes | string | — — — — |
+-------------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+
| :ref:`JOBTMPL/UnitTesting/Input/apt` | no | string | ``''`` |
+-------------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+
| :ref:`JOBTMPL/UnitTesting/Input/brew` | no | string | ``''`` |
+-------------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+
| :ref:`JOBTMPL/UnitTesting/Input/pacboy` | no | string | ``''`` |
+-------------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+
| :ref:`JOBTMPL/UnitTesting/Input/requirements` | no | string | ``'-r tests/requirements.txt'`` |
+-------------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+
| :ref:`JOBTMPL/UnitTesting/Input/mingw_requirements` | no | string | ``''`` |
+-------------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+
| :ref:`JOBTMPL/UnitTesting/Input/macos_before_script` | no | string | ``''`` |
+-------------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+
| :ref:`JOBTMPL/UnitTesting/Input/macos_arm_before_script` | no | string | ``''`` |
+-------------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+
| :ref:`JOBTMPL/UnitTesting/Input/ubuntu_before_script` | no | string | ``''`` |
+-------------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+
| :ref:`JOBTMPL/UnitTesting/Input/mingw64_before_script` | no | string | ``''`` |
+-------------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+
| :ref:`JOBTMPL/UnitTesting/Input/ucrt64_before_script` | no | string | ``''`` |
+-------------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+
| :ref:`JOBTMPL/UnitTesting/Input/root_directory` | no | string | ``''`` |
+-------------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+
| :ref:`JOBTMPL/UnitTesting/Input/tests_directory` | no | string | ``'tests'`` |
+-------------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+
| :ref:`JOBTMPL/UnitTesting/Input/unittest_directory` | no | string | ``'unit'`` |
+-------------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+
| :ref:`JOBTMPL/UnitTesting/Input/unittest_report_xml_directory` | no | string | ``'report/unit'`` |
+-------------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+
| :ref:`JOBTMPL/UnitTesting/Input/unittest_report_xml_filename` | no | string | ``'TestReportSummary.xml'`` |
+-------------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+
| :ref:`JOBTMPL/UnitTesting/Input/coverage_config` | no | string | ``'pyproject.toml'`` |
+-------------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+
| :ref:`JOBTMPL/UnitTesting/Input/coverage_report_xml_directory` | no | string | ``'report/coverage'`` |
+-------------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+
| :ref:`JOBTMPL/UnitTesting/Input/coverage_report_xml_filename` | no | string | ``'coverage.xml'`` |
+-------------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+
| :ref:`JOBTMPL/UnitTesting/Input/coverage_report_json_directory` | no | string | ``'report/coverage'`` |
+-------------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+
| :ref:`JOBTMPL/UnitTesting/Input/coverage_report_json_filename` | no | string | ``'coverage.json'`` |
+-------------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+
| :ref:`JOBTMPL/UnitTesting/Input/coverage_report_html_directory` | no | string | ``'report/coverage/html'`` |
+-------------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+
| :ref:`JOBTMPL/UnitTesting/Input/unittest_xml_artifact` | no | string | ``''`` |
+-------------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+
| :ref:`JOBTMPL/UnitTesting/Input/unittest_html_artifact` | no | string | ``''`` |
+-------------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+
| :ref:`JOBTMPL/UnitTesting/Input/coverage_sqlite_artifact` | no | string | ``''`` |
+-------------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+
| :ref:`JOBTMPL/UnitTesting/Input/coverage_xml_artifact` | no | string | ``''`` |
+-------------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+
| :ref:`JOBTMPL/UnitTesting/Input/coverage_json_artifact` | no | string | ``''`` |
+-------------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+
| :ref:`JOBTMPL/UnitTesting/Input/coverage_html_artifact` | no | string | ``''`` |
+-------------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+
+-------------------------------------------------------------------------+----------+----------+-----------------------------------------------------------------------------------------------------------------------------------+
| Parameter Name | Required | Type | Default |
+=========================================================================+==========+==========+===================================================================================================================================+
| :ref:`JOBTMPL/UnitTesting/Input/jobs` | yes | string | — — — — |
+-------------------------------------------------------------------------+----------+----------+-----------------------------------------------------------------------------------------------------------------------------------+
| :ref:`JOBTMPL/UnitTesting/Input/apt` | no | string | ``''`` |
+-------------------------------------------------------------------------+----------+----------+-----------------------------------------------------------------------------------------------------------------------------------+
| :ref:`JOBTMPL/UnitTesting/Input/brew` | no | string | ``''`` |
+-------------------------------------------------------------------------+----------+----------+-----------------------------------------------------------------------------------------------------------------------------------+
| :ref:`JOBTMPL/UnitTesting/Input/pacboy` | no | string | ``''`` |
+-------------------------------------------------------------------------+----------+----------+-----------------------------------------------------------------------------------------------------------------------------------+
| :ref:`JOBTMPL/UnitTesting/Input/requirements` | no | string | ``'-r tests/requirements.txt'`` |
+-------------------------------------------------------------------------+----------+----------+-----------------------------------------------------------------------------------------------------------------------------------+
| :ref:`JOBTMPL/UnitTesting/Input/mingw_requirements` | no | string | ``''`` |
+-------------------------------------------------------------------------+----------+----------+-----------------------------------------------------------------------------------------------------------------------------------+
| :ref:`JOBTMPL/UnitTesting/Input/macos_before_script` | no | string | ``''`` |
+-------------------------------------------------------------------------+----------+----------+-----------------------------------------------------------------------------------------------------------------------------------+
| :ref:`JOBTMPL/UnitTesting/Input/macos_arm_before_script` | no | string | ``''`` |
+-------------------------------------------------------------------------+----------+----------+-----------------------------------------------------------------------------------------------------------------------------------+
| :ref:`JOBTMPL/UnitTesting/Input/ubuntu_before_script` | no | string | ``''`` |
+-------------------------------------------------------------------------+----------+----------+-----------------------------------------------------------------------------------------------------------------------------------+
| :ref:`JOBTMPL/UnitTesting/Input/mingw64_before_script` | no | string | ``''`` |
+-------------------------------------------------------------------------+----------+----------+-----------------------------------------------------------------------------------------------------------------------------------+
| :ref:`JOBTMPL/UnitTesting/Input/ucrt64_before_script` | no | string | ``''`` |
+-------------------------------------------------------------------------+----------+----------+-----------------------------------------------------------------------------------------------------------------------------------+
| :ref:`JOBTMPL/UnitTesting/Input/root_directory` | no | string | ``''`` |
+-------------------------------------------------------------------------+----------+----------+-----------------------------------------------------------------------------------------------------------------------------------+
| :ref:`JOBTMPL/UnitTesting/Input/tests_directory` | no | string | ``'tests'`` |
+-------------------------------------------------------------------------+----------+----------+-----------------------------------------------------------------------------------------------------------------------------------+
| :ref:`JOBTMPL/UnitTesting/Input/unittest_directory` | no | string | ``'unit'`` |
+-------------------------------------------------------------------------+----------+----------+-----------------------------------------------------------------------------------------------------------------------------------+
| :ref:`JOBTMPL/UnitTesting/Input/unittest_report_xml` | no | string | :jsoncode:`{"directory": "report/unit", "filename": "TestReportSummary.xml", "fullpath": "report/unit/TestReportSummary.xml"}` |
+-------------------------------------------------------------------------+----------+----------+-----------------------------------------------------------------------------------------------------------------------------------+
| :ref:`JOBTMPL/UnitTesting/Input/coverage_config` | no | string | ``'pyproject.toml'`` |
+-------------------------------------------------------------------------+----------+----------+-----------------------------------------------------------------------------------------------------------------------------------+
| :ref:`JOBTMPL/UnitTesting/Input/coverage_report_xml` | no | string | :jsoncode:`{"directory": "report/coverage", "filename": "coverage.xml", "fullpath": "report/coverage/coverage.xml"}` |
+-------------------------------------------------------------------------+----------+----------+-----------------------------------------------------------------------------------------------------------------------------------+
| :ref:`JOBTMPL/UnitTesting/Input/coverage_report_json` | no | string | :jsoncode:`{"directory": "report/coverage", "filename": "coverage.json", "fullpath": "report/coverage/coverage.json"}` |
+-------------------------------------------------------------------------+----------+----------+-----------------------------------------------------------------------------------------------------------------------------------+
| :ref:`JOBTMPL/UnitTesting/Input/coverage_report_html` | no | string | :jsoncode:`{"directory": "report/coverage"}` |
+-------------------------------------------------------------------------+----------+----------+-----------------------------------------------------------------------------------------------------------------------------------+
| :ref:`JOBTMPL/UnitTesting/Input/unittest_xml_artifact` | no | string | ``''`` |
+-------------------------------------------------------------------------+----------+----------+-----------------------------------------------------------------------------------------------------------------------------------+
| :ref:`JOBTMPL/UnitTesting/Input/unittest_html_artifact` | no | string | ``''`` |
+-------------------------------------------------------------------------+----------+----------+-----------------------------------------------------------------------------------------------------------------------------------+
| :ref:`JOBTMPL/UnitTesting/Input/coverage_sqlite_artifact` | no | string | ``''`` |
+-------------------------------------------------------------------------+----------+----------+-----------------------------------------------------------------------------------------------------------------------------------+
| :ref:`JOBTMPL/UnitTesting/Input/coverage_xml_artifact` | no | string | ``''`` |
+-------------------------------------------------------------------------+----------+----------+-----------------------------------------------------------------------------------------------------------------------------------+
| :ref:`JOBTMPL/UnitTesting/Input/coverage_json_artifact` | no | string | ``''`` |
+-------------------------------------------------------------------------+----------+----------+-----------------------------------------------------------------------------------------------------------------------------------+
| :ref:`JOBTMPL/UnitTesting/Input/coverage_html_artifact` | no | string | ``''`` |
+-------------------------------------------------------------------------+----------+----------+-----------------------------------------------------------------------------------------------------------------------------------+
.. rubric:: Goto :ref:`secrets <JOBTMPL/UnitTesting/Secrets>`
@@ -224,14 +203,14 @@ jobs
:Default Value: — — — —
:Possible Values: A JSON string with an array of dictionaries with the following key-value pairs:
* ``sysicon`` - icon to display
* ``system`` - name of the system
* ``runs-on`` - virtual machine image and base operating system
* ``runtime`` - name of the runtime environment if not running natively on the VM image
* ``shell`` - name of the shell
* ``pyicon`` - icon for CPython or pypy
* ``python`` - Python version
* ``envname`` - full name of the selected environment
:sysicon: icon to display
:system: name of the system
:runs-on: virtual machine image and base operating system
:runtime: name of the runtime environment if not running natively on the VM image
:shell: name of the shell
:pyicon: icon for CPython or pypy
:python: Python version
:envname: full name of the selected environment
:Description: A JSON encoded job matrix to run multiple Python job variations.
@@ -506,30 +485,43 @@ unittest_directory
:Description: Path to the directory containing unit tests (relative from :ref:`JOBTMPL/UnitTesting/Input/tests_directory`).
.. _JOBTMPL/UnitTesting/Input/unittest_report_xml_directory:
.. _JOBTMPL/UnitTesting/Input/unittest_report_xml:
unittest_report_xml_directory
=============================
unittest_report_xml
===================
:Type: string
:Type: string (JSON)
:Required: no
:Default Value: ``'report/unit'``
:Possible Values: Any valid directory or sub-directory.
:Description: Directory or sub-directory where the unittest summary report in XML format will be saved. |br|
This path is configured in :file:`pyproject.toml` and can be extracted by :ref:`JOBTMPL/ExtractConfiguration`.
:Default Value:
.. code-block:: json
{ "directory": "reports/unit",
"filename": "UnittestReportSummary.xml",
"fullpath": "reports/unit/UnittestReportSummary.xml"
}
:Possible Values: Any valid JSON string containing a JSON object with fields:
.. _JOBTMPL/UnitTesting/Input/unittest_report_xml_filename:
:directory: Directory or sub-directory where the unittest summary report in XML format will be saved.
:filename: Filename of the generated JUnit XML report. |br|
Any valid filename accepted by ``pytest ... --junitxml=${unittest_report_xml}``.
:fullpath: The concatenation of both previous fields using the ``/`` separator.
:Description: Directory, filename and fullpath as JSON object where the unittest summary report in XML format will
be saved. |br|
This path is configured in :file:`pyproject.toml` and can be extracted by
:ref:`JOBTMPL/ExtractConfiguration`.
:Example:
.. code-block:: yaml
unittest_report_xml_filename
============================
ConfigParams:
uses: pyTooling/Actions/.github/workflows/ExtractConfiguration.yml@r5
:Type: string
:Required: no
:Default Value: ``'TestReportSummary.xml'``
:Possible Values: Any valid filename accepted by ``pytest ... --junitxml=${unittest_report_xml_filename}``.
:Description: Filename of the generated JUnit XML report. |br|
This filename is configured in :file:`pyproject.toml` and can be extracted by :ref:`JOBTMPL/ExtractConfiguration`.
UnitTesting:
uses: pyTooling/Actions/.github/workflows/UnitTesting.yml@r5
needs:
- ConfigParams
with:
...
unittest_report_xml: ${{ needs.ConfigParams.outputs.unittest_report_xml }}
.. _JOBTMPL/UnitTesting/Input/coverage_config:
@@ -543,69 +535,117 @@ coverage_config
:Possible Values: TBD
.. _JOBTMPL/UnitTesting/Input/coverage_report_xml_directory:
.. _JOBTMPL/UnitTesting/Input/coverage_report_xml:
coverage_report_xml_directory
=============================
coverage_report_xml
===================
:Type: string
:Type: string (JSON)
:Required: no
:Default Value: ``'report/coverage'``
:Possible Values: Any valid directory or sub-directory.
:Description: Directory or sub-directory where the code covergae report in XML format will be saved. |br|
This path is configured in :file:`pyproject.toml` and can be extracted by :ref:`JOBTMPL/ExtractConfiguration`.
:Default Value:
.. code-block:: json
{ "directory": "reports/coverage",
"filename": "coverage.xml",
"fullpath": "reports/coverage/coverage.xml"
}
:Possible Values: Any valid JSON string containing a JSON object with fields:
:directory: Directory or sub-directory where the code coverage report in Cobertura XML format will be
saved.
:filename: Filename of the generated Cobertura XML report. |br|
Any valid XML filename.
:fullpath: The concatenation of both previous fields using the ``/`` separator.
:Description: Directory, filename and fullpath as JSON object where the code coverage report in Cobertura XML format
will be saved. |br|
This path is configured in :file:`pyproject.toml` and can be extracted by
:ref:`JOBTMPL/ExtractConfiguration`.
:Example:
.. code-block:: yaml
ConfigParams:
uses: pyTooling/Actions/.github/workflows/ExtractConfiguration.yml@r5
UnitTesting:
uses: pyTooling/Actions/.github/workflows/UnitTesting.yml@r5
needs:
- ConfigParams
with:
...
coverage_report_xml: ${{ needs.ConfigParams.outputs.coverage_report_xml }}
.. _JOBTMPL/UnitTesting/Input/coverage_report_xml_filename:
.. _JOBTMPL/UnitTesting/Input/coverage_report_json:
coverage_report_xml_filename
============================
coverage_report_json
====================
:Type: string
:Type: string (JSON)
:Required: no
:Default Value: ``'coverage.xml'``
:Possible Values: Any valid XML filename.
:Description: Filename of the generated code coverage report in Cobertura format. |br|
This filename is configured in :file:`pyproject.toml` and can be extracted by :ref:`JOBTMPL/ExtractConfiguration`.
:Default Value:
.. code-block:: json
{ "directory": "reports/coverage",
"filename": "coverage.json",
"fullpath": "reports/coverage/coverage.json"
}
:Possible Values: Any valid JSON string containing a JSON object with fields:
:directory: Directory or sub-directory where the code coverage report in Coverage.py's JSON format
will be saved.
:filename: Filename of the generated Coverage.py JSON report. |br|
Any valid JSON filename.
:fullpath: The concatenation of both previous fields using the ``/`` separator.
:Description: Directory, filename and fullpath as JSON object where the code coverage report in Coverage.py's JSON
format will be saved. |br|
This path is configured in :file:`pyproject.toml` and can be extracted by
:ref:`JOBTMPL/ExtractConfiguration`.
:Example:
.. code-block:: yaml
ConfigParams:
uses: pyTooling/Actions/.github/workflows/ExtractConfiguration.yml@r5
UnitTesting:
uses: pyTooling/Actions/.github/workflows/UnitTesting.yml@r5
needs:
- ConfigParams
with:
...
coverage_report_json: ${{ needs.ConfigParams.outputs.coverage_report_json }}
.. _JOBTMPL/UnitTesting/Input/coverage_report_json_directory:
.. _JOBTMPL/UnitTesting/Input/coverage_report_html:
coverage_report_json_directory
==============================
coverage_report_html
====================
:Type: string
:Type: string (JSON)
:Required: no
:Default Value: ``'report/coverage'``
:Possible Values: Any valid directory or sub-directory.
:Description: Directory or sub-directory where the code covergae report in JSON format will be saved. |br|
This path is configured in :file:`pyproject.toml` and can be extracted by :ref:`JOBTMPL/ExtractConfiguration`.
:Default Value:
.. code-block:: json
{ "directory": "reports/coverage/html"
}
:Possible Values: Any valid JSON string containing a JSON object with fields:
.. _JOBTMPL/UnitTesting/Input/coverage_report_json_filename:
:directory: Directory or sub-directory where the code coverage report in HTML format will be saved.
:Description: Directory as JSON object where the code coverage report in HTML format will be saved. |br|
This path is configured in :file:`pyproject.toml` and can be extracted by
:ref:`JOBTMPL/ExtractConfiguration`.
:Example:
.. code-block:: yaml
coverage_report_json_filename
=============================
ConfigParams:
uses: pyTooling/Actions/.github/workflows/ExtractConfiguration.yml@r5
:Type: string
:Required: no
:Default Value: ``'coverage.json'``
:Possible Values: Any valid JSON filename.
:Description: Filename of the generated code coverage report in Coverage.py JSON format. |br|
This filename is configured in :file:`pyproject.toml` and can be extracted by :ref:`JOBTMPL/ExtractConfiguration`.
.. _JOBTMPL/UnitTesting/Input/coverage_report_html_directory:
coverage_report_html_directory
==============================
:Type: string
:Required: no
:Default Value: ``'report/coverage/html'``
:Possible Values: Any valid directory or sub-directory.
:Description: Directory or sub-directory where the code covergae report in HTML format will be saved. |br|
This path is configured in :file:`pyproject.toml` and can be extracted by :ref:`JOBTMPL/ExtractConfiguration`.
UnitTesting:
uses: pyTooling/Actions/.github/workflows/UnitTesting.yml@r5
needs:
- ConfigParams
with:
...
coverage_report_html: ${{ needs.ConfigParams.outputs.coverage_report_html }}
.. _JOBTMPL/UnitTesting/Input/unittest_xml_artifact:

75
doc/_static/css/override.css vendored
View File

@@ -1,24 +1,8 @@
/* theme overrides */
.rst-content h1,
.rst-content h2 {
margin-top: 24px;
margin-bottom: 6px;
text-decoration: underline;
}
/*
Theme overrides for ReadTheDocs Theme by Patrick Lehmann
*/
.rst-content h3,
.rst-content h4,
.rst-content h5,
.rst-content h6 {
margin-top: 12px;
margin-bottom: 6px;
}
.rst-content p {
margin-bottom: 6px
}
/* general overrides */
/* General overrides */
html {
font-size: 15px;
}
@@ -33,10 +17,20 @@ footer p {
font-size: 95%
}
section > p,
.section p,
.simple li {
text-align: justify
/* Headline */
.rst-content h1,
.rst-content h2 {
margin-top: 24px;
margin-bottom: 6px;
text-decoration: underline;
}
.rst-content h3,
.rst-content h4,
.rst-content h5,
.rst-content h6 {
margin-top: 12px;
margin-bottom: 6px;
}
.rst-content .topic-title {
@@ -54,6 +48,31 @@ section > p,
margin-bottom: 16px;
}
/* Paragraphs */
.rst-content p {
margin-bottom: 6px
}
section > p,
.section p,
.simple li {
text-align: justify
}
/* Field lists*/
/* last paragraph in a field list*/
dl.field-list > dd > p:last-of-type {
margin-bottom: 6px /* 12px */
}
/* Nested field lists */
dl.field-list > dd > dl.field-list.simple {
margin-bottom: 0px /* 24px */
}
/* code-block within field list */
dl.field-list > dd > div:has(div.highlight) {
margin-bottom: 0px /* 24px */
}
/* wyrm overrides */
.wy-menu-vertical header,
.wy-menu-vertical p.caption {
@@ -66,8 +85,6 @@ section > p,
.wy-side-nav-search {
margin-bottom: 0 /* .809em */;
background-color: #333333 /* #2980b9 */;
/* BTD: */
/*color: #fcfcfc*/
}
.wy-side-nav-search input[type=text] {
@@ -75,15 +92,11 @@ section > p,
}
.wy-side-nav-search .wy-dropdown > a, .wy-side-nav-search > a {
/* BTD: */
/*color: #fcfcfc;*/
margin-bottom: 0.404em /* .809em */;
}
.wy-side-nav-search > div.version {
margin: 0 0 6px 0;
/* BTD: */
/*margin-top: -.4045em;*/
}
.wy-nav .wy-menu-vertical a:hover {
@@ -98,7 +111,7 @@ section > p,
background: #333333 /* #2980b9 */;
}
/* Sphinx Design */
/* Theme overrides for Sphinx Design by Patrick Lehmann */
.sd-tab-set {
margin: 0
}

9
doc/conf.py
View File

@@ -1,7 +1,7 @@
# 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 sys import path as sys_path
from sys import path as sys_path
from os.path import abspath
from pathlib import Path
@@ -35,6 +35,7 @@ sys_path.insert(0, abspath(f"../{directoryName}"))
packageInformationFile = Path(f"../{directoryName}/__init__.py")
versionInformation = extractVersionInformation(packageInformationFile)
project = f"{githubNamespace}/{githubProject}"
author = versionInformation.Author
copyright = versionInformation.Copyright
version = ".".join(versionInformation.Version.split(".")[:2]) # e.g. 2.3 The short X.Y version.
@@ -80,6 +81,7 @@ except Exception as ex:
# ==============================================================================
# Options for HTML output
# ==============================================================================
html_title = f"{githubNamespace}/{githubProject} v{versionInformation.Version}"
html_theme = "sphinx_rtd_theme"
html_theme_options = {
"logo_only": True,
@@ -190,7 +192,8 @@ extensions = [
# Sphinx.Ext.InterSphinx
# ==============================================================================
intersphinx_mapping = {
"python": ("https://docs.python.org/3", None),
"python": ("https://docs.python.org/3", None),
"pyEDAARpt": ("https://edaa-org.github.io/pyEDAA.Reports", None),
}
@@ -299,7 +302,7 @@ report_doccov_packages = {
# ==============================================================================
autoapi_modules = {
f"{pythonProject}": {
"template": "package",
"template": "module",
"output": pythonProject,
"override": True
}

3
doc/index.rst
View File

@@ -300,7 +300,7 @@ License
:caption: pyDummy Example
:hidden:
myPackage/myPackage
Python Class Reference <myPackage/myPackage>
unittests/index
coverage/index
CodeCoverage
@@ -319,4 +319,5 @@ License
Doc-License
Glossary
genindex
Python Module Index <modindex>
TODO

8
doc/prolog.inc
View File

@@ -54,6 +54,14 @@
.. role:: addition
:class: colorgreen
.. role:: bashcode(code)
:language: bash
:class: highlight
.. role:: pycode(code)
:language: python
:class: highlight
.. role:: jsoncode(code)
:language: json
:class: highlight