pyTooling/Actions
1
0
Fork 0
mirror of https://github.com/pyTooling/Actions.git synced 2026-02-12 11:06: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

4
.github/workflows/CheckCodeQuality.yml vendored
View File

@@ -90,6 +90,10 @@ jobs:
mkdir -p report/bandit mkdir -p report/bandit
bandit -c pyproject.toml -r ${{ inputs.package_directory }} -f xml -o report/bandit/report.xml bandit -c pyproject.toml -r ${{ inputs.package_directory }} -f xml -o report/bandit/report.xml
- name: Debug
run: |
cat report/bandit/report.xml
- name: 📊 Publish Bandit Results - name: 📊 Publish Bandit Results
uses: dorny/test-reporter@v2 uses: dorny/test-reporter@v2
continue-on-error: true continue-on-error: true

17
.github/workflows/StaticTypeCheck.yml vendored
View File

@@ -48,17 +48,28 @@ on:
cobertura_report: cobertura_report:
description: 'Cobertura file to upload as an artifact.' description: 'Cobertura file to upload as an artifact.'
required: false required: false
default: '{"fullpath": "report/typing/cobertura.xml", "directory": "report/typing", "filename": "cobertura.xml"}' default: >-
{ "fullpath": "report/typing/cobertura.xml",
"directory": "report/typing",
"filename": "cobertura.xml"
}
type: string type: string
junit_report: junit_report:
description: 'JUnit file to upload as an artifact.' description: 'JUnit file to upload as an artifact.'
required: false required: false
default: '{"fullpath": "report/typing/StaticTypingSummary.xml", "directory": "report/typing", "filename": "StaticTypingSummary.xml"}' default: >-
{ "fullpath": "report/typing/StaticTypingSummary.xml",
"directory": "report/typing",
"filename": "StaticTypingSummary.xml"
}
type: string type: string
html_report: html_report:
description: 'Directory to upload as an artifact.' description: 'Directory to upload as an artifact.'
required: false required: false
default: '{"fullpath": "report/typing/html", "directory": "report/typing/html"}' default: >-
{ "directory": "report/typing/html"
}
# "fullpath": "report/typing/html",
type: string type: string
cobertura_artifact: cobertura_artifact:
description: 'Name of the typing cobertura artifact (Cobertura XML).' description: 'Name of the typing cobertura artifact (Cobertura XML).'

46
.github/workflows/UnitTesting.yml vendored
View File

@@ -95,44 +95,44 @@ on:
default: 'unit' default: 'unit'
type: string type: string
unittest_report_xml: unittest_report_xml:
description: 'Path where to save the unittest summary report XML.' description: 'JSON object describing the path where to save the unittest summary report XML.'
required: false required: false
default: 'report/unit' default: >-
{ "directory": "report/unit",
"filename": "TestReportSummary.xml",
"fullpath": "report/unit/TestReportSummary.xml"
}
type: string type: string
# unittest_report_xml_filename:
# description: 'Filename of the unittest summary report XML.'
# required: false
# default: 'TestReportSummary.xml'
# type: string
coverage_config: coverage_config:
description: 'Path to the .coveragerc file. Use pyproject.toml by default.' description: 'Path to the .coveragerc file. Use pyproject.toml by default.'
required: false required: false
default: 'pyproject.toml' default: 'pyproject.toml'
type: string type: string
coverage_report_xml: coverage_report_xml:
description: 'Directory where the coverage report in XML format will be generated.' description: 'JSON object describing the path where the coverage report in XML format will be generated.'
required: false required: false
default: 'report/coverage' default: >-
{ "directory": "report/coverage",
"filename": "coverage.xml",
"fullpath": "report/coverage/coverage.xml"
}
type: string type: string
# coverage_report_xml_filename:
# description: 'Filename how the coverage report in XML format will be named.'
# required: false
# default: 'coverage.xml'
# type: string
coverage_report_json: coverage_report_json:
description: 'Directory where the coverage report in JSON format will be generated.' description: 'JSON object describing the path where the coverage report in JSON format will be generated.'
required: false required: false
default: 'report/coverage' default: >-
{ "directory": "report/coverage",
"filename": "coverage.json",
"fullpath": "report/coverage/coverage.json"
}
type: string type: string
# coverage_report_json_filename:
# description: 'Filename how the coverage report in JSON format will be named.'
# required: false
# default: 'coverage.json'
# type: string
coverage_report_html: coverage_report_html:
description: 'Directory where the coverage report in HTML format will be generated.' description: 'JSON object describing the path where the coverage report in HTML format will be generated.'
required: false required: false
default: 'report/coverage/html' default: >-
{ "directory": "report/coverage/html",
}
# "fullpath": "report/coverage/html"
type: string type: string
unittest_xml_artifact: unittest_xml_artifact:
description: "Generate unit test report with junitxml and upload results as an artifact." description: "Generate unit test report with junitxml and upload results as an artifact."

92
doc/Glossary.rst
View File

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

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

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

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

File diff suppressed because it is too large Load Diff

180
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>` .. rubric:: Goto :ref:`output parameters <JOBTMPL/Parameters/Outputs>`
+---------------------------------------------------------------------+----------+-------------------------------------------------------------------+ +---------------------------------------------------------------------+----------------+-------------------------------------------------------------------+
| Result Name | Type | Description | | Result Name | Type | Description |
+=====================================================================+==========+===================================================================+ +=====================================================================+================+===================================================================+
| :ref:`JOBTMPL/Parameters/Output/python_version` | string | | | :ref:`JOBTMPL/Parameters/Output/python_version` | string | |
+---------------------------------------------------------------------+----------+-------------------------------------------------------------------+ +---------------------------------------------------------------------+----------------+-------------------------------------------------------------------+
| :ref:`JOBTMPL/Parameters/Output/python_jobs` | string | | | :ref:`JOBTMPL/Parameters/Output/package_fullname` | string | |
+---------------------------------------------------------------------+----------+-------------------------------------------------------------------+ +---------------------------------------------------------------------+----------------+-------------------------------------------------------------------+
| :ref:`JOBTMPL/Parameters/Output/artifact_names` | string | | | :ref:`JOBTMPL/Parameters/Output/package_directory` | string | |
+---------------------------------------------------------------------+----------+-------------------------------------------------------------------+ +---------------------------------------------------------------------+----------------+-------------------------------------------------------------------+
| :ref:`JOBTMPL/Parameters/Output/params` | string | **deprecated** | | :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: .. _JOBTMPL/Parameters/Inputs:
@@ -591,6 +595,87 @@ python_version
python_version: ${{ needs.Params.outputs.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: .. _JOBTMPL/Parameters/Output/python_jobs:
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 :Description: Returns a JSON array of job descriptions, wherein each job description is a dictionary providing the
following key-value pairs: following key-value pairs:
* ``sysicon`` - icon to display :sysicon: icon to display
* ``system`` - name of the system :system: name of the system
* ``runs-on`` - virtual machine image and base operating system :runs-on: virtual machine image and base operating system
* ``runtime`` - name of the runtime environment if not running natively on the VM image :runtime: name of the runtime environment if not running natively on the VM image
* ``shell`` - name of the shell :shell: name of the shell
* ``pyicon`` - icon for CPython or pypy :pyicon: icon for CPython or pypy
* ``python`` - Python version :python: Python version
* ``envname`` - full name of the selected environment :envname: full name of the selected environment
:Example: :Example:
.. code-block:: yaml .. 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" } {"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: .. _JOBTMPL/Parameters/Optimizations:

306
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 .. code-block:: yaml
name: Pipeline
on:
push:
workflow_dispatch:
jobs: jobs:
ConfigParams: ConfigParams:
uses: pyTooling/Actions/.github/workflows/ExtractConfiguration.yml@r5 uses: pyTooling/Actions/.github/workflows/ExtractConfiguration.yml@r5
with:
package_name: myPackage
UnitTestingParams: UnitTestingParams:
uses: pyTooling/Actions/.github/workflows/Parameters.yml@r5 uses: pyTooling/Actions/.github/workflows/Parameters.yml@r5
@@ -101,26 +93,11 @@ the :ref:`JOBTMPL/ExtractConfiguration` job template is used to extract these se
- UnitTestingParams - UnitTestingParams
with: with:
jobs: ${{ needs.UnitTestingParams.outputs.python_jobs }} jobs: ${{ needs.UnitTestingParams.outputs.python_jobs }}
requirements: "-r tests/unit/requirements.txt" requirements: '-r tests/unit/requirements.txt'
unittest_report_xml_directory: ${{ needs.ConfigParams.outputs.unittest_report_xml_directory }} unittest_report_xml: ${{ needs.ConfigParams.outputs.unittest_report_xml }}
unittest_report_xml_filename: ${{ needs.ConfigParams.outputs.unittest_report_xml_filename }}
unittest_xml_artifact: ${{ fromJson(needs.UnitTestingParams.outputs.artifact_names).unittesting_xml }} unittest_xml_artifact: ${{ fromJson(needs.UnitTestingParams.outputs.artifact_names).unittesting_xml }}
coverage_sqlite_artifact: ${{ fromJson(needs.UnitTestingParams.outputs.artifact_names).codecoverage_sqlite }} 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 }}
.. seealso:: .. seealso::
@@ -138,67 +115,69 @@ the :ref:`JOBTMPL/ExtractConfiguration` job template is used to extract these se
Parameter Summary 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>` .. rubric:: Goto :ref:`input parameters <JOBTMPL/UnitTesting/Inputs>`
+-------------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ +-------------------------------------------------------------------------+----------+----------+-----------------------------------------------------------------------------------------------------------------------------------+
| Parameter Name | Required | Type | Default | | Parameter Name | Required | Type | Default |
+=========================================================================+==========+==========+===================================================================+ +=========================================================================+==========+==========+===================================================================================================================================+
| :ref:`JOBTMPL/UnitTesting/Input/jobs` | yes | string | — — — — | | :ref:`JOBTMPL/UnitTesting/Input/jobs` | yes | string | — — — — |
+-------------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ +-------------------------------------------------------------------------+----------+----------+-----------------------------------------------------------------------------------------------------------------------------------+
| :ref:`JOBTMPL/UnitTesting/Input/apt` | no | string | ``''`` | | :ref:`JOBTMPL/UnitTesting/Input/apt` | no | string | ``''`` |
+-------------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ +-------------------------------------------------------------------------+----------+----------+-----------------------------------------------------------------------------------------------------------------------------------+
| :ref:`JOBTMPL/UnitTesting/Input/brew` | no | string | ``''`` | | :ref:`JOBTMPL/UnitTesting/Input/brew` | no | string | ``''`` |
+-------------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ +-------------------------------------------------------------------------+----------+----------+-----------------------------------------------------------------------------------------------------------------------------------+
| :ref:`JOBTMPL/UnitTesting/Input/pacboy` | no | string | ``''`` | | :ref:`JOBTMPL/UnitTesting/Input/pacboy` | no | string | ``''`` |
+-------------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ +-------------------------------------------------------------------------+----------+----------+-----------------------------------------------------------------------------------------------------------------------------------+
| :ref:`JOBTMPL/UnitTesting/Input/requirements` | no | string | ``'-r tests/requirements.txt'`` | | :ref:`JOBTMPL/UnitTesting/Input/requirements` | no | string | ``'-r tests/requirements.txt'`` |
+-------------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ +-------------------------------------------------------------------------+----------+----------+-----------------------------------------------------------------------------------------------------------------------------------+
| :ref:`JOBTMPL/UnitTesting/Input/mingw_requirements` | no | string | ``''`` | | :ref:`JOBTMPL/UnitTesting/Input/mingw_requirements` | no | string | ``''`` |
+-------------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ +-------------------------------------------------------------------------+----------+----------+-----------------------------------------------------------------------------------------------------------------------------------+
| :ref:`JOBTMPL/UnitTesting/Input/macos_before_script` | 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/macos_arm_before_script` | no | string | ``''`` |
+-------------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ +-------------------------------------------------------------------------+----------+----------+-----------------------------------------------------------------------------------------------------------------------------------+
| :ref:`JOBTMPL/UnitTesting/Input/ubuntu_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/mingw64_before_script` | no | string | ``''`` |
+-------------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ +-------------------------------------------------------------------------+----------+----------+-----------------------------------------------------------------------------------------------------------------------------------+
| :ref:`JOBTMPL/UnitTesting/Input/ucrt64_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/root_directory` | no | string | ``''`` |
+-------------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ +-------------------------------------------------------------------------+----------+----------+-----------------------------------------------------------------------------------------------------------------------------------+
| :ref:`JOBTMPL/UnitTesting/Input/tests_directory` | no | string | ``'tests'`` | | :ref:`JOBTMPL/UnitTesting/Input/tests_directory` | no | string | ``'tests'`` |
+-------------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ +-------------------------------------------------------------------------+----------+----------+-----------------------------------------------------------------------------------------------------------------------------------+
| :ref:`JOBTMPL/UnitTesting/Input/unittest_directory` | no | string | ``'unit'`` | | :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` | no | string | :jsoncode:`{"directory": "report/unit", "filename": "TestReportSummary.xml", "fullpath": "report/unit/TestReportSummary.xml"}` |
+-------------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ +-------------------------------------------------------------------------+----------+----------+-----------------------------------------------------------------------------------------------------------------------------------+
| :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_config` | no | string | ``'pyproject.toml'`` |
+-------------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ +-------------------------------------------------------------------------+----------+----------+-----------------------------------------------------------------------------------------------------------------------------------+
| :ref:`JOBTMPL/UnitTesting/Input/coverage_report_xml_directory` | no | string | ``'report/coverage'`` | | :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_xml_filename` | no | string | ``'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_json_directory` | no | string | ``'report/coverage'`` | | :ref:`JOBTMPL/UnitTesting/Input/coverage_report_html` | no | string | :jsoncode:`{"directory": "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_xml_artifact` | no | string | ``''`` |
+-------------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ +-------------------------------------------------------------------------+----------+----------+-----------------------------------------------------------------------------------------------------------------------------------+
| :ref:`JOBTMPL/UnitTesting/Input/unittest_html_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_sqlite_artifact` | no | string | ``''`` |
+-------------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ +-------------------------------------------------------------------------+----------+----------+-----------------------------------------------------------------------------------------------------------------------------------+
| :ref:`JOBTMPL/UnitTesting/Input/coverage_xml_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_json_artifact` | no | string | ``''`` |
+-------------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ +-------------------------------------------------------------------------+----------+----------+-----------------------------------------------------------------------------------------------------------------------------------+
| :ref:`JOBTMPL/UnitTesting/Input/coverage_html_artifact` | no | string | ``''`` | | :ref:`JOBTMPL/UnitTesting/Input/coverage_html_artifact` | no | string | ``''`` |
+-------------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ +-------------------------------------------------------------------------+----------+----------+-----------------------------------------------------------------------------------------------------------------------------------+
.. rubric:: Goto :ref:`secrets <JOBTMPL/UnitTesting/Secrets>` .. rubric:: Goto :ref:`secrets <JOBTMPL/UnitTesting/Secrets>`
@@ -224,14 +203,14 @@ jobs
:Default Value: — — — — :Default Value: — — — —
:Possible Values: A JSON string with an array of dictionaries with the following key-value pairs: :Possible Values: A JSON string with an array of dictionaries with the following key-value pairs:
* ``sysicon`` - icon to display :sysicon: icon to display
* ``system`` - name of the system :system: name of the system
* ``runs-on`` - virtual machine image and base operating system :runs-on: virtual machine image and base operating system
* ``runtime`` - name of the runtime environment if not running natively on the VM image :runtime: name of the runtime environment if not running natively on the VM image
* ``shell`` - name of the shell :shell: name of the shell
* ``pyicon`` - icon for CPython or pypy :pyicon: icon for CPython or pypy
* ``python`` - Python version :python: Python version
* ``envname`` - full name of the selected environment :envname: full name of the selected environment
:Description: A JSON encoded job matrix to run multiple Python job variations. :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`). :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 :Required: no
:Default Value: ``'report/unit'`` :Default Value:
:Possible Values: Any valid directory or sub-directory. .. code-block:: json
: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`.
{ "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 UnitTesting:
:Required: no uses: pyTooling/Actions/.github/workflows/UnitTesting.yml@r5
:Default Value: ``'TestReportSummary.xml'`` needs:
:Possible Values: Any valid filename accepted by ``pytest ... --junitxml=${unittest_report_xml_filename}``. - ConfigParams
:Description: Filename of the generated JUnit XML report. |br| with:
This filename is configured in :file:`pyproject.toml` and can be extracted by :ref:`JOBTMPL/ExtractConfiguration`. ...
unittest_report_xml: ${{ needs.ConfigParams.outputs.unittest_report_xml }}
.. _JOBTMPL/UnitTesting/Input/coverage_config: .. _JOBTMPL/UnitTesting/Input/coverage_config:
@@ -543,69 +535,117 @@ coverage_config
:Possible Values: TBD :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 :Required: no
:Default Value: ``'report/coverage'`` :Default Value:
:Possible Values: Any valid directory or sub-directory. .. code-block:: json
: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`. { "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 :Required: no
:Default Value: ``'coverage.xml'`` :Default Value:
:Possible Values: Any valid XML filename. .. code-block:: json
: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`. { "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 :Required: no
:Default Value: ``'report/coverage'`` :Default Value:
:Possible Values: Any valid directory or sub-directory. .. code-block:: json
: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`.
{ "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 UnitTesting:
:Required: no uses: pyTooling/Actions/.github/workflows/UnitTesting.yml@r5
:Default Value: ``'coverage.json'`` needs:
:Possible Values: Any valid JSON filename. - ConfigParams
:Description: Filename of the generated code coverage report in Coverage.py JSON format. |br| with:
This filename is configured in :file:`pyproject.toml` and can be extracted by :ref:`JOBTMPL/ExtractConfiguration`. ...
coverage_report_html: ${{ needs.ConfigParams.outputs.coverage_report_html }}
.. _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`.
.. _JOBTMPL/UnitTesting/Input/unittest_xml_artifact: .. _JOBTMPL/UnitTesting/Input/unittest_xml_artifact:

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

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

5
doc/conf.py
View File

@@ -35,6 +35,7 @@ sys_path.insert(0, abspath(f"../{directoryName}"))
packageInformationFile = Path(f"../{directoryName}/__init__.py") packageInformationFile = Path(f"../{directoryName}/__init__.py")
versionInformation = extractVersionInformation(packageInformationFile) versionInformation = extractVersionInformation(packageInformationFile)
project = f"{githubNamespace}/{githubProject}"
author = versionInformation.Author author = versionInformation.Author
copyright = versionInformation.Copyright copyright = versionInformation.Copyright
version = ".".join(versionInformation.Version.split(".")[:2]) # e.g. 2.3 The short X.Y version. 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 # Options for HTML output
# ============================================================================== # ==============================================================================
html_title = f"{githubNamespace}/{githubProject} v{versionInformation.Version}"
html_theme = "sphinx_rtd_theme" html_theme = "sphinx_rtd_theme"
html_theme_options = { html_theme_options = {
"logo_only": True, "logo_only": True,
@@ -191,6 +193,7 @@ extensions = [
# ============================================================================== # ==============================================================================
intersphinx_mapping = { 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 = { autoapi_modules = {
f"{pythonProject}": { f"{pythonProject}": {
"template": "package", "template": "module",
"output": pythonProject, "output": pythonProject,
"override": True "override": True
} }

3
doc/index.rst
View File

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

8
doc/prolog.inc
View File

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