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

Documented CompletePipeline.

Browse Source
This commit is contained in:
Patrick Lehmann
2025-08-20 12:25:48 +02:00
parent 4badbda8e7
commit 0f66b32418
17 changed files with 860 additions and 227 deletions
Download Patch File Download Diff File Expand all files Collapse all files

15
doc/Action/Actions.rst Normal file
View File

@@ -0,0 +1,15 @@
.. grid:: 2
.. grid-item::
:columns: 2
.. rubric:: Post-Processing
* :ref:`ACTION/WithPostStep`
.. grid-item::
:columns: 2
.. rubric:: Deprecated
* :ref:`ACTION/Releaser`

7
doc/Action/Releaser.rst
View File

@@ -3,6 +3,13 @@
Releaser
########
.. attention::
The **Releaser** action is deprecated.
Use the new GitHub Action workflow template :ref:`JOBTMPL/PublishReleaseNotes` as a replacement with lots of
additional features.
**Releaser** is a Docker GitHub Action written in Python.
**Releaser** allows to keep a GitHub Release of type pre-release and its artifacts up to date with latest builds.

24
doc/Action/index.rst
View File

@@ -1,7 +1,27 @@
.. _ACTION:
Overview
########
The following 2 actions are provided by **Actions**:
* :ref:`ACTION/Releaser`
* :ref:`ACTION/WithPostStep`
.. include:: Actions.rst
.. _ACTION/Instantiation:
Instantiation
*************
.. code-block:: yaml
jobs:
<JobName>:
steps:
- ...
- name: <Name>
uses: ./with-post-step
with:
<Param1>: <Value1>
<Param2>: <Value2>

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

@@ -3,18 +3,181 @@
CompletePipeline
################
The ``CompletePipeline`` 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>`__.
The ``CompletePipeline`` job template is the combination of almost all job templates offered by pyTooling/Actions in a
single workflow template. If fulfills all needs to test, package, document, publish and release Python code from GitHub.
It can be used for simple Python packages as well as namespace packages.
It generates output parameters with artifact names and a job matrix to be used in later running jobs.
.. topic:: Features
**Behavior:**
.. grid:: 3
.. todo:: Parameters:Behavior Needs documentation.
.. grid-item::
:columns: 4
**Dependencies:**
.. rubric:: Testing
*None*
* Run unit tests.
* Run platform tests.
* Run application tests on target platform.
.. rubric:: Code Quality
* Collect code coverage.
* Check documentation coverage.
* Check static typing closure.
.. rubric:: Report Handling
* Merge unit test results into a single summary report.
* Merge code coverage results into a single summary report.
.. grid-item::
:columns: 4
.. rubric:: Documentation
* Compile documentation using Sphinx as HTML and LaTeX.
* Translate LaTeX documentation to PDF.
.. rubric:: Publishing Results
* GitHub Pipeline Summary
* Publich unittest results using :gh:`dorny/test-reporter`.
* GitHub Pages
* Publish HTML documentation to GitHub Pages.
* Codacy
* Publish code coverage to Codacy.
* CodeCov
* Publish code coverage to CodeCov.
* Publish unittest results to CodeCov.
.. grid-item::
:columns: 4
.. rubric:: Packaging
* Package as wheel.
* Install wheel on target platform.
* Upload to PyPI.
.. rubric:: Releasing
* Automatic tagging of merge commits on main branch to trigger a tagged pipeline (release pipeline).
* Create a release page with text derived from pull request description.
.. topic:: Behavior:
.. todo:: CompletePipeline:Behavior needs documentation.
.. grid:: 2
.. grid-item::
:columns: 6
.. tab-set::
.. tab-item:: Simple Package
:sync: Simple
.. code-block:: yaml
name: Pipeline
jobs:
SimplePackage:
uses: pyTooling/Actions/.github/workflows/CompletePipeline.yml@r5
with:
package_name: myPackage
.. tab-item:: Namespace Package
:sync: Namespace
.. code-block:: yaml
name: Pipeline
jobs:
NamespacePackage:
uses: pyTooling/Actions/.github/workflows/CompletePipeline.yml@r5
with:
package_namespace: myFramework
package_name: Extension
.. grid-item::
:columns: 6
.. tab-set::
.. tab-item:: Simple Package
:sync: Simple
.. code-block::
📂ProjectRoot/
📂myFramework/
📦SubPackage/
🐍__init__.py
🐍SubModuleA.py
🐍__init__.py
🐍ModuleB.py
.. tab-item:: Namespace Package
:sync: Namespace
.. code-block::
📂ProjectRoot/
📂myFramework/
📂Extension/
📦SubPackage/
🐍__init__.py
🐍SubModuleA.py
🐍__init__.py
🐍ModuleB.py
.. topic:: Pipeline Graph
.. image:: ../../_static/pyTooling-Actions-SimplePackage.png
.. topic:: Dependencies
* :ref:`pyTooling/Actions/.github/workflows/PrepareJob.yml <JOBTMPL/PrepareJob>`
* :ref:`pyTooling/Actions/.github/workflows/Parameters.yml <JOBTMPL/Parameters>`
* :ref:`pyTooling/Actions/.github/workflows/ExtractConfiguration.yml <JOBTMPL/ExtractConfiguration>`
* :ref:`pyTooling/Actions/.github/workflows/UnitTesting.yml <JOBTMPL/UnitTesting>`
* :ref:`pyTooling/Actions/.github/workflows/ApplicationTesting.yml <JOBTMPL/ApplicationTesting>`
* :ref:`pyTooling/Actions/.github/workflows/CheckDocumentation.yml <JOBTMPL/CheckDocumentation>`
* :ref:`pyTooling/Actions/.github/workflows/StaticTypeCheck.yml <JOBTMPL/StaticTypeCheck>`
* :ref:`pyTooling/Actions/.github/workflows/Package.yml <JOBTMPL/Package>`
* :ref:`pyTooling/Actions/.github/workflows/PublishTestResults.yml <JOBTMPL/PublishTestResults>`
* :ref:`pyTooling/Actions/.github/workflows/PublishCoverageResults.yml <JOBTMPL/PublishCoverageResults>`
* :ref:`pyTooling/Actions/.github/workflows/SphinxDocumentation.yml <JOBTMPL/SphinxDocumentation>`
* :ref:`pyTooling/Actions/.github/workflows/LaTeXDocumentation.yml <JOBTMPL/LaTeXDocumentation>`
* :ref:`pyTooling/Actions/.github/workflows/PublishToGitHubPages.yml <JOBTMPL/PublishToGitHubPages>`
* :ref:`pyTooling/Actions/.github/workflows/PublishOnPyPI.yml <JOBTMPL/PublishOnPyPI>`
* :ref:`pyTooling/Actions/.github/workflows/TagReleaseCommit.yml <JOBTMPL/TagReleaseCommit>`
* :ref:`pyTooling/Actions/.github/workflows/PublishReleaseNotes.yml <JOBTMPL/PublishReleaseNotes>`
* :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
*************
@@ -38,3 +201,448 @@ requires a `name` parameter to create the artifact names.
uses: pyTooling/Actions/.github/workflows/CompletePipeline.yml@r5
with:
name: pyTooling
.. _JOBTMPL/CompletePipeline/Parameters:
Parameters
**********
.. topic:: Parameter Summary
+---------------------------------------------------------------------+----------+----------+----------------------------------------------+
| Parameter Name | Required | Type | Default |
+=====================================================================+==========+==========+==============================================+
| :ref:`JOBTMPL/CompletePipeline/Param/package_namespace` | no | string | ``''`` |
+---------------------------------------------------------------------+----------+----------+----------------------------------------------+
| :ref:`JOBTMPL/CompletePipeline/Param/package_name` | yes | string | — — — — |
+---------------------------------------------------------------------+----------+----------+----------------------------------------------+
| :ref:`JOBTMPL/CompletePipeline/Param/unittest_python_version` | no | string | ``'3.13'`` |
+---------------------------------------------------------------------+----------+----------+----------------------------------------------+
| :ref:`JOBTMPL/CompletePipeline/Param/unittest_python_version_list` | no | string | ``'3.9 3.10 3.11 3.12 3.13'`` |
+---------------------------------------------------------------------+----------+----------+----------------------------------------------+
| :ref:`JOBTMPL/CompletePipeline/Param/unittest_system_list` | no | string | ``'ubuntu windows macos macos-arm ucrt64'`` |
+---------------------------------------------------------------------+----------+----------+----------------------------------------------+
| :ref:`JOBTMPL/CompletePipeline/Param/unittest_include_list` | no | string | ``''`` |
+---------------------------------------------------------------------+----------+----------+----------------------------------------------+
| :ref:`JOBTMPL/CompletePipeline/Param/unittest_exclude_list` | no | string | ``''`` |
+---------------------------------------------------------------------+----------+----------+----------------------------------------------+
| :ref:`JOBTMPL/CompletePipeline/Param/unittest_disable_list` | no | string | ``''`` |
+---------------------------------------------------------------------+----------+----------+----------------------------------------------+
| :ref:`JOBTMPL/CompletePipeline/Param/apptest_python_version` | no | string | ``'3.13'`` |
+---------------------------------------------------------------------+----------+----------+----------------------------------------------+
| :ref:`JOBTMPL/CompletePipeline/Param/apptest_python_version_list` | no | string | ``''`` |
+---------------------------------------------------------------------+----------+----------+----------------------------------------------+
| :ref:`JOBTMPL/CompletePipeline/Param/apptest_system_list` | no | string | ``'ubuntu windows macos macos-arm ucrt64'`` |
+---------------------------------------------------------------------+----------+----------+----------------------------------------------+
| :ref:`JOBTMPL/CompletePipeline/Param/apptest_include_list` | no | string | ``''`` |
+---------------------------------------------------------------------+----------+----------+----------------------------------------------+
| :ref:`JOBTMPL/CompletePipeline/Param/apptest_exclude_list` | no | string | ``''`` |
+---------------------------------------------------------------------+----------+----------+----------------------------------------------+
| :ref:`JOBTMPL/CompletePipeline/Param/apptest_disable_list` | no | string | ``''`` |
+---------------------------------------------------------------------+----------+----------+----------------------------------------------+
| :ref:`JOBTMPL/CompletePipeline/Param/codecov` | no | string | ``'false'`` |
+---------------------------------------------------------------------+----------+----------+----------------------------------------------+
| :ref:`JOBTMPL/CompletePipeline/Param/codacy` | no | string | ``'false'`` |
+---------------------------------------------------------------------+----------+----------+----------------------------------------------+
| :ref:`JOBTMPL/CompletePipeline/Param/dorny` | no | string | ``'false'`` |
+---------------------------------------------------------------------+----------+----------+----------------------------------------------+
| :ref:`JOBTMPL/CompletePipeline/Param/cleanup` | no | string | ``'true'`` |
+---------------------------------------------------------------------+----------+----------+----------------------------------------------+
.. topic:: :ref:`Secret Summary <JOBTMPL/CompletePipeline/Secrets>`
+-----------------------------------------------------------+----------+----------+--------------+
| Token Name | Required | Type | Default |
+===========================================================+==========+==========+==============+
| :ref:`JOBTMPL/CompletePipeline/Secret/PYPI_TOKEN` | no | string | — — — — |
+-----------------------------------------------------------+----------+----------+--------------+
| :ref:`JOBTMPL/CompletePipeline/Secret/CODECOV_TOKEN` | no | string | — — — — |
+-----------------------------------------------------------+----------+----------+--------------+
| :ref:`JOBTMPL/CompletePipeline/Secret/CODACY_TOKEN` | no | string | — — — — |
+-----------------------------------------------------------+----------+----------+--------------+
.. topic:: :ref:`Output Summary <JOBTMPL/CompletePipeline/Results>`
This job template has no output parameters.
.. _JOBTMPL/CompletePipeline/Param/package_namespace:
package_namespace
=================
+-------------------------------+----------+----------+--------------+
| Parameter Name | Required | Type | Default |
+===============================+==========+==========+==============+
| package_namespace | no | string | ``''`` |
+-------------------------------+----------+----------+--------------+
In case the package is a Python namespace package, the name of the library's or package's namespace needs to be
specified using this parameter. |br|
In case of a simple Python package, this parameter must be specified as an empty string (``''``), which is the default.
.. grid:: 2
.. grid-item::
:columns: 4
.. rubric:: Example
.. code-block:: yaml
jobs:
NamespacePackage:
uses: pyTooling/Actions/.github/workflows/CompletePipeline.yml@r5
with:
package_namespace: myFramework
package_name: Extension
.. grid-item::
:columns: 4
.. rubric:: Example
.. code-block::
📂ProjectRoot/
📂myFramework/
📂Extension/
📦SubPackage/
🐍__init__.py
🐍SubModuleA.py
🐍__init__.py
🐍ModuleB.py
.. _JOBTMPL/CompletePipeline/Param/package_name:
package_name
============
+-------------------------------+----------+----------+--------------+
| Parameter Name | Required | Type | Default |
+===============================+==========+==========+==============+
| package_name | yes | string | — — — — |
+-------------------------------+----------+----------+--------------+
In case of a simple Python package, this package's name is specified using this parameter. |br|
In case the package is a Python namespace package, the parameter :ref:`JOBTMPL/CompletePipeline/Param/package_namespace`
must be specified, too.
.. rubric:: Example
.. grid:: 2
.. grid-item::
:columns: 4
.. rubric:: Example
.. code-block:: yaml
jobs:
SimplePackage:
uses: pyTooling/Actions/.github/workflows/CompletePipeline.yml@r5
with:
package_name: myPackage
.. grid-item::
:columns: 4
.. rubric:: Example
.. code-block::
📂ProjectRoot/
📂myFramework/
📦SubPackage/
🐍__init__.py
🐍SubModuleA.py
🐍__init__.py
🐍ModuleB.py
.. _JOBTMPL/CompletePipeline/Param/unittest_python_version:
unittest_python_version
=======================
+-------------------------------+----------+----------+--------------+
| Parameter Name | Required | Type | Default |
+===============================+==========+==========+==============+
| unittest_python_version | no | string | ``'3.13'`` |
+-------------------------------+----------+----------+--------------+
The default Python version used for intermediate jobs using Python tools.
In case :ref:`JOBTMPL/CompletePipeline/Param/unittest_python_version_list` is empty, this default version is used to
populate the ``unittest_python_version_list`` parameter.
.. _JOBTMPL/CompletePipeline/Param/unittest_python_version_list:
unittest_python_version_list
============================
+-------------------------------+----------+----------+-------------------------------------+
| Parameter Name | Required | Type | Default |
+===============================+==========+==========+=====================================+
| unittest_python_version_list | no | string | ``'3.9 3.10 3.11 3.12 3.13'`` |
+-------------------------------+----------+----------+-------------------------------------+
The list of space-separated Python versions used for unit testing.
.. include:: ../PythonVersionList.rst
.. _JOBTMPL/CompletePipeline/Param/unittest_system_list:
unittest_system_list
====================
+-------------------------------+----------+----------+-----------------------------------------------------+
| Parameter Name | Required | Type | Default |
+===============================+==========+==========+=====================================================+
| unittest_system_list | no | string | ``'ubuntu windows macos macos-arm mingw64 ucrt64'`` |
+-------------------------------+----------+----------+-----------------------------------------------------+
The list of space-separated systems used for unit testing.
.. include:: ../SystemList.rst
.. _JOBTMPL/CompletePipeline/Param/unittest_include_list:
unittest_include_list
=====================
+-------------------------------+----------+----------+--------------+
| Parameter Name | Required | Type | Default |
+===============================+==========+==========+==============+
| unittest_include_list | no | string | ``''`` |
+-------------------------------+----------+----------+--------------+
The name of the library or package.
.. _JOBTMPL/CompletePipeline/Param/unittest_exclude_list:
unittest_exclude_list
=====================
+-------------------------------+----------+----------+--------------+
| Parameter Name | Required | Type | Default |
+===============================+==========+==========+==============+
| unittest_exclude_list | no | string | ``''`` |
+-------------------------------+----------+----------+--------------+
The name of the library or package.
.. _JOBTMPL/CompletePipeline/Param/unittest_disable_list:
unittest_disable_list
=====================
+-------------------------------+----------+----------+--------------+
| Parameter Name | Required | Type | Default |
+===============================+==========+==========+==============+
| unittest_disable_list | no | string | ``''`` |
+-------------------------------+----------+----------+--------------+
The name of the library or package.
.. _JOBTMPL/CompletePipeline/Param/apptest_python_version:
apptest_python_version
======================
+-------------------------------+----------+----------+--------------+
| Parameter Name | Required | Type | Default |
+===============================+==========+==========+==============+
| apptest_python_version | no | string | ``'3.13'`` |
+-------------------------------+----------+----------+--------------+
The name of the library or package.
.. _JOBTMPL/CompletePipeline/Param/apptest_python_version_list:
apptest_python_version_list
===========================
+-------------------------------+----------+----------+--------------+
| Parameter Name | Required | Type | Default |
+===============================+==========+==========+==============+
| apptest_python_version_list | no | string | ``''`` |
+-------------------------------+----------+----------+--------------+
The name of the library or package.
.. _JOBTMPL/CompletePipeline/Param/apptest_system_list:
apptest_system_list
===================
+-------------------------------+----------+----------+--------------------------------------------------+
| Parameter Name | Required | Type | Default |
+===============================+==========+==========+==================================================+
| apptest_system_list | no | string | ``'ubuntu windows macos macos-arm ucrt64'`` |
+-------------------------------+----------+----------+--------------------------------------------------+
The name of the library or package.
.. _JOBTMPL/CompletePipeline/Param/apptest_include_list:
apptest_include_list
====================
+-------------------------------+----------+----------+--------------+
| Parameter Name | Required | Type | Default |
+===============================+==========+==========+==============+
| apptest_include_list | no | string | ``''`` |
+-------------------------------+----------+----------+--------------+
The name of the library or package.
.. _JOBTMPL/CompletePipeline/Param/apptest_exclude_list:
apptest_exclude_list
====================
+-------------------------------+----------+----------+--------------+
| Parameter Name | Required | Type | Default |
+===============================+==========+==========+==============+
| apptest_exclude_list | no | string | ``''`` |
+-------------------------------+----------+----------+--------------+
The name of the library or package.
.. _JOBTMPL/CompletePipeline/Param/apptest_disable_list:
apptest_disable_list
====================
+-------------------------------+----------+----------+--------------+
| Parameter Name | Required | Type | Default |
+===============================+==========+==========+==============+
| apptest_disable_list | no | string | ``''`` |
+-------------------------------+----------+----------+--------------+
The name of the library or package.
.. _JOBTMPL/CompletePipeline/Param/codecov:
codecov
=======
+-------------------------------+----------+----------+--------------+
| Parameter Name | Required | Type | Default |
+===============================+==========+==========+==============+
| codecov | no | string | ``'false'`` |
+-------------------------------+----------+----------+--------------+
The name of the library or package.
.. _JOBTMPL/CompletePipeline/Param/codacy:
codacy
======
+-------------------------------+----------+----------+--------------+
| Parameter Name | Required | Type | Default |
+===============================+==========+==========+==============+
| codacy | no | string | ``'false'`` |
+-------------------------------+----------+----------+--------------+
The name of the library or package.
.. _JOBTMPL/CompletePipeline/Param/dorny:
dorny
=====
+-------------------------------+----------+----------+--------------+
| Parameter Name | Required | Type | Default |
+===============================+==========+==========+==============+
| dorny | no | string | ``'false'`` |
+-------------------------------+----------+----------+--------------+
The name of the library or package.
.. _JOBTMPL/CompletePipeline/Param/cleanup:
cleanup
=======
+-------------------------------+----------+----------+--------------+
| Parameter Name | Required | Type | Default |
+===============================+==========+==========+==============+
| cleanup | no | string | ``'true'`` |
+-------------------------------+----------+----------+--------------+
The name of the library or package.
.. _JOBTMPL/CompletePipeline/Secrets:
Secrets
*******
The workflow template uses the following secrets to publish results to other services.
.. _JOBTMPL/CompletePipeline/Secret/PYPI_TOKEN:
PYPI_TOKEN
==========
+-------------------------------+----------+----------+--------------+
| Token Name | Required | Type | Default |
+===============================+==========+==========+==============+
| PYPI_TOKEN | no | string | — — — — |
+-------------------------------+----------+----------+--------------+
The name of the library or package.
.. _JOBTMPL/CompletePipeline/Secret/CODECOV_TOKEN:
CODECOV_TOKEN
=============
+-------------------------------+----------+----------+--------------+
| Token Name | Required | Type | Default |
+===============================+==========+==========+==============+
| CODECOV_TOKEN | no | string | — — — — |
+-------------------------------+----------+----------+--------------+
The name of the library or package.
.. _JOBTMPL/CompletePipeline/Secret/CODACY_TOKEN:
CODACY_TOKEN
============
+-------------------------------+----------+----------+--------------+
| Token Name | Required | Type | Default |
+===============================+==========+==========+==============+
| CODACY_TOKEN | no | string | — — — — |
+-------------------------------+----------+----------+--------------+
The name of the library or package.
.. _JOBTMPL/CompletePipeline/Results:
Results
*******
This job template has no output parameters.

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

@@ -11,7 +11,7 @@ IntermediateCleanUp
**Dependencies:**
.. todo:: IntermediateCleanUp:Dependencies needs documentation.
* :gh:`geekyeggo/delete-artifact`
Instantiation
*************

13
doc/JobTemplate/Global/ExtractConfiguration.rst
View File

@@ -38,3 +38,16 @@ requires a `name` parameter to create the artifact names.
uses: pyTooling/Actions/.github/workflows/ExtractConfiguration.yml@r5
with:
name: pyTooling
Parameters
**********
Secrets
*******
Results
*******

59
doc/JobTemplate/Global/Parameters.rst
View File

@@ -142,36 +142,7 @@ python_version_list
Space separated list of CPython versions and/or mypy version to run tests with.
**Possible values:**
* ``3.7``, ``3.8``, ``3.9``, ``3.10`` , ``3.11``, ``3.12``, ``3.13``
* ``pypy-3.7``, ``pypy-3.8``, ``pypy-3.9``, ``pypy-3.10``
+------+-----------+------------------+-----------------------------------------+
| Icon | Version | Maintained until | Comments |
+======+===========+==================+=========================================+
| ⚫ | 3.7 | 2023.06.27 | :red:`outdated` |
+------+-----------+------------------+-----------------------------------------+
| 🔴 | 3.8 | 2024.10 | |
+------+-----------+------------------+-----------------------------------------+
| 🟠 | 3.9 | 2025.10 | |
+------+-----------+------------------+-----------------------------------------+
| 🟡 | 3.10 | 2026.10 | |
+------+-----------+------------------+-----------------------------------------+
| 🟢 | 3.11 | 2027.10 | |
+------+-----------+------------------+-----------------------------------------+
| 🟢 | 3.12 | 2028.10 | :green:`latest` |
+------+-----------+------------------+-----------------------------------------+
| 🟣 | 3.13 | 2029.10 | Python 3.13 alpha (or RC) will be used. |
+------+-----------+------------------+-----------------------------------------+
| ⟲⚫ | pypy-3.7 | ????.?? | |
+------+-----------+------------------+-----------------------------------------+
| ⟲🔴 | pypy-3.8 | ????.?? | |
+------+-----------+------------------+-----------------------------------------+
| ⟲🟠 | pypy-3.9 | ????.?? | |
+------+-----------+------------------+-----------------------------------------+
| ⟲🟡 | pypy-3.10 | ????.?? | |
+------+-----------+------------------+-----------------------------------------+
.. include:: ../PythonVersionList.rst
system_list
@@ -185,34 +156,8 @@ system_list
Space separated list of systems to run tests on.
**Possible values:**
.. include:: ../SystemList.rst
* Native systems: ``ubuntu``, ``windows``, ``macos``
* MSYS2: ``msys``, ``mingw32``, ``mingw64``, ``clang32``, ``clang64``, ``ucrt64``
+------+-----------+------------------------------+-----------------------------------------------------------------+
| Icon | System | Used version | Comments |
+======+===========+==============================+=================================================================+
| 🧊 | Windows | Windows Server 2022 (latest) | |
+------+-----------+------------------------------+-----------------------------------------------------------------+
| 🐧 | Ubuntu | Ubuntu 22.04 (LTS) (latest) | |
+------+-----------+------------------------------+-----------------------------------------------------------------+
| 🍎 | macOS | macOS Monterey 12 (latest) | While this marked latest, macOS Ventura 13 is already provided. |
+------+-----------+------------------------------+-----------------------------------------------------------------+
| 🟪 | MSYS | | |
+------+-----------+------------------------------+-----------------------------------------------------------------+
| ⬛ | MinGW32 | | |
+------+-----------+------------------------------+-----------------------------------------------------------------+
| 🟦 | MinGW64 | | |
+------+-----------+------------------------------+-----------------------------------------------------------------+
| 🟫 | Clang32 | | |
+------+-----------+------------------------------+-----------------------------------------------------------------+
| 🟧 | Clang64 | | |
+------+-----------+------------------------------+-----------------------------------------------------------------+
| 🟨 | UCRT64 | | |
+------+-----------+------------------------------+-----------------------------------------------------------------+
Source: `Images provided by GitHub <https://github.com/actions/runner-images>`__
include_list
============

13
doc/JobTemplate/Global/PrepareJob.rst
View File

@@ -38,3 +38,16 @@ requires a `name` parameter to create the artifact names.
uses: pyTooling/Actions/.github/workflows/PrepareJob.yml@r5
with:
name: pyTooling
Parameters
**********
Secrets
*******
Results
*******

32
doc/JobTemplate/PythonVersionList.rst Normal file
View File

@@ -0,0 +1,32 @@
.. rubric:: Possible values
* ``3.8``, ``3.9``, ``3.10`` , ``3.11``, ``3.12``, ``3.13``, ``3.14``
* ``pypy-3.7``, ``pypy-3.8``, ``pypy-3.9``, ``pypy-3.10``, ``pypy-3.11``
+------+-----------+------------------+-----------------------------------------------+
| Icon | Version | Maintained until | Comments |
+======+===========+==================+===============================================+
| ⚫ | 3.8 | 2024.10 | :red:`outdated` |
+------+-----------+------------------+-----------------------------------------------+
| 🔴 | 3.9 | 2025.10 | |
+------+-----------+------------------+-----------------------------------------------+
| 🟠 | 3.10 | 2026.10 | |
+------+-----------+------------------+-----------------------------------------------+
| 🟡 | 3.11 | 2027.10 | |
+------+-----------+------------------+-----------------------------------------------+
| 🟢 | 3.12 | 2028.10 | |
+------+-----------+------------------+-----------------------------------------------+
| 🟢 | 3.13 | 2029.10 | :green:`latest CPython` |
+------+-----------+------------------+-----------------------------------------------+
| 🟣 | 3.14 | 2030.10 | Python 3.14 alpha, beta (or RC) will be used. |
+------+-----------+------------------+-----------------------------------------------+
| ⟲⚫ | pypy-3.7 | ????.?? | |
+------+-----------+------------------+-----------------------------------------------+
| ⟲⚫ | pypy-3.8 | ????.?? | |
+------+-----------+------------------+-----------------------------------------------+
| ⟲🔴 | pypy-3.9 | ????.?? | |
+------+-----------+------------------+-----------------------------------------------+
| ⟲🟠 | pypy-3.10 | ????.?? | |
+------+-----------+------------------+-----------------------------------------------+
| ⟲🟡 | pypy-3.11 | ????.?? | :green:`latest PyPy` |
+------+-----------+------------------+-----------------------------------------------+

30
doc/JobTemplate/SystemList.rst Normal file
View File

@@ -0,0 +1,30 @@
.. rubric:: Possible values
* Native systems: ``ubuntu``, ``windows``, ``macos``
* MSYS2: ``msys``, ``mingw32``, ``mingw64``, ``clang32``, ``clang64``, ``ucrt64``
+------+-----------+------------------------------+-----------------------------------------------------------------+
| Icon | System | Used version | Comments |
+======+===========+==============================+=================================================================+
| 🧊 | Windows | Windows Server 2025 (latest) | |
+------+-----------+------------------------------+-----------------------------------------------------------------+
| 🐧 | Ubuntu | Ubuntu 24.04 (LTS) (latest) | |
+------+-----------+------------------------------+-----------------------------------------------------------------+
| 🍎 | macOS | macOS Ventura 13 (latest) | While this marked latest, macOS Ventura 13 is already provided. |
+------+-----------+------------------------------+-----------------------------------------------------------------+
| 🍏 | macOS-arm | macOS Sonoma 14 (latest) | While this marked latest, macOS Ventura 13 is already provided. |
+------+-----------+------------------------------+-----------------------------------------------------------------+
| 🟪 | MSYS | | |
+------+-----------+------------------------------+-----------------------------------------------------------------+
| ⬛ | MinGW32 | | |
+------+-----------+------------------------------+-----------------------------------------------------------------+
| 🟦 | MinGW64 | | |
+------+-----------+------------------------------+-----------------------------------------------------------------+
| 🟫 | Clang32 | | |
+------+-----------+------------------------------+-----------------------------------------------------------------+
| 🟧 | Clang64 | | |
+------+-----------+------------------------------+-----------------------------------------------------------------+
| 🟨 | UCRT64 | | |
+------+-----------+------------------------------+-----------------------------------------------------------------+
Source: `Images provided by GitHub <https://github.com/actions/runner-images>`__

76
doc/JobTemplate/Templates.rst Normal file
View File

@@ -0,0 +1,76 @@
.. grid:: 5
.. grid-item::
:columns: 2
.. rubric:: All-In-One Templates
* :ref:`JOBTMPL/CompletePipeline` |br| |br| |br| |br|
.. rubric:: Global Templates
* :ref:`JOBTMPL/Parameters`
* :ref:`JOBTMPL/PrepareJob`
* :ref:`JOBTMPL/ExtractConfiguration`
.. grid-item::
:columns: 2
.. rubric:: Documentation
* :ref:`JOBTMPL/CheckDocumentation`
* :ref:`JOBTMPL/VerifyDocs`
* :ref:`JOBTMPL/SphinxDocumentation`
* :ref:`JOBTMPL/LaTeXDocumentation`
.. rubric:: Unit Tests, Code Coverage
* :ref:`JOBTMPL/ApplicationTesting`
* :ref:`JOBTMPL/UnitTesting`
.. grid-item::
:columns: 2
.. rubric:: Code Quality
* :ref:`JOBTMPL/StaticTypeCheck`
* *code formatting (planned)*
* *coding style (planned)*
* *code linting (planned)*
.. rubric:: Build and Packaging
* :ref:`JOBTMPL/Package`
* :ref:`JOBTMPL/InstallPackage`
.. grid-item::
:columns: 2
.. rubric:: Publishing
* :ref:`JOBTMPL/PublishOnPyPI`
* :ref:`JOBTMPL/PublishTestResults`
* :ref:`JOBTMPL/PublishCoverageResults`
* :ref:`JOBTMPL/PublishToGitHubPages`
.. rubric:: Releasing
* :ref:`JOBTMPL/PublishReleaseNotes`
* :ref:`JOBTMPL/TagReleaseCommit`
.. grid-item::
:columns: 2
.. rubric:: Cleanup Templates
* :ref:`JOBTMPL/IntermediateCleanup`
* :ref:`JOBTMPL/ArtifactCleanup`
.. grid-item::
:columns: 2
.. rubric:: :ref:`JOBTMPL/Deprecated`
* :ref:`JOBTMPL/CodeCoverage`
* :ref:`JOBTMPL/NightlyRelease`
* :ref:`JOBTMPL/BuildTheDocs`

111
doc/JobTemplate/index.rst
View File

@@ -6,101 +6,50 @@ Overview
The following list categorizes all pre-defined job templates, which can be instantiated in a pipeline (GitHub Action
Workflow). They can also serve as an example for creating or deriving own job templates.
.. grid:: 5
.. include:: Templates.rst
.. grid-item::
:columns: 2
.. rubric:: All-In-One Templates
* :ref:`JOBTMPL/CompletePipeline`
.. rubric:: Global Templates
* :ref:`JOBTMPL/Parameters`
* :ref:`JOBTMPL/PrepareJob`
* :ref:`JOBTMPL/ExtractConfiguration`
.. grid-item::
:columns: 2
.. rubric:: Documentation
* :ref:`JOBTMPL/CheckDocumentation`
* :ref:`JOBTMPL/VerifyDocs`
* :ref:`JOBTMPL/SphinxDocumentation`
* :ref:`JOBTMPL/LaTeXDocumentation`
.. rubric:: Unit Tests, Code Coverage
* :ref:`JOBTMPL/ApplicationTesting`
* :ref:`JOBTMPL/UnitTesting`
.. grid-item::
:columns: 2
.. rubric:: Code Quality
* :ref:`JOBTMPL/StaticTypeCheck`
* *code formatting (planned)*
* *coding style (planned)*
* *code linting (planned)*
.. rubric:: Build and Packaging
* :ref:`JOBTMPL/Package`
* :ref:`JOBTMPL/InstallPackage`
.. grid-item::
:columns: 2
.. rubric:: Publishing
* :ref:`JOBTMPL/PublishOnPyPI`
* :ref:`JOBTMPL/PublishTestResults`
* :ref:`JOBTMPL/PublishCoverageResults`
* :ref:`JOBTMPL/PublishToGitHubPages`
.. rubric:: Releasing
* :ref:`JOBTMPL/PublishReleaseNotes`
* :ref:`JOBTMPL/TagReleaseCommit`
.. grid-item::
:columns: 2
.. rubric:: Cleanup Templates
* :ref:`JOBTMPL/IntermediateCleanup`
* :ref:`JOBTMPL/ArtifactCleanup`
.. grid-item::
:columns: 2
.. rubric:: :ref:`JOBTMPL/Deprecated`
* :ref:`JOBTMPL/CodeCoverage`
* :ref:`JOBTMPL/NightlyRelease`
* :ref:`JOBTMPL/BuildTheDocs`
.. _JOBTMPL/Instantiation:
Instantiation
*************
When instantiating a template, a ``jobs:<Name>:uses`` is used to refer to a template file. Unfortunately, besides the
GitHub SLUG (*<Organization>/<Repository>*), also the full path to the template needs to be gives, but still it can't be
outside of ``.github/workflows`` to create a cleaner repository structure. Finally, the path contains a branch name
postfixed by ``@<branch>`` (tags are still not supported by GitHub Actions). A ``jobs:<Name>:with:`` section can be used
to handover input parameters to the template.
GitHub SLUG (*<Organization>/<Repository>*), also the full path to the template needs to be gives. Unfortunately, it
can't be outside of the ``.github/workflows`` directory creating a cleaner repository structure. Finally, the path
contains a branch name postfixed by ``@<branch>`` (tags are still not supported by GitHub Actions). Repositories usually
offer a ``@v2``/``@r2`` syntax for refering to the second version/revision.
Allmost all templates are generic and offer lots of configuration options. For handing over input parameters, a
``jobs:<Name>:with:`` node with a dictionary can be used. Additionally, some templates might require secrets, which
are passed from GitHub's ``secrets`` context to the template by using a ``jobs:<Name>:secrets:`` node.
Some templates might provide output parameters, which can be used in dependent jobs by setting a job dependency using
``jobs:<Name>:needs:``. The output parameter can be retrieved by accessing the ``needs`` context.
.. code-block:: yaml
on:
push:
workflow_dispatch:
schedule:
# Every Friday at 22:00 - rerun pipeline to check for dependency-based issues
- cron: '0 22 * * 5'
jobs:
<InstanceName>:
uses: <GitHubOrganization>/<Repository>/.github/workflows/<Template>.yml@v0
uses: <GitHubOrganization>/<Repository>/.github/workflows/<Template>.yml@r5
with:
<Param1>: <Value>
<Param1>: <Value1>
<Param2>: <Value2>
secrets:
<Secret1>: ${{ secrets.<SecretVariable1> }}
<Secret2>: ${{ secrets.<SecretVariable2> }}
<OtherInstance>:
...
needs:
- <InstanceName>
...
with:
<Param1>: ${{ needs.<InstanceName>.outputs.<Output1> }}

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

@@ -42,6 +42,7 @@ section > p,
.rst-content .topic-title {
font-size: larger;
font-weight: 700;
text-decoration: underline;
margin-top: 18px;
margin-bottom: 6px;
}

BIN
doc/_static/pyTooling-Actions-SimplePackage-Jobs.png vendored Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 189 KiB

BIN
doc/_static/pyTooling-Actions-SimplePackage.png vendored
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 189 KiB

After

Width:  |  Height:  |  Size: 146 KiB

80
doc/index.rst
View File

@@ -38,8 +38,7 @@ This repository gathers reusable CI tooling for testing, packaging and distribut
GitHub Actions
**************
* :ref:`ACTION/Releaser`
* :ref:`ACTION/WithPostStep`
.. include:: Action/Actions.rst
GitHub Action Job Templates
@@ -48,82 +47,7 @@ GitHub Action Job Templates
The following list categorizes all pre-defined job templates, which can be instantiated in a pipeline (GitHub Action
Workflow):
.. grid:: 5
.. grid-item::
:columns: 2
.. rubric:: All-In-One Templates
* :ref:`JOBTMPL/CompletePipeline`
.. rubric:: Global Templates
* :ref:`JOBTMPL/Parameters`
* :ref:`JOBTMPL/PrepareJob`
* :ref:`JOBTMPL/ExtractConfiguration`
.. grid-item::
:columns: 2
.. rubric:: Documentation
* :ref:`JOBTMPL/CheckDocumentation`
* :ref:`JOBTMPL/VerifyDocs`
* :ref:`JOBTMPL/SphinxDocumentation`
* :ref:`JOBTMPL/LaTeXDocumentation`
.. rubric:: Unit Tests, Code Coverage
* :ref:`JOBTMPL/ApplicationTesting`
* :ref:`JOBTMPL/UnitTesting`
.. grid-item::
:columns: 2
.. rubric:: Code Quality
* :ref:`JOBTMPL/StaticTypeCheck`
* *code formatting (planned)*
* *coding style (planned)*
* *code linting (planned)*
.. rubric:: Build and Packaging
* :ref:`JOBTMPL/Package`
* :ref:`JOBTMPL/InstallPackage`
.. grid-item::
:columns: 2
.. rubric:: Publishing
* :ref:`JOBTMPL/PublishOnPyPI`
* :ref:`JOBTMPL/PublishTestResults`
* :ref:`JOBTMPL/PublishCoverageResults`
* :ref:`JOBTMPL/PublishToGitHubPages`
.. rubric:: Releasing
* :ref:`JOBTMPL/PublishReleaseNotes`
* :ref:`JOBTMPL/TagReleaseCommit`
.. grid-item::
:columns: 2
.. rubric:: Cleanup Templates
* :ref:`JOBTMPL/IntermediateCleanup`
* :ref:`JOBTMPL/ArtifactCleanup`
.. grid-item::
:columns: 2
.. rubric:: :ref:`JOBTMPL/Deprecated`
* :ref:`JOBTMPL/CodeCoverage`
* :ref:`JOBTMPL/NightlyRelease`
* :ref:`JOBTMPL/BuildTheDocs`
.. include:: JobTemplate/Templates.rst
Example Pipelines