From 0f66b32418700766188c03919959ff07a069055d Mon Sep 17 00:00:00 2001 From: Patrick Lehmann Date: Wed, 20 Aug 2025 12:25:48 +0200 Subject: [PATCH] Documented CompletePipeline. --- .github/workflows/CompletePipeline.yml | 2 +- doc/Action/Actions.rst | 15 + doc/Action/Releaser.rst | 7 + doc/Action/index.rst | 24 +- doc/JobTemplate/AllInOne/CompletePipeline.rst | 622 +++++++++++++++++- .../Cleanup/IntermediateCleanup.rst | 2 +- .../Global/ExtractConfiguration.rst | 13 + doc/JobTemplate/Global/Parameters.rst | 59 +- doc/JobTemplate/Global/PrepareJob.rst | 13 + doc/JobTemplate/PythonVersionList.rst | 32 + doc/JobTemplate/SystemList.rst | 30 + doc/JobTemplate/Templates.rst | 76 +++ doc/JobTemplate/index.rst | 111 +--- doc/_static/css/override.css | 1 + .../pyTooling-Actions-SimplePackage-Jobs.png | Bin 0 -> 193607 bytes .../pyTooling-Actions-SimplePackage.png | Bin 193607 -> 149150 bytes doc/index.rst | 80 +-- 17 files changed, 860 insertions(+), 227 deletions(-) create mode 100644 doc/Action/Actions.rst create mode 100644 doc/JobTemplate/PythonVersionList.rst create mode 100644 doc/JobTemplate/SystemList.rst create mode 100644 doc/JobTemplate/Templates.rst create mode 100644 doc/_static/pyTooling-Actions-SimplePackage-Jobs.png diff --git a/.github/workflows/CompletePipeline.yml b/.github/workflows/CompletePipeline.yml index 6ad44b8..1229a39 100644 --- a/.github/workflows/CompletePipeline.yml +++ b/.github/workflows/CompletePipeline.yml @@ -71,7 +71,7 @@ on: apptest_python_version_list: description: 'Space separated list of Python versions to run tests with.' required: false - default: "" + default: '' type: string apptest_system_list: description: 'Space separated list of systems to run tests on.' diff --git a/doc/Action/Actions.rst b/doc/Action/Actions.rst new file mode 100644 index 0000000..98ad02e --- /dev/null +++ b/doc/Action/Actions.rst @@ -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` diff --git a/doc/Action/Releaser.rst b/doc/Action/Releaser.rst index 588da9d..189a2f5 100644 --- a/doc/Action/Releaser.rst +++ b/doc/Action/Releaser.rst @@ -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. diff --git a/doc/Action/index.rst b/doc/Action/index.rst index 44eef5f..6b38509 100644 --- a/doc/Action/index.rst +++ b/doc/Action/index.rst @@ -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: + : + steps: + - ... + + - name: + uses: ./with-post-step + with: + : + : diff --git a/doc/JobTemplate/AllInOne/CompletePipeline.rst b/doc/JobTemplate/AllInOne/CompletePipeline.rst index 9895cbc..7a0a26a 100644 --- a/doc/JobTemplate/AllInOne/CompletePipeline.rst +++ b/doc/JobTemplate/AllInOne/CompletePipeline.rst @@ -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 `__. +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 ` + * :ref:`pyTooling/Actions/.github/workflows/Parameters.yml ` + * :ref:`pyTooling/Actions/.github/workflows/ExtractConfiguration.yml ` + * :ref:`pyTooling/Actions/.github/workflows/UnitTesting.yml ` + * :ref:`pyTooling/Actions/.github/workflows/ApplicationTesting.yml ` + * :ref:`pyTooling/Actions/.github/workflows/CheckDocumentation.yml ` + * :ref:`pyTooling/Actions/.github/workflows/StaticTypeCheck.yml ` + * :ref:`pyTooling/Actions/.github/workflows/Package.yml ` + * :ref:`pyTooling/Actions/.github/workflows/PublishTestResults.yml ` + * :ref:`pyTooling/Actions/.github/workflows/PublishCoverageResults.yml ` + * :ref:`pyTooling/Actions/.github/workflows/SphinxDocumentation.yml ` + * :ref:`pyTooling/Actions/.github/workflows/LaTeXDocumentation.yml ` + * :ref:`pyTooling/Actions/.github/workflows/PublishToGitHubPages.yml ` + * :ref:`pyTooling/Actions/.github/workflows/PublishOnPyPI.yml ` + * :ref:`pyTooling/Actions/.github/workflows/TagReleaseCommit.yml ` + * :ref:`pyTooling/Actions/.github/workflows/PublishReleaseNotes.yml ` + * :ref:`pyTooling/Actions/.github/workflows/IntermediateCleanUp.yml ` + + * :gh:`geekyeggo/delete-artifact` + + * :ref:`pyTooling/Actions/.github/workflows/ArtifactCleanUp.yml ` + + * :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 ` + + +-----------------------------------------------------------+----------+----------+--------------+ + | 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 ` + + 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. diff --git a/doc/JobTemplate/Cleanup/IntermediateCleanup.rst b/doc/JobTemplate/Cleanup/IntermediateCleanup.rst index c025637..7608264 100644 --- a/doc/JobTemplate/Cleanup/IntermediateCleanup.rst +++ b/doc/JobTemplate/Cleanup/IntermediateCleanup.rst @@ -11,7 +11,7 @@ IntermediateCleanUp **Dependencies:** -.. todo:: IntermediateCleanUp:Dependencies needs documentation. +* :gh:`geekyeggo/delete-artifact` Instantiation ************* diff --git a/doc/JobTemplate/Global/ExtractConfiguration.rst b/doc/JobTemplate/Global/ExtractConfiguration.rst index 81c174f..79fce1d 100644 --- a/doc/JobTemplate/Global/ExtractConfiguration.rst +++ b/doc/JobTemplate/Global/ExtractConfiguration.rst @@ -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 +******* + + diff --git a/doc/JobTemplate/Global/Parameters.rst b/doc/JobTemplate/Global/Parameters.rst index dc2c1a8..d201a71 100644 --- a/doc/JobTemplate/Global/Parameters.rst +++ b/doc/JobTemplate/Global/Parameters.rst @@ -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 `__ include_list ============ diff --git a/doc/JobTemplate/Global/PrepareJob.rst b/doc/JobTemplate/Global/PrepareJob.rst index aad847e..e49e5f2 100644 --- a/doc/JobTemplate/Global/PrepareJob.rst +++ b/doc/JobTemplate/Global/PrepareJob.rst @@ -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 +******* + + diff --git a/doc/JobTemplate/PythonVersionList.rst b/doc/JobTemplate/PythonVersionList.rst new file mode 100644 index 0000000..2494769 --- /dev/null +++ b/doc/JobTemplate/PythonVersionList.rst @@ -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` | ++------+-----------+------------------+-----------------------------------------------+ diff --git a/doc/JobTemplate/SystemList.rst b/doc/JobTemplate/SystemList.rst new file mode 100644 index 0000000..4fd9703 --- /dev/null +++ b/doc/JobTemplate/SystemList.rst @@ -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 `__ diff --git a/doc/JobTemplate/Templates.rst b/doc/JobTemplate/Templates.rst new file mode 100644 index 0000000..7798f5a --- /dev/null +++ b/doc/JobTemplate/Templates.rst @@ -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` diff --git a/doc/JobTemplate/index.rst b/doc/JobTemplate/index.rst index 2fa9878..b8ab033 100644 --- a/doc/JobTemplate/index.rst +++ b/doc/JobTemplate/index.rst @@ -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::uses`` is used to refer to a template file. Unfortunately, besides the -GitHub SLUG (*/*), 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 ``@`` (tags are still not supported by GitHub Actions). A ``jobs::with:`` section can be used -to handover input parameters to the template. +GitHub SLUG (*/*), 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 ``@`` (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::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::secrets:`` node. + +Some templates might provide output parameters, which can be used in dependent jobs by setting a job dependency using +``jobs::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: : - uses: //.github/workflows/