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

Fine tuning documentation pages.

Browse Source
This commit is contained in:
Patrick Lehmann
2025-09-09 07:48:42 +02:00
parent f37f087334
commit 57f88b158f
27 changed files with 368 additions and 648 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
.github/workflows/CompletePipeline.yml vendored
View File

@@ -97,7 +97,7 @@ on:
description: 'Publish merged coverage and unittest reports to Codecov.'
required: false
default: 'false'
type: string
type: string
codacy:
description: 'Publish merged coverage report to Codacy.'
required: false

458
doc/JobTemplate/AllInOne/CompletePipeline.rst
View File

@@ -74,7 +74,218 @@ It can be used for simple Python packages as well as namespace packages.
.. topic:: Behavior
.. todo:: CompletePipeline:Behavior needs documentation.
1. Infer information from ``${{ github.ref }}`` variable.
2. Extract Python project settings from :file:`pyproject.toml`.
3. Compute job matrix based on system, Python version, environment, ... for job variants.
4. Run unit tests using pytest and collect code coverage.
5. Run platform tests using pytest and collect code coverage.
6. Run application tests using pytest.
7. Package code as wheel.
8. Check documentation coverage using docstr_coverage and interrogate.
9. Verify type annotation using static typing analysis using mypy.
10. Merge unit test results and code coverage results.
11. Generate HTML and LaTeX documentations using Sphinx.
12. Translate LaTeX documentation to PDF using MikTeX.
13. Publish unit test and code coverage results to cloud services.
14. Publish documentation to GitHub Pages.
15. Publish wheel to PyPI.
16. Create a GitHub release page and upload release assets.
.. topic:: Pipeline Graph
.. image:: ../../_static/pyTooling-Actions-SimplePackage.png
.. topic:: Dependencies
.. dropdown:: Expand List
:animate: fade-in-slide-down
:icon: codescan
:color: muted
.. grid:: 2
.. grid-item::
:columns: 6
* :ref:`pyTooling/Actions/.github/workflows/PrepareJob.yml <JOBTMPL/PrepareJob>`
* :gh:`actions/checkout`
* :gh:`GitHub command line tool 'gh' <cli/cli>`
* :ref:`pyTooling/Actions/.github/workflows/Parameters.yml <JOBTMPL/Parameters>`
* :ref:`pyTooling/Actions/.github/workflows/ExtractConfiguration.yml <JOBTMPL/ExtractConfiguration>`
* :gh:`actions/checkout`
* :gh:`actions/setup-python`
* :pypi:`wheel`
* :pypi:`tomli`
* :ref:`pyTooling/Actions/.github/workflows/UnitTesting.yml <JOBTMPL/UnitTesting>`
* :gh:`actions/checkout`
* :gh:`msys2/setup-msys2`
* :gh:`actions/setup-python`
* :gh:`pyTooling/download-artifact`
* :gh:`actions/download-artifact`
* :gh:`pyTooling/upload-artifact`
* :gh:`actions/upload-artifact`
* apt: Packages specified via :ref:`JOBTMPL/UnitTesting/Input/apt` parameter.
* homebrew: Packages specified via :ref:`JOBTMPL/UnitTesting/Input/brew` parameter.
* MSYS2: Packages specified via :ref:`JOBTMPL/UnitTesting/Input/pacboy` parameter.
* pip
* :pypi:`wheel`
* :pypi:`tomli`
* Python packages specified via :ref:`JOBTMPL/UnitTesting/Input/requirements` or
:ref:`JOBTMPL/UnitTesting/Input/mingw_requirements` parameter.
* :ref:`pyTooling/Actions/.github/workflows/ApplicationTesting.yml <JOBTMPL/ApplicationTesting>`
* :ref:`pyTooling/Actions/.github/workflows/CheckDocumentation.yml <JOBTMPL/CheckDocumentation>`
* :gh:`actions/checkout`
* :gh:`actions/setup-python`
* pip
* :pypi:`docstr_coverage`
* :pypi:`interrogate`
* :ref:`pyTooling/Actions/.github/workflows/StaticTypeCheck.yml <JOBTMPL/StaticTypeCheck>`
* :ref:`pyTooling/Actions/.github/workflows/Package.yml <JOBTMPL/Package>`
* :gh:`actions/checkout`
* :gh:`actions/setup-python`
* :gh:`pyTooling/upload-artifact`
* :gh:`actions/upload-artifact`
* pip
* :pypi:`build`
* :pypi:`wheel`
* :ref:`pyTooling/Actions/.github/workflows/PublishTestResults.yml <JOBTMPL/PublishTestResults>`
* :gh:`actions/checkout`
* :gh:`pyTooling/download-artifact`
* :gh:`actions/download-artifact`
* pip
* :pypi:`pyEDAA.Reports`
* :gh:`dorny/test-reporter`
* :gh:`codecov/test-results-action`
* :gh:`pyTooling/upload-artifact`
* :gh:`actions/upload-artifact`
.. grid-item::
:columns: 6
* :ref:`pyTooling/Actions/.github/workflows/PublishCoverageResults.yml <JOBTMPL/PublishCoverageResults>`
* :gh:`actions/checkout`
* :gh:`pyTooling/download-artifact`
* :gh:`actions/download-artifact`
* pip
* :pypi:`coverage`
* :pypi:`tomli`
* :gh:`pyTooling/upload-artifact`
* :gh:`actions/upload-artifact`
* :gh:`codecov/codecov-action`
* :gh:`codacy/codacy-coverage-reporter-action`
* :ref:`pyTooling/Actions/.github/workflows/SphinxDocumentation.yml <JOBTMPL/SphinxDocumentation>`
* :gh:`actions/checkout`
* :gh:`actions/setup-python`
* :gh:`pyTooling/download-artifact`
* :gh:`actions/download-artifact`
* :gh:`pyTooling/upload-artifact`
* :gh:`actions/upload-artifact`
* apt
* `graphviz <https://graphviz.org/>`__
* pip
* :pypi:`wheel`
* Python packages specified via :ref:`JOBTMPL/SphinxDocumentation/Input/requirements` parameter.
* :ref:`pyTooling/Actions/.github/workflows/LaTeXDocumentation.yml <JOBTMPL/LaTeXDocumentation>`
* :gh:`pyTooling/download-artifact`
* :gh:`actions/download-artifact`
* :gh:`pyTooling/upload-artifact`
* :gh:`actions/upload-artifact`
* :gh:`addnab/docker-run-action`
* :dockerhub:`pytooling/miktex <pytooling/miktex:sphinx>`
* :ref:`pyTooling/Actions/.github/workflows/PublishToGitHubPages.yml <JOBTMPL/PublishToGitHubPages>`
* :ref:`pyTooling/Actions/.github/workflows/PublishOnPyPI.yml <JOBTMPL/PublishOnPyPI>`
* :gh:`pyTooling/download-artifact`
* :gh:`actions/download-artifact`
* :gh:`actions/setup-python`
* :gh:`geekyeggo/delete-artifact`
* pip
* :pypi:`wheel`
* :pypi:`twine`
* :ref:`pyTooling/Actions/.github/workflows/TagReleaseCommit.yml <JOBTMPL/TagReleaseCommit>`
* :gh:`actions/github-script`
* :ref:`pyTooling/Actions/.github/workflows/PublishReleaseNotes.yml <JOBTMPL/PublishReleaseNotes>`
* :gh:`actions/checkout`
* ``gh`` (GitHub command line interface)
* ``jq`` (JSON processing)
* apt
* zstd
* :ref:`pyTooling/Actions/.github/workflows/IntermediateCleanUp.yml <JOBTMPL/IntermediateCleanUp>`
* :gh:`geekyeggo/delete-artifact`
* :ref:`pyTooling/Actions/.github/workflows/ArtifactCleanUp.yml <JOBTMPL/ArtifactCleanUp>`
* :gh:`geekyeggo/delete-artifact`
.. _JOBTMPL/CompletePipeline/Instantiation:
Instantiation
*************
The following instantiation example creates a ``SimplePackage`` job derived from job template ``CompletePipeline``
version ``@r5``. It only requires the `package_name` parameter to run a full pipeline suitable for a Python project.
.. grid:: 2
@@ -146,203 +357,6 @@ It can be used for simple Python packages as well as namespace packages.
🐍ModuleB.py
.. topic:: Pipeline Graph
.. image:: ../../_static/pyTooling-Actions-SimplePackage.png
.. topic:: Dependencies
* :ref:`pyTooling/Actions/.github/workflows/PrepareJob.yml <JOBTMPL/PrepareJob>`
* :gh:`actions/checkout`
* :gh:`GitHub command line tool 'gh' <cli/cli>`
* :ref:`pyTooling/Actions/.github/workflows/Parameters.yml <JOBTMPL/Parameters>`
* :ref:`pyTooling/Actions/.github/workflows/ExtractConfiguration.yml <JOBTMPL/ExtractConfiguration>`
* :gh:`actions/checkout`
* :gh:`actions/setup-python`
* :pypi:`wheel`
* :pypi:`tomli`
* :ref:`pyTooling/Actions/.github/workflows/UnitTesting.yml <JOBTMPL/UnitTesting>`
* :gh:`actions/checkout`
* :gh:`msys2/setup-msys2`
* :gh:`actions/setup-python`
* :gh:`pyTooling/download-artifact`
* :gh:`actions/download-artifact`
* :gh:`pyTooling/upload-artifact`
* :gh:`actions/upload-artifact`
* apt: Packages specified via :ref:`JOBTMPL/UnitTesting/Input/apt` parameter.
* homebrew: Packages specified via :ref:`JOBTMPL/UnitTesting/Input/brew` parameter.
* MSYS2: Packages specified via :ref:`JOBTMPL/UnitTesting/Input/pacboy` parameter.
* pip
* :pypi:`wheel`
* :pypi:`tomli`
* Python packages specified via :ref:`JOBTMPL/UnitTesting/Input/requirements` or
:ref:`JOBTMPL/UnitTesting/Input/mingw_requirements` parameter.
* :ref:`pyTooling/Actions/.github/workflows/ApplicationTesting.yml <JOBTMPL/ApplicationTesting>`
* :ref:`pyTooling/Actions/.github/workflows/CheckDocumentation.yml <JOBTMPL/CheckDocumentation>`
* :gh:`actions/checkout`
* :gh:`actions/setup-python`
* pip
* :pypi:`docstr_coverage`
* :pypi:`interrogate`
* :ref:`pyTooling/Actions/.github/workflows/StaticTypeCheck.yml <JOBTMPL/StaticTypeCheck>`
* :ref:`pyTooling/Actions/.github/workflows/Package.yml <JOBTMPL/Package>`
* :gh:`actions/checkout`
* :gh:`actions/setup-python`
* :gh:`pyTooling/upload-artifact`
* :gh:`actions/upload-artifact`
* pip
* :pypi:`build`
* :pypi:`wheel`
* :ref:`pyTooling/Actions/.github/workflows/PublishTestResults.yml <JOBTMPL/PublishTestResults>`
* :gh:`actions/checkout`
* :gh:`pyTooling/download-artifact`
* :gh:`actions/download-artifact`
* pip
* :pypi:`pyEDAA.Reports`
* :gh:`dorny/test-reporter`
* :gh:`codecov/test-results-action`
* :gh:`pyTooling/upload-artifact`
* :gh:`actions/upload-artifact`
* :ref:`pyTooling/Actions/.github/workflows/PublishCoverageResults.yml <JOBTMPL/PublishCoverageResults>`
* :gh:`actions/checkout`
* :gh:`pyTooling/download-artifact`
* :gh:`actions/download-artifact`
* pip
* :pypi:`coverage`
* :pypi:`tomli`
* :gh:`pyTooling/upload-artifact`
* :gh:`actions/upload-artifact`
* :gh:`codecov/codecov-action`
* :gh:`codacy/codacy-coverage-reporter-action`
* :ref:`pyTooling/Actions/.github/workflows/SphinxDocumentation.yml <JOBTMPL/SphinxDocumentation>`
* :gh:`actions/checkout`
* :gh:`actions/setup-python`
* :gh:`pyTooling/download-artifact`
* :gh:`actions/download-artifact`
* :gh:`pyTooling/upload-artifact`
* :gh:`actions/upload-artifact`
* apt
* `graphviz <https://graphviz.org/>`__
* pip
* :pypi:`wheel`
* Python packages specified via :ref:`JOBTMPL/SphinxDocumentation/Input/requirements` parameter.
* :ref:`pyTooling/Actions/.github/workflows/LaTeXDocumentation.yml <JOBTMPL/LaTeXDocumentation>`
* :gh:`pyTooling/download-artifact`
* :gh:`actions/download-artifact`
* :gh:`pyTooling/upload-artifact`
* :gh:`actions/upload-artifact`
* :gh:`addnab/docker-run-action`
* :dockerhub:`pytooling/miktex <pytooling/miktex:sphinx>`
* :ref:`pyTooling/Actions/.github/workflows/PublishToGitHubPages.yml <JOBTMPL/PublishToGitHubPages>`
* :ref:`pyTooling/Actions/.github/workflows/PublishOnPyPI.yml <JOBTMPL/PublishOnPyPI>`
* :gh:`pyTooling/download-artifact`
* :gh:`actions/download-artifact`
* :gh:`actions/setup-python`
* :gh:`geekyeggo/delete-artifact`
* pip
* :pypi:`wheel`
* :pypi:`twine`
* :ref:`pyTooling/Actions/.github/workflows/TagReleaseCommit.yml <JOBTMPL/TagReleaseCommit>`
* :gh:`actions/github-script`
* :ref:`pyTooling/Actions/.github/workflows/PublishReleaseNotes.yml <JOBTMPL/PublishReleaseNotes>`
* :gh:`actions/checkout`
* ``gh`` (GitHub command line interface)
* ``jq`` (JSON processing)
* apt
zstd
* :ref:`pyTooling/Actions/.github/workflows/IntermediateCleanUp.yml <JOBTMPL/IntermediateCleanUp>`
* :gh:`geekyeggo/delete-artifact`
* :ref:`pyTooling/Actions/.github/workflows/ArtifactCleanUp.yml <JOBTMPL/ArtifactCleanUp>`
* :gh:`geekyeggo/delete-artifact`
.. _JOBTMPL/CompletePipeline/Instantiation:
Instantiation
*************
The following instantiation example creates a ``Params`` job derived from job template ``Parameters`` version ``@r5``.
It only requires a `name` parameter to create the artifact names.
.. code-block:: yaml
name: Pipeline
on:
push:
workflow_dispatch:
jobs:
Params:
uses: pyTooling/Actions/.github/workflows/CompletePipeline.yml@r5
with:
package_name: myPackage
.. _JOBTMPL/CompletePipeline/Parameters:
Parameter Summary
@@ -563,7 +577,10 @@ unittest_include_list
:Required: no
:Default Value: ``''``
:Possible Values: A space separated list of ``<system>:<python_version>`` tuples.
:Description:
:Description: List of space-separated ``<system>:<python_version>`` tuples to be included into the list of unittest
variants.
For more details see :ref:`JOBTMPL/Parameters/Input/include_list`.
.. _JOBTMPL/CompletePipeline/Input/unittest_exclude_list:
@@ -575,7 +592,10 @@ unittest_exclude_list
:Required: no
:Default Value: ``'windows-arm:3.9 windows-arm:3.10'``
:Possible Values: A space separated list of ``<system>:<python_version>`` tuples.
:Description:
:Description: List of space-separated ``<system>:<python_version>`` tuples to be excluded from the list of unittest
variants.
For more details see :ref:`JOBTMPL/Parameters/Input/exclude_list`.
.. _JOBTMPL/CompletePipeline/Input/unittest_disable_list:
@@ -587,7 +607,11 @@ unittest_disable_list
:Required: no
:Default Value: ``'windows-arm:pypy-3.10 windows-arm:pypy-3.11'``
:Possible Values: A space separated list of ``<system>:<python_version>`` tuples.
:Description:
:Description: List of space-separated ``<system>:<python_version>`` tuples to be temporarily disabled from the list
of unittest variants. |br|
Each disabled item creates a warning in the workflow log.
For more details see :ref:`JOBTMPL/Parameters/Input/disable_list`.
.. _JOBTMPL/CompletePipeline/Input/apptest_python_version:
@@ -649,7 +673,10 @@ apptest_include_list
:Required: no
:Default Value: ``''``
:Possible Values: A space separated list of ``<system>:<python_version>`` tuples.
:Description:
:Description: List of space-separated ``<system>:<python_version>`` tuples to be included into the list of
application test variants.
For more details see :ref:`JOBTMPL/Parameters/Input/include_list`.
.. _JOBTMPL/CompletePipeline/Input/apptest_exclude_list:
@@ -661,7 +688,10 @@ apptest_exclude_list
:Required: no
:Default Value: ``'windows-arm:3.9 windows-arm:3.10'``
:Possible Values: A space separated list of ``<system>:<python_version>`` tuples.
:Description:
:Description: List of space-separated ``<system>:<python_version>`` tuples to be excluded from the list of
appliation test variants.
For more details see :ref:`JOBTMPL/Parameters/Input/exclude_list`.
.. _JOBTMPL/CompletePipeline/Input/apptest_disable_list:
@@ -673,7 +703,11 @@ apptest_disable_list
:Required: no
:Default Value: ``'windows-arm:pypy-3.10 windows-arm:pypy-3.11'``
:Possible Values: A space separated list of ``<system>:<python_version>`` tuples.
:Description:
:Description: List of space-separated ``<system>:<python_version>`` tuples to be temporarily disabled from the list
of application test variants. |br|
Each disabled item creates a warning in the workflow log.
For more details see :ref:`JOBTMPL/Parameters/Input/disable_list`.
.. _JOBTMPL/CompletePipeline/Input/codecov:
@@ -685,7 +719,8 @@ codecov
:Required: no
:Default Value: ``'false'``
:Possible Values: ``'true'``, ``'false'``
:Description:
:Description: If *true*, publish merged code coverage results and a merged unit test summary to CodeCov. |br|
Secret :ref:`JOBTMPL/CompletePipeline/Secret/CODECOV_TOKEN` must be set.
.. _JOBTMPL/CompletePipeline/Input/codacy:
@@ -697,7 +732,8 @@ codacy
:Required: no
:Default Value: ``'false'``
:Possible Values: ``'true'``, ``'false'``
:Description:
:Description: If *true*, publish merged code coverage results to Codacy. |br|
Secret :ref:`JOBTMPL/CompletePipeline/Secret/CODACY_TOKEN` must be set.
.. _JOBTMPL/CompletePipeline/Input/dorny:
@@ -709,7 +745,7 @@ dorny
:Required: no
:Default Value: ``'false'``
:Possible Values: ``'true'``, ``'false'``
:Description:
:Description: If *true*, publish a merged unit test summary as pipeline result.
.. _JOBTMPL/CompletePipeline/Input/cleanup:
@@ -721,7 +757,8 @@ cleanup
:Required: no
:Default Value: ``'true'``
:Possible Values: ``'true'``, ``'false'``
:Description:
:Description: If *false*, do not remove intermediate artifacts. |br|
This might help debugging artifact handovers between jobs.
.. _JOBTMPL/CompletePipeline/Secrets:
@@ -780,5 +817,6 @@ Optimizations
The following optimizations can be used to reduce the template's runtime.
TBD
tbd tbd tbd
.. todo::
CompletePipeline::Optimizations Needs a list of optimizations.

3
doc/JobTemplate/Cleanup/IntermediateCleanup.rst
View File

@@ -51,7 +51,8 @@ requires a `name` parameter to create the artifact names.
.. seealso::
:ref:`JOBTMPL/ArtifactCleanup`
``ArtifactCleanup`` is usualy
``ArtifactCleanup`` is used to remove artifacts like unit test report artifacts after artifact's content has been
(post-)processed or published.
.. _JOBTMPL/IntermediateCleanUp/Parameters:

71
doc/JobTemplate/Deprecated/BuildTheDocs.rst
View File

@@ -3,73 +3,8 @@
BuildTheDocs
############
This jobs compiles the documentation written in ReStructured Text with Sphinx using BuildTheDocs.
.. attention::
**Behavior:**
The ``BuildTheDocs`` job template is deprecated.
1. Checkout repository.
2. Build the documentation.
3. Upload the HTML documentation as an artifact.
4. Publish the HTML documentation to GitHub Pages.
**Dependencies:**
* :gh:`actions/checkout`
* :gh:`buildthedocs/btd`
* :gh:`actions/upload-artifact`
Instantiation
*************
Simple Example
==============
.. code-block:: yaml
jobs:
BuildTheDocs:
uses: pyTooling/Actions/.github/workflows/BuildTheDocs.yml@r5
Complex Example
===============
.. code-block:: yaml
jobs:
BuildTheDocs:
uses: pyTooling/Actions/.github/workflows/BuildTheDocs.yml@r5
needs:
- Params
with:
artifact: ${{ fromJson(needs.Params.outputs.artifact_names).documentation_html }}
Parameters
**********
artifact
========
+----------------+----------+----------+--------------+
| Parameter Name | Required | Type | Default |
+================+==========+==========+==============+
| artifact | optional | string | ``""`` |
+----------------+----------+----------+--------------+
Name of the documentation artifact.
If no artifact name is given, the job directly publishes the documentation's HTML content to GitHub Pages.
Secrets
*******
This job template needs no secrets.
Results
*******
This job template has no output parameters.
See :ref:`JOBTMPL/SphinxDocumentation` and :ref:`JOBTMPL/LaTeXDocumentation`.

164
doc/JobTemplate/Deprecated/CoverageCollection.rst
View File

@@ -3,166 +3,8 @@
CoverageCollection
##################
This jobs runs the specified unit tests with activated code coverage collection (incl. branch coverage).
.. attention::
It uses pytest, pytest-cov and coverage.py in a single job run, thus it uses one fixed Python version (usually latest).
It generates HTML and Cobertura reports (XML), then it uploads the HTML report as an artifact and the jUnit test results
(XML) to `Codecov <https://about.codecov.io/>`__ and `Codacy <https://www.codacy.com/>`__.
The ``CoverageCollection`` job template is deprecated.
Configuration options to ``pytest`` and ``coverage.py`` should be given via sections ``[tool.pytest.ini_options]`` and
``[tool.coverage.*]`` in a ``pyproject.toml`` file.
**Behavior:**
1. Checkout repository
2. Setup Python and install dependencies
3. Extract configuration from ``pyproject.toml`` or ``.coveragerc``.
4. Run unit tests and collect code coverage
5. Convert coverage data to a Cobertura XML file
6. Convert coverage data to a HTML report
7. Upload HTML report as an artifact
8. Publish Cobertura file to CodeCov
9. Publish Cobertura file to Codacy
**Preconditions:**
* A CodeCov account was created.
* A Codacy account was created.
**Requirements:**
Setup a secret (e.g. ``codacy_token``) in GitHub to handover the Codacy project token to the job.
**Dependencies:**
* :gh:`actions/checkout`
* :gh:`actions/setup-python`
* :gh:`actions/upload-artifact`
* :gh:`codecov/codecov-action`
* :gh:`codacy/codacy-coverage-reporter-action`
Instantiation
*************
Simple Example
==============
.. code-block:: yaml
jobs:
Coverage:
uses: pyTooling/Actions/.github/workflows/CoverageCollection.yml@r5
with:
artifact: Coverage
secrets: inherit
Complex Example
===============
.. code-block:: yaml
jobs:
Coverage:
uses: pyTooling/Actions/.github/workflows/CoverageCollection.yml@r5
needs:
- Params
with:
python_version: ${{ needs.Params.outputs.python_version }}
artifact: ${{ fromJson(needs.Params.outputs.artifact_names).codecoverage_html }}
secrets: inherit
Parameters
**********
python_version
==============
+----------------+----------+----------+----------+
| Parameter Name | Required | Type | Default |
+================+==========+==========+==========+
| python_version | optional | string | 3.11 |
+----------------+----------+----------+----------+
Python version used for running unit tests.
requirements
============
+----------------+----------+----------+-------------------------------+
| Parameter Name | Required | Type | Default |
+================+==========+==========+===============================+
| requirements | optional | string | ``-r tests/requirements.txt`` |
+----------------+----------+----------+-------------------------------+
Python dependencies to be installed through pip.
tests_directory
===============
+-----------------+----------+----------+-----------+
| Parameter Name | Required | Type | Default |
+=================+==========+==========+===========+
| tests_directory | optional | string | ``tests`` |
+-----------------+----------+----------+-----------+
Path to the directory containing tests (test working directory).
unittest_directory
==================
+--------------------+----------+----------+-----------+
| Parameter Name | Required | Type | Default |
+====================+==========+==========+===========+
| unittest_directory | optional | string | ``unit`` |
+--------------------+----------+----------+-----------+
Path to the directory containing unit tests (relative to tests_directory).
coverage_config
===============
+-----------------+----------+----------+--------------------+
| Parameter Name | Required | Type | Default |
+=================+==========+==========+====================+
| coverage_config | optional | string | ``pyproject.toml`` |
+-----------------+----------+----------+--------------------+
Path to the ``.coveragerc`` file. Use ``pyproject.toml`` by default.
artifact
========
+----------------+----------+----------+--------------+
| Parameter Name | Required | Type | Default |
+================+==========+==========+==============+
| artifact | yes | string | — — — — |
+----------------+----------+----------+--------------+
Name of the coverage artifact.
Secrets
*******
codacy_token
============
+----------------+----------+----------+--------------+
| Secret Name | Required | Type | Default |
+================+==========+==========+==============+
| codacy_token | yes | string | — — — — |
+----------------+----------+----------+--------------+
Token to push result to codacy.
Results
*******
This job template has no output parameters.
See :ref:`JOBTMPL/UnitTesting` and :ref:`JOBTMPL/PublishCoverageResults`.

18
doc/JobTemplate/Deprecated/NightlyRelease.rst
View File

@@ -3,20 +3,8 @@
NightlyRelease
##############
.. todo:: NightlyRelease:Needs documentation.
.. attention::
**Behavior:**
The ``NightlyRelease`` job template is deprecated.
.. todo:: NightlyRelease:Behavior needs documentation.
**Dependencies:**
.. todo:: NightlyRelease:Dependencies needs documentation.
Instantiation
*************
Simple Example
==============
.. todo:: NightlyRelease:Simple example needs documentation.
See :ref:`JOBTMPL/PublishReleaseNotes`.

23
doc/JobTemplate/Documentation/LaTeXDocumentation.rst
View File

@@ -3,9 +3,11 @@
LatexDocumentation
##################
The ``LatexDocumentation`` job template ................
The ``LatexDocumentation`` job template downloads an artifact containing a LaTeX document and translates to a PDF file
using MikTeX.
* uses xelatex and latexmk
The translation process uses ``latexmk`` for handling multiple passes. The default LaTeX processor is ``xelatex``, but
can be switched by a parameter.
.. topic:: Features
@@ -13,12 +15,9 @@ The ``LatexDocumentation`` job template ................
.. topic:: Behavior
.. todo:: LatexDocumentation:Behavior needs documentation.
.. topic:: Job Execution
.. image:: ../../_static/pyTooling-Actions-LatexDocumentation.png
:width: 600px
1. Download the LaTeX artifact.
2. Build the PDF using ``latexmk``.
3. Upload the generated PDF as an artifact.
.. topic:: Dependencies
@@ -40,9 +39,6 @@ The ``LatexDocumentation`` job template ................
Instantiation
*************
The following instantiation example creates a ``Params`` job derived from job template ``Parameters`` version ``@r5``. It only
requires a `name` parameter to create the artifact names.
.. code-block:: yaml
name: Pipeline
@@ -77,11 +73,6 @@ requires a `name` parameter to create the artifact names.
pdf_artifact: ${{ fromJson(needs.UnitTestingParams.outputs.artifact_names).documentation_pdf }}
.. seealso::
:ref:`JOBTMPL/TagReleaseCommit`
``LatexDocumentation`` is usualy
.. _JOBTMPL/LatexDocumentation/Parameters:
Parameter Summary

0
doc/JobTemplate/Publish/PublishToGitHubPages.rst → doc/JobTemplate/Documentation/PublishToGitHubPages.rst
View File

23
doc/JobTemplate/Documentation/SphinxDocumentation.rst
View File

@@ -3,7 +3,8 @@
SphinxDocumentation
###################
The ``SphinxDocumentation`` job template ..........
The ``SphinxDocumentation`` job template compiles the ReStructured Text documentation using Sphinx to an HTML website
and a LaTeX documentation. This LaTeX document can be translated using e.g. MikTeX to a PDF file.
.. topic:: Features
@@ -20,7 +21,17 @@ The ``SphinxDocumentation`` job template ..........
.. topic:: Behavior
.. todo:: SphinxDocumentation:Behavior needs documentation.
1. Checkout repository.
2. Install system dependencies.
3. Setup Python environment and install Python dependencies.
4. Download optional artifacts for integration of futher reports into the documentation.
5. Build the HTML documentation using Sphinx.
6. Build the LaTeX documentation using Sphinx.
1. Apply LaTeX workaround I.
2. Apply LaTeX workaround II.
7. Upload the HTML and LaTeX artifacts.
.. topic:: Job Execution
@@ -54,9 +65,6 @@ The ``SphinxDocumentation`` job template ..........
Instantiation
*************
The following instantiation example creates a ``Params`` job derived from job template ``Parameters`` version ``@r5``. It only
requires a `name` parameter to create the artifact names.
.. code-block:: yaml
name: Pipeline
@@ -81,11 +89,6 @@ requires a `name` parameter to create the artifact names.
latex_artifact: ${{ fromJson(needs.UnitTestingParams.outputs.artifact_names).documentation_latex }}
.. seealso::
:ref:`JOBTMPL/TagReleaseCommit`
``SphinxDocumentation`` is usualy
.. _JOBTMPL/SphinxDocumentation/Parameters:
Parameter Summary

42
doc/JobTemplate/Documentation/VerifyDocs.rst
View File

@@ -1,42 +0,0 @@
.. _JOBTMPL/VerifyDocs:
VerifyDocs
##########
This job extracts code examples from the README and tests these code snippets.
**Behavior:**
TBD
**Dependencies:**
TBD
Instantiation
*************
Simple Example
==============
.. todo:: VerifyDocs:SimpleExample Needs documentation.
Complex Example
===============
.. todo:: VerifyDocs:ComplexExample Needs documentation.
Parameters
**********
.. todo:: VerifyDocs:Parameters Needs documentation.
Secrets
*******
This job template needs no secrets.
Results
*******
This job template has no output parameters.

8
doc/JobTemplate/Documentation/index.rst
View File

@@ -5,13 +5,13 @@ Documentation
The category *documentation* provides workflow templates implementing
* :ref:`JOBTMPL/VerifyDocs` -
* :ref:`JOBTMPL/SphinxDocumentation` -
* :ref:`JOBTMPL/LaTeXDocumentation` -
* :ref:`JOBTMPL/SphinxDocumentation` - Translate ReStructured Text to HTML and LaTeX using Sphinx.
* :ref:`JOBTMPL/LaTeXDocumentation` - Translate LaTeX to PDF using MikTeX.
* :ref:`JOBTMPL/PublishToGitHubPages` - Upload HTML content to GitHub Pages.
.. toctree::
:hidden:
VerifyDocs
SphinxDocumentation
LaTeXDocumentation
PublishToGitHubPages

36
doc/JobTemplate/Package/InstallPackage.rst
View File

@@ -42,28 +42,9 @@ the installation is verified. This aims for packaging and dependency mistakes in
Instantiation
*************
The following instantiation example creates a ``Params`` job derived from job template ``Parameters`` version ``@r5``. It only
requires a `name` parameter to create the artifact names.
.. todo::
.. code-block:: yaml
name: Pipeline
on:
push:
workflow_dispatch:
jobs:
Params:
uses: pyTooling/Actions/.github/workflows/ExtractConfiguration.yml@r5
with:
name: pyTooling
.. seealso::
:ref:`JOBTMPL/Package`
``InstallPackage`` is usualy
InstallPackage:: Needs instantiation instructions.
.. _JOBTMPL/InstallPackage/Parameters:
@@ -73,11 +54,9 @@ Parameter Summary
.. rubric:: Goto :ref:`input parameters <JOBTMPL/InstallPackage/Inputs>`
+---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+
| Parameter Name | Required | Type | Default |
+=====================================================================+==========+==========+===================================================================+
| :ref:`JOBTMPL/InstallPackage/Input/ubuntu_image` | no | string | ``'ubuntu-24.04'`` |
+---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+
.. todo::
InstallPackage:: Needs a parameter list.
.. rubric:: Goto :ref:`secrets <JOBTMPL/InstallPackage/Secrets>`
@@ -93,10 +72,9 @@ This job template has no output parameters.
Input Parameters
****************
.. _JOBTMPL/InstallPackage/Input/ubuntu_image:
.. todo::
ubuntu_image
============
InstallPackage:: Needs input parameter descriptions.
.. _JOBTMPL/InstallPackage/Secrets:

6
doc/JobTemplate/Package/Package.rst
View File

@@ -24,7 +24,6 @@ as an artifact.
* If parameter :ref:`JOBTMPL/Package/Input/requirements` is non-empty, use :pypi:`setuptools` for package and
execute ``python setup.py ...``.
.. topic:: Job Execution
.. image:: ../../_static/pyTooling-Actions-Package.png
@@ -77,11 +76,6 @@ Complex Example
artifact: ${{ fromJson(needs.Params.outputs.artifact_names).package_all }}
.. seealso::
:ref:`JOBTMPL/PublishOnPyPI`
.. _JOBTMPL/Package/Parameters:
Parameter Summary

6
doc/JobTemplate/Package/index.rst
View File

@@ -5,9 +5,9 @@ Packaging
The category *packaging* provides workflow templates implementing
* :ref:`JOBTMPL/Package` -
* :ref:`JOBTMPL/InstallPackage` -
* :ref:`JOBTMPL/PublishOnPyPI` -
* :ref:`JOBTMPL/Package` - Package Python packages and modules as wheel.
* :ref:`JOBTMPL/InstallPackage` - Install Python package (wheel) on target platforms.
* :ref:`JOBTMPL/PublishOnPyPI` - Upload Python package (wheel) to PyPI.
.. toctree::
:hidden:

6
doc/JobTemplate/Publish/PublishCoverageResults.rst
View File

@@ -116,12 +116,6 @@ The following
CODACY_TOKEN: ${{ secrets.CODACY_TOKEN }}
.. seealso::
:ref:`JOBTMPL/UnitTesting`
``UnitTesting`` is usualy
.. _JOBTMPL/PublishCoverageResults/Parameters:
Parameter Summary

11
doc/JobTemplate/Publish/PublishTestResults.rst
View File

@@ -8,7 +8,7 @@ JUnit test summary reports to multiple services for visualization and longterm s
Supported services are:
* GitHub Actions - Job results using :gh:`dorny/test-reporter`
* GitHub Actions job results using :gh:`dorny/test-reporter`
* `Codecov <https://about.codecov.io/>`__
.. topic:: Features
@@ -99,13 +99,6 @@ Complex Example
- CodeCoverage
- UnitTesting
.. seealso::
:ref:`JOBTMPL/UnitTesting`
tbd
:ref:`JOBTMPL/PublishCoverageResults`
tbd
.. _JOBTMPL/PublishTestResults/Parameters:
@@ -343,5 +336,3 @@ Optimizations
*************
This template offers no optimizations (reduced job runtime).
merged_junit_artifact

2
doc/JobTemplate/Publish/index.rst
View File

@@ -7,11 +7,9 @@ The category *publish* provides workflow templates implementing
* :ref:`JOBTMPL/PublishTestResults` -
* :ref:`JOBTMPL/PublishCoverageResults` -
* :ref:`JOBTMPL/PublishToGitHubPages` -
.. toctree::
:hidden:
PublishTestResults
PublishCoverageResults
PublishToGitHubPages

6
doc/JobTemplate/Quality/VerifyDocs.rst Normal file
View File

@@ -0,0 +1,6 @@
.. _JOBTMPL/VerifyDocs:
VerifyDocs (idea)
#################
.. todo:: VerifyDocs:: Needs documentation.

6
doc/JobTemplate/Quality/index.rst
View File

@@ -5,11 +5,13 @@ Quality
The category *quality* provides workflow templates implementing
* :ref:`JOBTMPL/CheckDocumentation` -
* :ref:`JOBTMPL/StaticTypeCheck` -
* :ref:`JOBTMPL/VerifyDocs` - Verify code snippets in documentations for correctness.
* :ref:`JOBTMPL/CheckDocumentation` - Check documentation coverage in Python modules.
* :ref:`JOBTMPL/StaticTypeCheck` - Check type annotations using mypy.
.. toctree::
:hidden:
VerifyDocs
StaticTypeCheck
CheckDocumentation

5
doc/JobTemplate/Release/PublishReleaseNotes.rst
View File

@@ -75,11 +75,6 @@ Instantiation
tag: ${{ needs.Prepare.outputs.version }}
secrets: inherit
.. seealso::
:ref:`JOBTMPL/TagReleaseCommit`
``TagReleaseCommit`` is
.. _JOBTMPL/PublishReleaseNotes/ReleaseNotes:

7
doc/JobTemplate/Release/TagReleaseCommit.rst
View File

@@ -88,13 +88,6 @@ other reason. Its outputs are used to either run a ``TriggerTaggedRelease`` job
tag: ${{ needs.Prepare.outputs.version }}
secrets: inherit
.. seealso::
:ref:`JOBTMPL/PrepareJob`
``PrepareJob`` ...
:ref:`JOBTMPL/PublishReleaseNotes`
``PublishReleaseNotes`` ...
.. _JOBTMPL/TagReleaseCommit/Parameters:

4
doc/JobTemplate/Release/index.rst
View File

@@ -5,8 +5,8 @@ Release
The category *release* provides workflow templates implementing
* :ref:`JOBTMPL/TagReleaseCommit` -
* :ref:`JOBTMPL/PublishReleaseNotes` -
* :ref:`JOBTMPL/TagReleaseCommit` - Automatically tag current commit in Git using the associate pull-requests title.
* :ref:`JOBTMPL/PublishReleaseNotes` - Create GitHub release page and upload release assets.
.. toctree::
:hidden:

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

@@ -3,8 +3,9 @@
ExtractConfiguration
####################
The ``ExtractConfiguration`` job template is a .....
The ``ExtractConfiguration`` job template extracts Python project settings from :file:`pyproject.toml` and shares the
values via output parameters with other jobs. Thus, only a single centralized implementation is needed to avoid code
duplications within jobs.
.. topic:: Features
@@ -21,7 +22,14 @@ The ``ExtractConfiguration`` job template is a .....
.. topic:: Behavior
.. todo:: ExtractConfiguration:Behavior needs documentation.
1. Checkout repository.
2. Install Python dependencies.
3. Compute the full package name and the package source directory.
4. Read :file:`pyproject.toml` and extract settings for:
* pytest
* Coverage.py
* pyEDAA.Reports
.. topic:: Job Execution

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

@@ -6,14 +6,27 @@ Parameters
The ``Parameters`` job template is a workaround for the limitations of GitHub Actions to handle global variables in
GitHub Actions workflows (see `actions/runner#480 <https://github.com/actions/runner/issues/480>`__).
It generates output parameters with artifact names and a job matrix to be used in later running jobs.
It generates output parameters containing a list of artifact names and a job matrix to be used in later running jobs.
.. topic:: Features
* Generate names for various artifacts.
* Generate a matrix of job combinations made from systems, Python versions and environments as a JSON string.
* Generate artifact names for various artifacts.
* Generate a matrix of job combinations as a JSON string made from:
* systems (Ubuntu, macOS, Windows)
* architecture (x64-64, aarch64)
* Python versions (3.9, 3.10, ..., 3.13),
* Python implementation (CPython, PyPy), and
* environments (Native, MinGW64, UCRT64, ...).
* Provide a (default) Python version for other jobs.
.. topic:: Behavior
1. Delay job execution by :ref:`JOBTMPL/Parameters/Input/pipeline-delay` seconds.
2. Compute job matrix using an embedded Python script.
3. Assemble artifact names using a common prefix derived from Python namespace and package name.
.. topic:: Job Execution
.. image:: ../../_static/pyTooling-Actions-Parameters.png
@@ -430,8 +443,8 @@ disable_list
:Possible Values: A space separated list of ``<system>:<python_version>`` tuples.
:Description: List of space-separated ``<system>:<python_version>`` tuples to be temporarily disabled from the list
of test variants. |br|
Each disabled item creates a warning in the workflow log:
:Example:
Each disabled item creates a warning in the workflow log.
:Warning Example:
.. code-block:: yaml
jobs:

46
doc/JobTemplate/Setup/PrepareJob.rst
View File

@@ -13,7 +13,7 @@ The job template generates various output parameters derived from
.. topic:: Features
* Provide branch name or tag name from ``${{ github.ref }}`` variable.
* Check if pipeline is a branch or tag pipeline.
* Check if pipeline is a branch, tag or pull-request pipeline.
* Check if a commit is a merge commit.
* Check if a commit is a release commit.
* Check if a tag is a nightly tag (rolling release tag).
@@ -21,23 +21,30 @@ The job template generates various output parameters derived from
* Find associated pull-request (PR) for a merge commit/release commit.
* Provide a version from tag name or pull-request name.
.. note::
.. note::
Due to GitHub Action's broken type system and missing implicit type conversions in YAML files, *boolean* values need
to be returned as *string* values otherwise type compatibility and comparison are broken. This also requires all
inputs to be *string* parameters, otherwise step's, job's or template's output cannot be assigned to a template's
input.
Due to GitHub Action's broken type system and missing implicit type conversions in YAML files, *boolean* values need
to be returned as *string* values otherwise type compatibility and comparison are broken. This also requires all
inputs to be *string* parameters, otherwise step's, job's or template's output cannot be assigned to a template's
input.
**Problems:**
**Problems:**
1. Scripts (Bash, Python, ...) return results as strings. There is no option or operation provided by GitHub Actions
to convert outputs of ``printf`` to a ``boolean`` in the YAML file.
2. Unlike job template inputs, outputs have no type information. These are all considered *string* values. Again no
implicit or explicit type conversion is provided.
3. While inputs might be defined as ``boolean`` and a matching default can be set as a *boolean* value (e.g.,
``false``), a connected variable from ``${{ needs }}`` context will either cause a typing error or a later
comparison will not work as expected. Either the comparison works with ``inputs.param == false`` for the default
value, **or** it works with a value from ``${{ needs }}`` context, which is a string ``inputs.param == 'false'``.
1. Scripts (Bash, Python, ...) return results as strings. There is no option or operation provided by GitHub Actions
to convert outputs of ``printf`` to a ``boolean`` in the YAML file.
2. Unlike job template inputs, outputs have no type information. These are all considered *string* values. Again no
implicit or explicit type conversion is provided.
3. While inputs might be defined as ``boolean`` and a matching default can be set as a *boolean* value (e.g.,
``false``), a connected variable from ``${{ needs }}`` context will either cause a typing error or a later
comparison will not work as expected. Either the comparison works with ``inputs.param == false`` for the default
value, **or** it works with a value from ``${{ needs }}`` context, which is a string ``inputs.param == 'false'``.
.. topic:: Behavior
1. Checkout repository.
2. Classify ``${{ github.ref }}`` into branch, tag or pull-request.
3. Compute output parameters.
4. Find associated pull-request.
.. topic:: Job Execution
@@ -377,11 +384,12 @@ ref_kind
Moreover, if the tag matches the :ref:`JOBTMPL/PrepareJob/Input/release_tag_pattern`, the extracted
version is available in the job's :ref:`JOBTMPL/PrepareJob/Output/version` result.
.. note::
.. note::
GitHub doesn't provide standalone branch or tag information, but provides the variable ``${{ github.ref }}``
specifying the currently active reference (branch, tag, pull, ...). This job template parses the context's variable
and derives if a pipeline runs for a commit on a branch or a tagged commit.
GitHub doesn't provide standalone branch or tag information, but provides the variable
``${{ github.ref }}`` specifying the currently active reference (branch, tag, pull, ...). This job
template parses the context's variable and derives if a pipeline runs for a commit on a branch or a
tagged commit.
.. _JOBTMPL/PrepareJob/Output/branch:

22
doc/JobTemplate/Testing/ApplicationTesting.rst
View File

@@ -1,22 +1,6 @@
.. _JOBTMPL/ApplicationTesting:
ApplicationTesting
##################
ApplicationTesting (idea)
#########################
.. todo:: ApplicationTesting:Needs documentation.
**Behavior:**
.. todo:: ApplicationTesting:Behavior needs documentation.
**Dependencies:**
.. todo:: ApplicationTesting:Dependencies needs documentation.
Instantiation
*************
Simple Example
==============
.. todo:: ApplicationTesting:Simple example needs documentation.
.. todo:: ApplicationTesting:: Needs documentation.

4
doc/JobTemplate/Testing/index.rst
View File

@@ -5,8 +5,8 @@ Testing
The category *testing* provides workflow templates implementing
* :ref:`JOBTMPL/UnitTesting` -
* :ref:`JOBTMPL/ApplicationTesting` -
* :ref:`JOBTMPL/UnitTesting` - Run unit tests and collect code coverage.
* :ref:`JOBTMPL/ApplicationTesting` - Run application tests.
.. toctree::
:hidden: