From d7ad8f1387d0c35d73ad71a6c3f41391bcb849a4 Mon Sep 17 00:00:00 2001 From: Patrick Lehmann Date: Sun, 30 Oct 2022 18:14:36 +0100 Subject: [PATCH] Added more documentation sections. --- .github/workflows/Package.yml | 3 +- doc/JobTemplate/ArtifactCleanUp.rst | 76 ++++++++++++++++++---- doc/JobTemplate/CoverageCollection.rst | 23 +++++-- doc/JobTemplate/Package.rst | 90 +++++++++++++++++++++----- doc/JobTemplate/Parameters.rst | 78 +++++++++++++++++++--- doc/JobTemplate/StaticTypeCheck.rst | 15 +++-- 6 files changed, 233 insertions(+), 52 deletions(-) diff --git a/.github/workflows/Package.yml b/.github/workflows/Package.yml index b16f2ca..d2a640d 100644 --- a/.github/workflows/Package.yml +++ b/.github/workflows/Package.yml @@ -28,7 +28,7 @@ on: python_version: description: 'Python version.' required: false - default: '3.10' + default: '3.11' type: string requirements: description: 'Python dependencies to be installed through pip; if empty, use pyproject.toml through build.' @@ -100,7 +100,6 @@ jobs: if: inputs.requirements != '' && inputs.requirements != 'no-isolation' run: python setup.py bdist_wheel - - name: 📤 Upload wheel artifact uses: actions/upload-artifact@v2 with: diff --git a/doc/JobTemplate/ArtifactCleanUp.rst b/doc/JobTemplate/ArtifactCleanUp.rst index 77d65b0..78b8fb3 100644 --- a/doc/JobTemplate/ArtifactCleanUp.rst +++ b/doc/JobTemplate/ArtifactCleanUp.rst @@ -1,15 +1,34 @@ ArtifactCleanUp ############### +This job removes artifacts used to exchange data from job to job. + +**Behavior:** + +1. Delete the package artifact if the current pipeline run was not a tagged run. +2. Delete all remaining artifacts if given as a parameter. + +**Dependencies:** + +* geekyeggo/delete-artifact@v1 + + Instantiation ************* Simple Example ============== +The simplest variant just uses the artifact name for the package. + .. code-block:: yaml - TBD + jobs: + ArtifactCleanUp: + uses: pyTooling/Actions/.github/workflows/ArtifactCleanUp.yml@r0 + with: + package: Package + Complex Example =============== @@ -18,22 +37,53 @@ Complex Example .. code-block:: yaml - TBD + jobs: + ArtifactCleanUp: + uses: pyTooling/Actions/.github/workflows/ArtifactCleanUp.yml@r0 + needs: + - Params + - UnitTesting + - BuildTheDocs + - PublishToGitHubPages + - PublishTestResults + with: + package: ${{ fromJson(needs.Params.outputs.params).artifacts.package }} + remaining: | + ${{ fromJson(needs.Params.outputs.params).artifacts.unittesting }}-ubuntu-3.9 + ${{ fromJson(needs.Params.outputs.params).artifacts.unittesting }}-ubuntu-3.10 -Template Parameters -******************* -TBD 1 -===== +Parameters +********** -TBD +package +======= -TBD 1 -===== +Artifacts to be removed on not tagged runs. -TBD ++----------+----------+----------+ +| Required | Type | Default | ++==========+==========+==========+ +| yes | string | — — — — | ++----------+----------+----------+ -Template Results -**************** +remaining +========= -*None* +Artifacts to be removed unconditionally. + ++----------+----------+----------+ +| Required | Type | Default | ++==========+==========+==========+ +| optional | string | ``""`` | ++----------+----------+----------+ + +Secrets +******* + +This job template needs no secrets. + +Results +******* + +This job template has no output parameters. diff --git a/doc/JobTemplate/CoverageCollection.rst b/doc/JobTemplate/CoverageCollection.rst index da4ce14..975f333 100644 --- a/doc/JobTemplate/CoverageCollection.rst +++ b/doc/JobTemplate/CoverageCollection.rst @@ -18,8 +18,9 @@ Configuration options to ``pytest`` and ``coverage.py`` should be given via sect 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. Publish Cobertura file to CodeCov -8. Publish Cobertura file to Codacy +7. Upload HTML report as an artifact +8. Publish Cobertura file to CodeCov +9. Publish Cobertura file to Codacy **Preconditions:** @@ -30,6 +31,14 @@ Configuration options to ``pytest`` and ``coverage.py`` should be given via sect Setup a secret (e.g. ``codacy_token``) in GitHub to handover the Codacy project token to the job. +**Dependencies:** + +* actions/checkout@v2 +* actions/setup-python@v2 +* actions/upload-artifact@v2 +* codecov/codecov-action@v1 +* codacy/codacy-coverage-reporter-action@master + Instantiation ************* @@ -63,8 +72,8 @@ Complex Example secrets: codacy_token: ${{ secrets.CODACY_PROJECT_TOKEN }} -Template Parameters -******************* +Parameters +********** python_version ============== @@ -152,7 +161,7 @@ Token to push result to codacy. +----------+----------+--------------+ -Template Results -**************** +Results +******* -*None* +This job template has no output parameters. diff --git a/doc/JobTemplate/Package.rst b/doc/JobTemplate/Package.rst index 3e676aa..bdf4f8d 100644 --- a/doc/JobTemplate/Package.rst +++ b/doc/JobTemplate/Package.rst @@ -1,7 +1,25 @@ Package ####### -generate source and wheel packages, and upload them as an artifact. +This job packages the Python source code as a source package (``*.tar.gz``) and wheel package (``*.whl``) and uploads it +as an artifact. + +**Behavior:** + +1. Checkout repository +2. Setup Python and install dependencies +3. Package Python sources: + + * If parameter ``requirements`` is empty, use ``build`` package and run ``python build``. + * If parameter ``requirements`` is ``no-isolation``, use ``build`` package in *no-isolation* mode and run + ``python build``. + * If parameter ``requirements`` is non-empty, use ``setuptools`` package and run ``python setup.py``. + +**Dependencies:** + +* actions/checkout@v2 +* actions/setup-python@v2 +* actions/upload-artifact@v2 Instantiation ************* @@ -11,31 +29,73 @@ Simple Example .. code-block:: yaml - TBD + jobs: + Package: + uses: pyTooling/Actions/.github/workflows/Package.yml@r0 + with: + artifact: Package + Complex Example =============== - .. code-block:: yaml - TBD + jobs: + Package: + uses: pyTooling/Actions/.github/workflows/Package.yml@r0 + needs: + - Params + - Coverage + with: + python_version: ${{ fromJson(needs.Params.outputs.params).python_version }} + requirements: -r build/requirements.txt + artifact: ${{ fromJson(needs.Params.outputs.params).artifacts.Package }} -Template Parameters -******************* -TBD 1 -===== +Parameters +********** -TBD +python_version +============== -TBD 1 -===== +Python version. -TBD ++----------+----------+----------+ +| Required | Type | Default | ++==========+==========+==========+ +| optional | string | 3.11 | ++----------+----------+----------+ -Template Results -**************** +requirements +============ -*None* +Python dependencies to be installed through pip; if empty, use pyproject.toml through build. + ++----------+----------+----------+ +| Required | Type | Default | ++==========+==========+==========+ +| optional | string | ``""`` | ++----------+----------+----------+ + +artifact +======== + +Name of the package artifact. + ++----------+----------+----------+ +| Required | Type | Default | ++==========+==========+==========+ +| yes | string | — — — — | ++----------+----------+----------+ + +Secrets +******* + +This job template needs no secrets. + +Results +******* + +This job template has no output parameters. diff --git a/doc/JobTemplate/Parameters.rst b/doc/JobTemplate/Parameters.rst index 35aae7f..26e27f6 100644 --- a/doc/JobTemplate/Parameters.rst +++ b/doc/JobTemplate/Parameters.rst @@ -93,40 +93,98 @@ over resulting in the following combinations: python_version_list: "3.10" system_list: "ubuntu windows macos mingw32 mingw64 clang64 ucrt64" -Template Parameters -******************* +Parameters +********** Name -====== +==== + The name of the library or package. - It's used to create artifact names. +It's used to create artifact names. ++----------+----------+--------------+ +| Required | Type | Default | ++==========+==========+==============+ +| yes | string | — — — — | ++----------+----------+--------------+ + +python_version +============== + +Python version. + ++----------+----------+----------+ +| Required | Type | Default | ++==========+==========+==========+ +| optional | string | ``3.11`` | ++----------+----------+----------+ python_version_list =================== -TBD +Space separated list of Python versions to run tests with. + +Possible values: + +* ``3.7``, ``3.8``, ..., ``3.11``, ``3.12`` +* ``mypy-3.7``, ``mypy-3.8``, ``mypy-3.9`` + +For ``3.12``, Python 3.12 alpha will be used. + ++----------+----------+---------------------------+ +| Required | Type | Default | ++==========+==========+===========================+ +| optional | string | ``3.7 3.8 3.9 3.10 3.11`` | ++----------+----------+---------------------------+ system_list =========== -TBD +Space separated list of systems to run tests on. + +Possible values: + +* Native systems: ``ubuntu``, ``windows``, ``macos`` +* MSYS2: ``msys``, ``mingw32``, ``mingw64``, ``clang32``, ``clang64``, ``ucrt64`` + ++----------+----------+----------------------------------+ +| Required | Type | Default | ++==========+==========+==================================+ +| optional | string | ``ubuntu windows mingw64 macos`` | ++----------+----------+----------------------------------+ include_list ============ -TBD +Space separated list of ``system:python`` items to be included into the list of test. + ++----------+----------+----------+ +| Required | Type | Default | ++==========+==========+==========+ +| optional | string | ``""`` | ++----------+----------+----------+ exclude_list ============ -TBD +Space separated list of ``system:python`` items to be excluded from the list of test. -Template Results -**************** ++----------+----------+----------+ +| Required | Type | Default | ++==========+==========+==========+ +| optional | string | ``""`` | ++----------+----------+----------+ + +Secrets +******* + +This job template needs no secrets. + +Results +******* Params ====== diff --git a/doc/JobTemplate/StaticTypeCheck.rst b/doc/JobTemplate/StaticTypeCheck.rst index 49cd57e..d2a1cd1 100644 --- a/doc/JobTemplate/StaticTypeCheck.rst +++ b/doc/JobTemplate/StaticTypeCheck.rst @@ -48,8 +48,8 @@ Complex Example TBD -Template Parameters -******************* +Parameters +********** TBD 1 ===== @@ -61,7 +61,12 @@ TBD 1 TBD -Template Results -**************** +Secrets +******* -*None* +This job template needs no secrets. + +Results +******* + +This job template has no output parameters.