diff --git a/.btd.yml b/.btd.yml new file mode 100644 index 0000000..296c029 --- /dev/null +++ b/.btd.yml @@ -0,0 +1,9 @@ +input: doc +output: _build +requirements: requirements.txt +target: gh-pages +formats: [ html ] +images: + base: btdi/sphinx:pytooling + latex: btdi/latex +theme: https://codeload.GitHub.com/buildthedocs/sphinx.theme/tar.gz/v1 diff --git a/.editorconfig b/.editorconfig new file mode 100644 index 0000000..3c7043c --- /dev/null +++ b/.editorconfig @@ -0,0 +1,30 @@ +root = true + +[*] +charset = utf-8 +# end_of_line = lf +insert_final_newline = true +trim_trailing_whitespace = true +indent_style = tab +indent_size = 2 +tab_width = 2 + + +[*.py] +indent_style = tab +indent_size = 2 + +[*.{yml,yaml}] +indent_style = space +indent_size = 2 + +[*.{json,ini}] +indent_style = tab +indent_size = 2 + +[*.md] +trim_trailing_whitespace = false + +[*.rst] +indent_style = space +indent_size = 3 diff --git a/.github/workflows/CoverageCollection.yml b/.github/workflows/CoverageCollection.yml index 4a4462a..b5f6a97 100644 --- a/.github/workflows/CoverageCollection.yml +++ b/.github/workflows/CoverageCollection.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.' 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/.github/workflows/Pipeline.yml b/.github/workflows/Pipeline.yml new file mode 100644 index 0000000..dfaa29b --- /dev/null +++ b/.github/workflows/Pipeline.yml @@ -0,0 +1,31 @@ +name: Pipeline + +on: + push: + workflow_dispatch: + +jobs: + BuildTheDocs: + uses: pyTooling/Actions/.github/workflows/BuildTheDocs.yml@r0 + with: + artifact: Documentation + + PublishToGitHubPages: + uses: pyTooling/Actions/.github/workflows/PublishToGitHubPages.yml@r0 + needs: + - BuildTheDocs + with: + doc: Documentation + + ArtifactCleanUp: + name: πŸ—‘οΈ Artifact Cleanup + needs: + - BuildTheDocs + - PublishToGitHubPages + runs-on: ubuntu-latest + + steps: + - name: πŸ—‘οΈ Delete artifacts + uses: geekyeggo/delete-artifact@v1 + with: + name: Documentation diff --git a/.github/workflows/StaticTypeCheck.yml b/.github/workflows/StaticTypeCheck.yml index 55568c9..a94a026 100644 --- a/.github/workflows/StaticTypeCheck.yml +++ b/.github/workflows/StaticTypeCheck.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.' diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..b4feb0e --- /dev/null +++ b/.gitignore @@ -0,0 +1,37 @@ +# Python cache and object files +__pycache__/ +*.py[cod] + +# Coverage.py +.coverage +.cov +coverage.xml +/report/coverage + +# mypy +/report/typing + +# pytest +/report/unit + +# setuptools +/build/**/*.* +/dist/**/*.* +/*.egg-info + +# Dependencies +!requirements.txt + +# Sphinx +doc/_build/ +doc/pyTooling/**/*.* +!doc/pyTooling/index.rst + +# BuildTheDocs +doc/_theme/**/*.* + +# IntelliJ project files +/.idea/workspace.xml + +# Git files +!.git* diff --git a/Actions/__init__.py b/Actions/__init__.py new file mode 100644 index 0000000..c79a865 --- /dev/null +++ b/Actions/__init__.py @@ -0,0 +1,37 @@ +# ==================================================================================================================== # +# _____ _ _ ____ # +# _ __ _ |_ _|__ ___ | (_)_ __ __ _ / ___|___ _ __ ___ _ __ ___ ___ _ __ # +# | '_ \| | | || |/ _ \ / _ \| | | '_ \ / _` || | / _ \| '_ ` _ \| '_ ` _ \ / _ \| '_ \ # +# | |_) | |_| || | (_) | (_) | | | | | | (_| || |__| (_) | | | | | | | | | | | (_) | | | | # +# | .__/ \__, ||_|\___/ \___/|_|_|_| |_|\__, (_)____\___/|_| |_| |_|_| |_| |_|\___/|_| |_| # +# |_| |___/ |___/ # +# ==================================================================================================================== # +# Authors: # +# Patrick Lehmann # +# # +# License: # +# ==================================================================================================================== # +# Copyright 2017-2022 Patrick Lehmann - BΓΆtzingen, Germany # +# # +# Licensed under the Apache License, Version 2.0 (the "License"); # +# you may not use this file except in compliance with the License. # +# You may obtain a copy of the License at # +# # +# http://www.apache.org/licenses/LICENSE-2.0 # +# # +# Unless required by applicable law or agreed to in writing, software # +# distributed under the License is distributed on an "AS IS" BASIS, # +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # +# See the License for the specific language governing permissions and # +# limitations under the License. # +# # +# SPDX-License-Identifier: Apache-2.0 # +# ==================================================================================================================== # +# +"""Placeholder""" +__author__ = "Patrick Lehmann" +__email__ = "Paebbels@gmail.com" +__copyright__ = "2017-2022, Patrick Lehmann" +__license__ = "Apache License, Version 2.0" +__version__ = "0.4.4" +__keywords__ = [] diff --git a/doc/Action/Releaser.rst b/doc/Action/Releaser.rst new file mode 100644 index 0000000..69b7328 --- /dev/null +++ b/doc/Action/Releaser.rst @@ -0,0 +1,195 @@ +.. _ACTION/Releaser: + +Releaser +######## + +**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. +Combined with a workflow that is executed periodically, **Releaser** allows to provide a fixed release name for users +willing to use daily/nightly artifacts of a project. + +Furthermore, when any `semver `__ compliant tagged commit is pushed, **Releaser** can create a +release and upload assets. + +Context +******* + +GitHub provides official clients for the GitHub API through `github.com/octokit `__: + +- `octokit.js `__ (`octokit.github.io/rest.js `__) +- `octokit.rb `__ (`octokit.github.io/octokit.rb `__) +- `octokit.net `__ (`octokitnet.rtfd.io `__) + +When GitHub Actions was released in 2019, two Actions were made available through +`github.com/actions `__ for dealing with GitHub Releases: + +- `actions/create-release `__ +- `actions/upload-release-asset `__ + +However, those Actions were contributed by an employee in spare time, not officially supported by GitHub. +Therefore, they were unmaintained before GitHub Actions was out of the private beta +(see `actions/upload-release-asset#58 `__) +and, a year later, archived. +Those Actions are based on `actions/toolkit `__'s hydrated version of octokit.js. + +From a practical point of view, `actions/github-script `__ is the natural replacement to those Actions, since it allows to use a pre-authenticated *octokit.js* client along with the workflow run context. +Still, it requires writing plain JavaScript. + +Alternatively, there are non-official GitHub API libraries available in other languages (see `docs.github.com: rest/overview/libraries `__). +**Releaser** is based on `PyGithub/PyGithub `__, a Python client for the GitHub API. + +**Releaser** was originally created in `eine/tip `__, as an enhanced alternative to using +``actions/create-release`` and ``actions/upload-release-asset``, in order to cover certain use cases that were being +migrated from Travis CI to GitHub Actions. +The main limitation of GitHub's Actions was/is verbosity and not being possible to dynamically define the list of assets +to be uploaded. + +On the other hand, GitHub Actions artifacts do require login in order to download them. +Conversely, assets of GitHub Releases can be downloaded without login. +Therefore, in order to make CI results available to the widest audience, some projects prefer having tarballs available +as assets. +In this context, one of the main use cases of **Releaser** is pushing artifacts as release assets. +Thus, the name of the Action. + +GitHub provides an official CLI tool, written in golang: `cli/cli `__. +When the Python version of **Releaser** was written, ``cli`` was evaluated as an alternative to *PyGitHub*. +``gh release`` was (and still is) not flexible enough to update the reference of a release, without deleting and +recreating it (see `cli.github.com: manual/gh_release_create `__). +Deletion and recreation is unfortunate, because it notifies all the watchers of a repository +(see `eine/tip#111 `__). +However, `cli.github.com: manual/gh_release_upload `__ handles uploading +artifacts as assets faster and with better stability for larger files than *PyGitHub* +(see `msys2/msys2-installer#36 `__). +Furthermore, the GitHub CLI is installed on GitHub Actions' default virtual environments. +Although ``gh`` does not support login through SSH (see `cli/cli#3715 `__), on GitHub +Actions a token is available ``${{ github.token }}``. +Therefore, **Releaser** uses ``gh release upload`` internally. + +Usage +***** + +The following block shows a minimal YAML workflow file: + +.. code-block:: yaml + + name: 'workflow' + + on: + schedule: + - cron: '0 0 * * 5' + + jobs: + mwe: + runs-on: ubuntu-latest + steps: + + # Clone repository + - uses: actions/checkout@v2 + + # Build your application, tool, artifacts, etc. + - name: Build + run: | + echo "Build some tool and generate some artifacts" > artifact.txt + + # Update tag and pre-release + # - Update (force-push) tag to the commit that is used in the workflow. + # - Upload artifacts defined by the user. + - uses: pyTooling/Actions/releaser@r0 + with: + token: ${{ secrets.GITHUB_TOKEN }} + files: | + artifact.txt + README.md + + +Composite Action +================ + +The default implementation of **Releaser** is a Container Action. +Therefore, a pre-built container image is pulled before starting the job. +Alternatively, a Composite Action version is available: ``uses: pyTooling/Actions/releaser/composite@main``. +The Composite version installs the dependencies on the host (the runner environment), instead of using a container. +Both implementations are functionally equivalent from **Releaser**'s point of view; however, the Composite Action allows +users to tweak the version of Python by using `actions/setup-python `__ before. + +Options +******* + +All options can be optionally provided as environment variables: ``INPUT_TOKEN``, ``INPUT_FILES``, ``INPUT_TAG``, ``INPUT_RM`` +and/or ``INPUT_SNAPSHOTS``. + +token (required) +================ + +Token to make authenticated API calls; can be passed in using ``{{ secrets.GITHUB_TOKEN }}``. + +files (required) +================ + +Either a single filename/pattern or a multi-line list can be provided. All the artifacts are uploaded regardless of the +hierarchy. + +For creating/updating a release without uploading assets, set ``files: none``. + +tag +=== + +The default tag name for the tip/nightly pre-release is ``tip``, but it can be optionally overriden through option ``tag``. + +rm +== + +Set option ``rm`` to ``true`` for systematically removing previous artifacts (e.g. old versions). +Otherwise (by default), all previours artifacts are preserved or overwritten. + +Note: + If all the assets are removed, or if the release itself is removed, tip/nightly assets won't be available for + users until the workflow is successfully run. + For instance, Action `setup-ghdl-ci `__ uses assets from `ghdl/ghdl: releases/tag/nightly `__. + Hence, it is recommended to try removing the conflictive assets only, in order to maximise the availability. + +snapshots +========= + +Whether to create releases from any tag or to treat some as snapshots. +By default, all the tags with non-empty ``prerelease`` field (see `semver.org: Is there a suggested regular expression (RegEx) to check a SemVer string? `__) +are considered snapshots; neither a release is created nor assets are uploaded. + +Advanced/complex use cases +************************** + +**Releaser** is essentially a very thin wrapper to use the GitHub Actions context data along with the classes +and methods of PyGithub. + +Similarly to `actions/github-script `__, users with advanced/complex requirements +might find it desirable to write their own Python script, instead of using **Releaser**. +In fact, since ``shell: python`` is supported in GitHub Actions, using Python does *not* require any Action. +For prototyping purposes, the following job might be useful: + +.. code-block:: yaml + + Release: + name: 'πŸ“¦ Release' + runs-on: ubuntu-latest + needs: + - ... + if: github.event_name != 'pull_request' && (github.ref == 'refs/heads/master' || contains(github.ref, 'refs/tags/'>`__) + steps: + + - uses: actions/download-artifact@v2 + + - shell: bash + run: pip install PyGithub --progress-bar off + + - name: Set list of files for uploading + id: files + shell: python + run: | + from github import Github + print("Β· Get GitHub API handler (authenticate)") + gh = Github('${{ github.token }}') + print("Β· Get Repository handler") + gh_repo = gh.get_repo('${{ github.repository }}') + +Find a non-trivial use case at `msys2/msys2-autobuild `__. diff --git a/doc/Action/With-post-step.rst b/doc/Action/With-post-step.rst new file mode 100644 index 0000000..6ab3d98 --- /dev/null +++ b/doc/Action/With-post-step.rst @@ -0,0 +1,5 @@ +.. _ACTION/WithPostStep: + +with-post-step +############## + diff --git a/doc/Action/index.rst b/doc/Action/index.rst new file mode 100644 index 0000000..be86e43 --- /dev/null +++ b/doc/Action/index.rst @@ -0,0 +1,4 @@ +Overview +######## + + diff --git a/doc/Background.rst b/doc/Background.rst new file mode 100644 index 0000000..6e8da2d --- /dev/null +++ b/doc/Background.rst @@ -0,0 +1,87 @@ +Background +########## + +GitHub Actions supports five procedures to reuse code: + +- JavaScript Action: + + - `docs.github.com: actions/creating-actions/creating-a-javascript-action `__ + +- Container Action: + + - `docs.github.com: actions/creating-actions/creating-a-docker-container-action `__ + +- Container Step: + + - `docs.github.com: actions/learn-github-actions/workflow-syntax-for-github-actions#example-using-a-docker-public-registry-action `__ + - `docs.github.com: actions/learn-github-actions/workflow-syntax-for-github-actions#jobsjob_idstepswithargs `__ + +- Composite Action: + + - `docs.github.com: actions/creating-actions/creating-a-composite-action `__ + - `github.blog/changelog: 2020-08-07-github-actions-composite-run-steps `__ + - `github.blog/changelog: 2021-08-25-github-actions-reduce-duplication-with-action-composition `__ + +- Reusable Workflow: + + - `docs.github.com: actions/learn-github-actions/reusing-workflows `__ + - `github.blog/changelog: 2021-10-05-github-actions-dry-your-github-actions-configuration-by-reusing-workflows `__ + +Container Actions and Container Steps are almost equivalent: Actions use a configuration file (``action.yml``), while +Steps do not. +Leaving JavaScript and Container Actions and Steps aside, the main differences between Composite Actions and Reusable +Workflows are the following: + +- Composite Actions can be executed from a remote/external path or from the checked out branch, and from any location. + However, Reusable Workflows can only be used through a remote/external path (``{owner}/{repo}/{path}/{filename}@{ref}``), + where ``{path}`` must be ``.github/workflows``, and ``@{ref}`` is required. + See `actions/runner#1493 `__. + As a result: + + - Local Composite Actions cannot be used without a prior repo checkout, but Reusable Workflows can be used without + checkout. + - Testing development versions of local Reusable Workflows is cumbersome, because PRs do not pick the modifications by + default. + +- Composite Actions can include multiple steps, but not multiple jobs. + Conversely, Reusable Workflows can include multiple jobs, and multiple steps in each job. +- Composite Actions can include multiple files, so it's possible to use files from the Action or from the user's repository. + Conversely, Reusable Workflows are a single YAML file, with no additional files retrieved by default. + +Callable vs dispatchable workflows +********************************** + +Reusable Workflows are defined through the ``workflow_call`` event kind. +Similarly, any "regular" Workflow can be triggered through a ``workflow_dispatch`` event. +Both event kinds support ``input`` options, which are usable within the Workflow. +Therefore, one might intuitively try to write a workflow which is both callable and dispatchable. +In other words, which can be either reused from another workflow, or triggered through the API. +Unfortunately, that is not the case. +Although ``input`` options can be duplicated for both events, GitHub's backend exposes them through different objects. +In dispatchable Workflows, the object is ``${{ github.event.inputs }}``, while callable workflows receive ``${{ inputs }}``. + +As a result, in order to make a reusable workflow dispatchable, a wrapper workflow is required. +See, for instance, `hdl/containers: .github/workflows/common.yml `__ +and `hdl/containers: .github/workflows/dispatch.yml `__. +Alternatively, a normalisation job might be used, similar to the ``Parameters`` in this repo. + +Call hierarchy +************** + +Reusable Workflows cannot call other Reusable Workflows, however, they can use Composite Actions and Composite Actions +can call other Actions. +Therefore, in some use cases it is sensible to combine one layer of reusable workflows for orchestrating the jobs, along +with multiple layers of composite actions. + +Script with post step +********************* + +JavaScript Actions support defining ``pre``, ``pre-if``, ``post`` and ``post-if`` steps, which allow executing steps at +the beginning or the end of a job, regardless of intermediate steps failing. +Unfortunately, those are not available for any other Action type. + +Action [with-post-step](with-post-step) is a generic JS Action to execute a main command and to set a command as a post +step. +It allows using the ``post`` feature with scripts written in bash, python or any other interpreted language available on +the environment. +See: `actions/runner#1478 `__. diff --git a/doc/Dependency.rst b/doc/Dependency.rst new file mode 100644 index 0000000..4cf2f5d --- /dev/null +++ b/doc/Dependency.rst @@ -0,0 +1,12 @@ +Dependencies +############ + +* Parameters + + * *None* + +* PublishOnPyPI + + * actions/download-artifact + * actions/setup-python + * geekyeggo/delete-artifact diff --git a/doc/JobTemplate/ArtifactCleanUp.rst b/doc/JobTemplate/ArtifactCleanUp.rst new file mode 100644 index 0000000..bc9ae54 --- /dev/null +++ b/doc/JobTemplate/ArtifactCleanUp.rst @@ -0,0 +1,91 @@ +.. _JOBTMPL/ArtifactCleanup: + +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:** + +* :gh:`geekyeggo/delete-artifact` + + +Instantiation +************* + +Simple Example +============== + +The simplest variant just uses the artifact name for the package. + +.. code-block:: yaml + + jobs: + ArtifactCleanUp: + uses: pyTooling/Actions/.github/workflows/ArtifactCleanUp.yml@r0 + with: + package: Package + + +Complex Example +=============== + + + +.. code-block:: yaml + + 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 + + +Parameters +********** + +package +======= + +Artifacts to be removed on not tagged runs. + ++----------+----------+----------+ +| Required | Type | Default | ++==========+==========+==========+ +| yes | string | β€” β€” β€” β€” | ++----------+----------+----------+ + +remaining +========= + +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/BuildTheDocs.rst b/doc/JobTemplate/BuildTheDocs.rst new file mode 100644 index 0000000..f89f626 --- /dev/null +++ b/doc/JobTemplate/BuildTheDocs.rst @@ -0,0 +1,71 @@ +.. _JOBTMPL/BuildTheDocs: + +BuildTheDocs +############ + +This jobs compiles the documentation written in ReStructured Text with Sphinx using BuildTheDocs. + +**Behavior:** + +1. Checkout repository. +2. Build the documentation. +3. Upload the HTML documentation as an artifact. + +**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@r0 + with: + artifact: Documentation + +Complex Example +=============== + +.. code-block:: yaml + + jobs: + BuildTheDocs: + uses: pyTooling/Actions/.github/workflows/BuildTheDocs.yml@r0 + needs: + - Params + with: + artifact: ${{ fromJson(needs.Params.outputs.params).artifacts.doc }} + + +Parameters +********** + +artifact +======== + +Name of the documentation 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/CoverageCollection.rst b/doc/JobTemplate/CoverageCollection.rst new file mode 100644 index 0000000..0f5b714 --- /dev/null +++ b/doc/JobTemplate/CoverageCollection.rst @@ -0,0 +1,169 @@ +.. _JOBTMPL/CodeCoverage: + +CoverageCollection +################## + +This jobs runs the specified unit tests with activated code coverage collection (incl. branch coverage). + +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 `__ and `Codacy `__. + +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@r0 + with: + artifact: Coverage + secrets: + codacy_token: ${{ secrets.CODACY_PROJECT_TOKEN }} + +Complex Example +=============== + +.. code-block:: yaml + + jobs: + Coverage: + uses: pyTooling/Actions/.github/workflows/CoverageCollection.yml@r0 + needs: + - Params + with: + python_version: ${{ fromJson(needs.Params.outputs.params).python_version }} + artifact: ${{ fromJson(needs.Params.outputs.params).artifacts.Coverage }} + secrets: + codacy_token: ${{ secrets.CODACY_PROJECT_TOKEN }} + +Parameters +********** + +python_version +============== + +Python version used for running unit tests. + ++----------+----------+----------+ +| Required | Type | Default | ++==========+==========+==========+ +| optional | string | 3.11 | ++----------+----------+----------+ + + +requirements +============ + +Python dependencies to be installed through pip. + ++----------+----------+-------------------------------+ +| Required | Type | Default | ++==========+==========+===============================+ +| optional | string | ``-r tests/requirements.txt`` | ++----------+----------+-------------------------------+ + + +tests_directory +=============== + +Path to the directory containing tests (test working directory). + ++----------+----------+-----------+ +| Required | Type | Default | ++==========+==========+===========+ +| optional | string | ``tests`` | ++----------+----------+-----------+ + + +unittest_directory +================== + +Path to the directory containing unit tests (relative to test_directory). + ++----------+----------+-----------+ +| Required | Type | Default | ++==========+==========+===========+ +| optional | string | ``unit`` | ++----------+----------+-----------+ + + +coverage_config +=============== + +Path to the ``.coveragerc`` file. Use ``pyproject.toml`` by default. + ++----------+----------+--------------------+ +| Required | Type | Default | ++==========+==========+====================+ +| optional | string | ``pyproject.toml`` | ++----------+----------+--------------------+ + + +artifact +======== + +Name of the coverage artifact. + ++----------+----------+--------------+ +| Required | Type | Default | ++==========+==========+==============+ +| yes | string | β€” β€” β€” β€” | ++----------+----------+--------------+ + +Secrets +******* + +codacy_token +============ + +Token to push result to codacy. + ++----------+----------+--------------+ +| Required | Type | Default | ++==========+==========+==============+ +| yes | string | β€” β€” β€” β€” | ++----------+----------+--------------+ + + +Results +******* + +This job template has no output parameters. diff --git a/doc/JobTemplate/Package.rst b/doc/JobTemplate/Package.rst new file mode 100644 index 0000000..dd2f45f --- /dev/null +++ b/doc/JobTemplate/Package.rst @@ -0,0 +1,103 @@ +.. _JOBTMPL/Package: + +Package +####### + +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:** + +* :gh:`actions/checkout` +* :gh:`actions/setup-python` +* :gh:`actions/upload-artifact` + +Instantiation +************* + +Simple Example +============== + +.. code-block:: yaml + + jobs: + Package: + uses: pyTooling/Actions/.github/workflows/Package.yml@r0 + with: + artifact: Package + + +Complex Example +=============== + + +.. code-block:: yaml + + 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 }} + + +Parameters +********** + +python_version +============== + +Python version. + ++----------+----------+----------+ +| Required | Type | Default | ++==========+==========+==========+ +| optional | string | 3.11 | ++----------+----------+----------+ + +requirements +============ + +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 new file mode 100644 index 0000000..8e0a3b4 --- /dev/null +++ b/doc/JobTemplate/Parameters.rst @@ -0,0 +1,198 @@ +.. _JOBTMPL/Parameters: + +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 `__. + +It generates output parameters with artifact names and a job matrix to be used in later running jobs. + +Instantiation +************* + +Simple Example +============== + +The following instantiation example creates a job `Params` derived from job template `Parameters` version `r0`. 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/Parameters.yml@r0 + with: + name: pyTooling + +Complex Example +=============== + +The following instantiation example creates 3 jobs from the same template, but with differing input parameters. The +first job `UnitTestingParams` might be used to create a job matrix of unit tests. It creates the cross of default +systems (Windows, Ubuntu, MacOS, MinGW64) and the given list of Python versions including some mypy versions. In +addition a list of excludes (marked as :deletion:`deletions`) and includes (marked as :addition:`additions`) is handed +over resulting in the following combinations: + ++------------+-------------+-------------+-------------+--------------+-------------------------+------------+-------------+------------------------------+------------------------------+ +| Version | 3.7 πŸ”΄ | 3.8 🟠 | 3.9 🟑 | 3.10 🟒 | 3.11 🟒 | 3.12.a1 🟣 | pypy-3.7 πŸ”΄ | pypy-3.8 🟠 | pypy-3.9 🟑 | ++============+=============+=============+=============+==============+=========================+============+=============+==============================+==============================+ +| Windows 🧊 | windows:3.7 | windows:3.8 | windows:3.9 | windows:3.10 | | | | :deletion:`windows:pypy-3.8` | :deletion:`windows:pypy-3.9` | ++------------+-------------+-------------+-------------+--------------+-------------------------+------------+-------------+------------------------------+------------------------------+ +| Ubuntu 🐧 | ubuntu:3.7 | ubuntu:3.8 | ubuntu:3.9 | ubuntu:3.10 | :addition:`ubuntu:3.11` | | | ubuntu:pypy-3.8 | ubuntu:pypy-3.9 | ++------------+-------------+-------------+-------------+--------------+-------------------------+------------+-------------+------------------------------+------------------------------+ +| MacOS 🍎 | macos:3.7 | macos:3.8 | macos:3.9 | macos:3.10 | :addition:`macos:3.11` | | | macos:pypy-3.8 | macos:pypy-3.9 | ++------------+-------------+-------------+-------------+--------------+-------------------------+------------+-------------+------------------------------+------------------------------+ +| MSYS πŸŸͺ | | | | | | | | | | ++------------+-------------+-------------+-------------+--------------+-------------------------+------------+-------------+------------------------------+------------------------------+ +| MinGW32 ⬛ | | | | | | | | | | ++------------+-------------+-------------+-------------+--------------+-------------------------+------------+-------------+------------------------------+------------------------------+ +| MinGW64 🟦 | | | | mingw64:3.10 | | | | | | ++------------+-------------+-------------+-------------+--------------+-------------------------+------------+-------------+------------------------------+------------------------------+ +| Clang32 🟫 | | | | | | | | | | ++------------+-------------+-------------+-------------+--------------+-------------------------+------------+-------------+------------------------------+------------------------------+ +| Clang64 🟧 | | | | | | | | | | ++------------+-------------+-------------+-------------+--------------+-------------------------+------------+-------------+------------------------------+------------------------------+ +| UCRT64 🟨 | | | | | | | | | | ++------------+-------------+-------------+-------------+--------------+-------------------------+------------+-------------+------------------------------+------------------------------+ + + +.. code-block:: yaml + + name: Pipeline + + on: + push: + workflow_dispatch: + + jobs: + UnitTestingParams: + uses: pyTooling/Actions/.github/workflows/Parameters.yml@r0 + with: + name: pyTooling + python_version_list: "3.7 3.8 3.9 3.10 pypy-3.8 pypy-3.9" + include_list: "ubuntu:3.11 macos:3.11" + exclude_list: "windows:pypy-3.8 windows:pypy-3.9" + + PerformanceTestingParams: + uses: pyTooling/Actions/.github/workflows/Parameters.yml@r0 + with: + name: pyTooling + python_version_list: "3.10 3.11" + system_list: "ubuntu windows macos" + + PlatformTestingParams: + uses: pyTooling/Actions/.github/workflows/Parameters.yml@dev + with: + name: pyTooling + python_version_list: "3.10" + system_list: "ubuntu windows macos mingw32 mingw64 clang64 ucrt64" + +Parameters +********** + +Name +==== + +The name of the library or package. + +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 +=================== + +Space separated list of Python versions to run tests with. + +Possible values: + +* ``3.6`` (outdated), ``3.7``, ..., ``3.11``, ``3.12`` +* ``pypy-3.7``, ``pypy-3.8``, ``pypy-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 +=========== + +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 +============ + +Space separated list of ``system:python`` items to be included into the list of test. + ++----------+----------+----------+ +| Required | Type | Default | ++==========+==========+==========+ +| optional | string | ``""`` | ++----------+----------+----------+ + +exclude_list +============ + +Space separated list of ``system:python`` items to be excluded from the list of test. + ++----------+----------+----------+ +| Required | Type | Default | ++==========+==========+==========+ +| optional | string | ``""`` | ++----------+----------+----------+ + +Secrets +******* + +This job template needs no secrets. + +Results +******* + +Params +====== + +.. todo:: Parameters:Params Needs documentation. + +Jobs +==== + +.. todo:: Parameters:Jobs Needs documentation. diff --git a/doc/JobTemplate/PublishOnPyPI.rst b/doc/JobTemplate/PublishOnPyPI.rst new file mode 100644 index 0000000..22d953c --- /dev/null +++ b/doc/JobTemplate/PublishOnPyPI.rst @@ -0,0 +1,136 @@ +.. _JOBTMPL/PyPI: + +PublishOnPyPI +############# + +Publish a source (``*.tar.gz``) package and/or wheel (``*.whl``) packages to `PyPI `__. + +**Behavior:** + +1. Download package artifact +2. Publish source package(s) (``*.tar.gz``) +3. Publish wheel package(s) (``*.whl``) +4. Delete the artifact + +**Preconditions:** + +A PyPI account was created and the package name is either not occupied or the user has access rights for that package. + +**Requirements:** + +Setup a secret (e.g. ``PYPI_TOKEN``) in GitHub to handover the PyPI token to the job. + +**Dependencies:** + +* :gh:`actions/download-artifact` +* :gh:`actions/setup-python` +* :gh:`geekyeggo/delete-artifact` + + +Instantiation +************* + +Simple Example +============== + +The following example demonstrates how to publish the artifact named ``Package`` to PyPI on every pipeline run triggered +by a Git tag. A secret is forwarded from GitHub secrets to a job secret. + +.. code-block:: yaml + + jobs: + # ... + + PublishOnPyPI: + uses: pyTooling/Actions/.github/workflows/PublishOnPyPI.yml@r0 + if: startsWith(github.ref, 'refs/tags') + with: + artifact: Package + secrets: + PYPI_TOKEN: ${{ secrets.PYPI_TOKEN }} + +Complex Example +=============== + +In this more complex example, the job depends on a parameter creation (``Params``) and packaging job (``Package``). The +used Python version is overwritten by a parameter calculated in the ``Params`` jobs. Also the artifact name is managed +by that job. Finally, the list of requirements is overwritten to load a list of requirements from ``dist/requirements.txt``. + +.. code-block:: yaml + + jobs: + Params: + # ... + + Package: + # ... + + PublishOnPyPI: + uses: pyTooling/Actions/.github/workflows/PublishOnPyPI.yml@r0 + if: startsWith(github.ref, 'refs/tags') + needs: + - Params + - Package + with: + python_version: ${{ fromJson(needs.Params.outputs.params).python_version }} + requirements: -r dist/requirements.txt + artifact: ${{ fromJson(needs.Params.outputs.params).artifacts.Package }} + secrets: + PYPI_TOKEN: ${{ secrets.PYPI_TOKEN }} + +Parameters +********** + +python_version +============== + +Python version used for uploading the package contents via `twine` to PyPI. + ++----------+----------+----------+ +| Required | Type | Default | ++==========+==========+==========+ +| optional | string | ``3.11`` | ++----------+----------+----------+ + + +requirements +============ + +List of requirements to be installed for uploading the package contents to PyPI. + ++----------+----------+-----------------+ +| Required | Type | Default | ++==========+==========+=================+ +| optional | string | ``wheel twine`` | ++----------+----------+-----------------+ + + +artifact +======== + +Name of the artifact containing the package(s). + ++----------+----------+--------------+ +| Required | Type | Default | ++==========+==========+==============+ +| yes | string | β€” β€” β€” β€” | ++----------+----------+--------------+ + +Secrets +******* + +PYPI_TOKEN +========== + +The token to access the package at PyPI for uploading new data. + ++----------+----------+--------------+ +| Required | Type | Default | ++==========+==========+==============+ +| yes | string | β€” β€” β€” β€” | ++----------+----------+--------------+ + +Results +******* + +This job template has no output parameters. diff --git a/doc/JobTemplate/PublishTestResults.rst b/doc/JobTemplate/PublishTestResults.rst new file mode 100644 index 0000000..3053053 --- /dev/null +++ b/doc/JobTemplate/PublishTestResults.rst @@ -0,0 +1,87 @@ +.. _JOBTMPL/PublishTestResults: + +PublishTestResults +################## + +This job downloads all artifacts and uploads jUnit XML reports as a Markdown page to GitHub Actions to visualize the +results a an item in the job list. For publishing, :gh:`dorny/test-reporter` is used. + +**Behavior:** + +1. Checkout repository +2. Download (all) artifacts +3. Publish test results as a markdown report page to GitHub Actions. + +.. note:: + + The :gh:`actions/download-artifact` does not support wildcards to specify a subset of artifacts for downloading. + Thus, all artifacts need to be downloaded. + +**Dependencies:** + +* :gh:`actions/checkout` +* :gh:`actions/download-artifact` +* :gh:`dorny/test-reporter` + + +Instantiation +************* + +Simple Example +============== + +.. code-block:: yaml + + jobs: + PublishTestResults: + uses: pyTooling/Actions/.github/workflows/PublishTestResults.yml@r0 + +Complex Example +=============== + +.. code-block:: yaml + + jobs: + CodeCoverage: + # ... + + UnitTesting: + # ... + + PublishTestResults: + uses: pyTooling/Actions/.github/workflows/PublishTestResults.yml@r0 + needs: + - CodeCoverage + - UnitTesting + +Parameters +********** + +report_files +============ + +Pattern of jUnit report files to publish as Markdown. + +The parameter can be a comma separated list. Wildcards are supported. + +.. hint:: + + All artifacts are downloaded into directory ``artifacts``, thus the pattern should include this directory as a + prefix. + ++----------+----------+---------------------------------+ +| Required | Type | Default | ++==========+==========+=================================+ +| optional | string | ``artifacts/**/*.xml`` | ++----------+----------+---------------------------------+ + + +Secrets +******* + +This job template needs no secrets. + +Results +******* + +This job template has no output parameters. diff --git a/doc/JobTemplate/PublishToGitHubPages.rst b/doc/JobTemplate/PublishToGitHubPages.rst new file mode 100644 index 0000000..2f7520a --- /dev/null +++ b/doc/JobTemplate/PublishToGitHubPages.rst @@ -0,0 +1,103 @@ +.. _JOBTMPL/PublishToGitHubPages: + +PublishToGitHubPages +#################### + +This job publishes HTML content from artifacts of other jobs to GitHub Pages. + +**Behavior:** + +1. Checkout repository. +2. Download artifacts. +3. Push HTML files to branch ``gh-pages``. + +**Dependencies:** + +* :gh:`actions/checkout` +* :gh:`actions/download-artifact` + +Instantiation +************* + +Simple Example +============== + +.. code-block:: yaml + + jobs: + BuildTheDocs: + # ... + + PublishToGitHubPages: + uses: pyTooling/Actions/.github/workflows/PublishToGitHubPages.yml@r0 + needs: + - BuildTheDocs + with: + doc: Documentation + + +Complex Example +=============== + +.. code-block:: yaml + + jobs: + PublishToGitHubPages: + uses: pyTooling/Actions/.github/workflows/PublishToGitHubPages.yml@r0 + needs: + - Params + - BuildTheDocs + - Coverage + - StaticTypeCheck + with: + doc: ${{ fromJson(needs.Params.outputs.params).artifacts.doc }} + coverage: ${{ fromJson(needs.Params.outputs.params).artifacts.coverage }} + typing: ${{ fromJson(needs.Params.outputs.params).artifacts.typing }} + +Parameters +********** + +doc +=== + +Name of the documentation artifact. + ++----------+----------+--------------+ +| Required | Type | Default | ++==========+==========+==============+ +| yes | string | β€” β€” β€” β€” | ++----------+----------+--------------+ + +coverage +======== + +Name of the coverage artifact. + ++----------+----------+-----------------+ +| Required | Type | Default | ++==========+==========+=================+ +| optional | string | ``""`` | ++----------+----------+-----------------+ + + +typing +====== + +Name of the typing artifact. + ++----------+----------+-----------------+ +| 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/Release.rst b/doc/JobTemplate/Release.rst new file mode 100644 index 0000000..51832a8 --- /dev/null +++ b/doc/JobTemplate/Release.rst @@ -0,0 +1,70 @@ +.. _JOBTMPL/GitHubReleasePage: + +Release +####### + +This job creates a Release Page on GitHub. + +**Release Template in Markdown**: + +.. parsed-literal:: + + **Automated Release created on: ${{ steps.getVariables.outputs.datetime }}** + + # New Features + * tbd + + # Changes + * tbd + + # Bug Fixes + * tbd + +**Behavior:** + +1. Extract information from environment variables provided by GitHub Actions. +2. Create a Release Page on GitHub + +**Dependencies:** + +* :gh:`actions/create-release` + +Instantiation +************* + +Simple Example +============== + +.. code-block:: yaml + + jobs: + Release: + uses: pyTooling/Actions/.github/workflows/Release.yml@r0 + + +Complex Example +=============== + +.. code-block:: yaml + + jobs: + Release: + uses: pyTooling/Actions/.github/workflows/Release.yml@r0 + if: startsWith(github.ref, 'refs/tags') + needs: + - Package + +Parameters +********** + +This job template needs no input parameters. + +Secrets +******* + +This job template needs no secrets. + +Results +******* + +This job template has no output parameters. diff --git a/doc/JobTemplate/StaticTypeCheck.rst b/doc/JobTemplate/StaticTypeCheck.rst new file mode 100644 index 0000000..e6ecfbc --- /dev/null +++ b/doc/JobTemplate/StaticTypeCheck.rst @@ -0,0 +1,155 @@ +.. _JOBTMPL/StaticTypeChecking: + +StaticTypeCheck +############### + +This job runs a static type check using mypy and collects the results. These results can be converted to a HTML report +and then uploaded as an artifact. + +**Behavior:** + +1. Checkout repository +2. Setup Python and install dependencies +3. Run type checking command(s). +4. Upload type checking report as an artifact + +**Dependencies:** + +* :gh:`actions/checkout` +* :gh:`actions/setup-python` +* :gh:`actions/upload-artifact` + +Instantiation +************* + +Simple Example +============== + +.. code-block:: yaml + + jobs: + StaticTypeCheck: + uses: pyTooling/Actions/.github/workflows/StaticTypeCheck.yml@r0 + with: + commands: | + touch pyTooling/__init__.py + mypy --html-report htmlmypy -p pyTooling + report: 'htmlmypy' + artifact: TypeChecking + +Complex Example +=============== + +.. code-block:: yaml + + jobs: + StaticTypeCheck: + uses: pyTooling/Actions/.github/workflows/StaticTypeCheck.yml@r0 + needs: + - Params + with: + python_version: ${{ fromJson(needs.Params.outputs.params).python_version }} + commands: | + touch pyTooling/__init__.py + mypy --html-report htmlmypy -p pyTooling + report: 'htmlmypy' + artifact: ${{ fromJson(needs.Params.outputs.params).artifacts.typing }} + +Commands +======== + +Example ``commands``: + +1. Regular package + + .. code-block:: yaml + + commands: mypy --html-report htmlmypy -p ToolName + + +2. Parent namespace package + + .. code-block:: yaml + + commands: | + touch Parent/__init__.py + mypy --html-report htmlmypy -p ToolName + +3. Child namespace package + + .. code-block:: yaml + + commands: | + cd Parent + mypy --html-report ../htmlmypy -p ToolName + +Parameters +********** + +python_version +============== + +Python version. + ++----------+----------+-----------------+ +| Required | Type | Default | ++==========+==========+=================+ +| optional | string | ``3.11`` | ++----------+----------+-----------------+ + + +requirements +============ + +Python dependencies to be installed through pip. + ++----------+----------+-------------------------------+ +| Required | Type | Default | ++==========+==========+===============================+ +| optional | string | ``-r tests/requirements.txt`` | ++----------+----------+-------------------------------+ + + +report +====== + +Directory to upload as an artifact. + ++----------+----------+-----------------+ +| Required | Type | Default | ++==========+==========+=================+ +| optional | string | ``htmlmypy`` | ++----------+----------+-----------------+ + + +commands +======== + +Commands to run the static type checks. + ++----------+----------+--------------+ +| Required | Type | Default | ++==========+==========+==============+ +| yes | string | β€” β€” β€” β€” | ++----------+----------+--------------+ + +artifact +======== + +Name of the typing 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/UnitTesting.rst b/doc/JobTemplate/UnitTesting.rst new file mode 100644 index 0000000..65aa0ed --- /dev/null +++ b/doc/JobTemplate/UnitTesting.rst @@ -0,0 +1,155 @@ +.. _JOBTMPL/UnitTesting: + +UnitTesting +########### + +This template runs multiple jobs from a matrix as a cross of Python versions and systems. The summary report in junit +XML format is optionally uploaded as an artifact. + +Configuration options to ``pytest`` should be given via section ``[tool.pytest.ini_options]`` in a ``pyproject.toml`` +file. + +**Behavior:** + +1. Checkout repository +2. Setup Python and install dependencies +3. Run unit tests using ``pytest``. +4. Upload junit test summary as an artifact + +**Dependencies:** + +* :gh:`actions/checkout` +* :gh:`actions/setup-python` +* :gh:`actions/upload-artifact` + +Instantiation +************* + +Simple Example +============== + +.. code-block:: yaml + + jobs: + Params: + # ... + + UnitTesting: + uses: pyTooling/Actions/.github/workflows/UnitTesting.yml@r0 + needs: + - Params + with: + jobs: ${{ needs.Params.outputs.python_jobs }} + artifact: ${{ fromJson(needs.Params.outputs.params).artifacts.Unittesting }} + + +Complex Example +=============== + +.. code-block:: yaml + + TBD + +Parameters +********** + +jobs +==== + +JSON list with environment fields, telling the system and Python versions to run tests with. + ++----------+----------+--------------+ +| Required | Type | Default | ++==========+==========+==============+ +| yes | string | β€” β€” β€” β€” | ++----------+----------+--------------+ + +requirements +============ + +Python dependencies to be installed through pip. + ++----------+----------+---------------------------------+ +| Required | Type | Default | ++==========+==========+=================================+ +| optional | string | ``-r tests/requirements.txt`` | ++----------+----------+---------------------------------+ + + +pacboy +====== + +MSYS2 dependencies to be installed through pacboy (pacman). + ++----------+----------+-----------------------------------------------------------------+ +| Required | Type | Default | ++==========+==========+=================================================================+ +| optional | string | ``python-pip:p python-wheel:p python-coverage:p python-lxml:p`` | ++----------+----------+-----------------------------------------------------------------+ + +.. code-block:: yaml + + pacboy: >- + python-pip:p + python-wheel:p + python-coverage:p + python-lxml:p + + +mingw_requirements +================== + +Override Python dependencies to be installed through pip on MSYS2 (MINGW64) only. + ++----------+----------+----------+ +| Required | Type | Default | ++==========+==========+==========+ +| optional | string | ``""`` | ++----------+----------+----------+ + + +tests_directory +=============== + +Path to the directory containing tests (test working directory). + ++----------+----------+-----------+ +| Required | Type | Default | ++==========+==========+===========+ +| optional | string | ``tests`` | ++----------+----------+-----------+ + + +unittest_directory +================== + +Path to the directory containing unit tests (relative to tests_directory). + ++----------+----------+----------+ +| Required | Type | Default | ++==========+==========+==========+ +| optional | string | ``unit`` | ++----------+----------+----------+ + + +artifact +======== + +Generate unit test report with junitxml and upload results as an artifact. + ++----------+----------+----------+ +| 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/VerifyDocs.rst b/doc/JobTemplate/VerifyDocs.rst new file mode 100644 index 0000000..9ce0438 --- /dev/null +++ b/doc/JobTemplate/VerifyDocs.rst @@ -0,0 +1,42 @@ +.. _JOBTMPL/VerifyDocumentation: + +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. diff --git a/doc/JobTemplate/index.rst b/doc/JobTemplate/index.rst new file mode 100644 index 0000000..18503d5 --- /dev/null +++ b/doc/JobTemplate/index.rst @@ -0,0 +1,32 @@ +Overview +######## + +**Global Templates** + +* :ref:`JOBTMPL/Parameters` + +**Unit Tests, Code Coverage, ...** + +* :ref:`JOBTMPL/UnitTesting` +* :ref:`JOBTMPL/CodeCoverage` +* :ref:`JOBTMPL/StaticTypeChecking` + +**Build and Packaging** + +* :ref:`JOBTMPL/Package` + +**Documentation** + +* :ref:`JOBTMPL/VerifyDocumentation` +* :ref:`JOBTMPL/BuildTheDocs` + +**Publishing** + +* :ref:`JOBTMPL/GitHubReleasePage` +* :ref:`JOBTMPL/PyPI` +* :ref:`JOBTMPL/PublishTestResults` +* :ref:`JOBTMPL/PublishToGitHubPages` + +**Cleanups** + +* :ref:`JOBTMPL/ArtifactCleanup` diff --git a/doc/License.rst b/doc/License.rst new file mode 100644 index 0000000..7df6024 --- /dev/null +++ b/doc/License.rst @@ -0,0 +1,136 @@ +.. Note:: This is a local copy of the `Apache License Version 2.0 `_. + +Apache License 2.0 +################## + +Version 2.0, January 2004 + +**TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION** + + +1. Definitions. +=============== +**"License"** shall mean the terms and conditions for use, reproduction, and distribution as defined by Sections 1 through 9 of this document. + +**"Licensor"** shall mean the copyright owner or entity authorized by the copyright owner that is granting the License. + +**"Legal Entity"** shall mean the union of the acting entity and all other entities that control, are controlled by, or are under common control with that +entity. For the purposes of this definition, **"control"** means (i) the power, direct or indirect, to cause the direction or management of such entity, whether +by contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the outstanding shares, or (iii) beneficial ownership of such entity. + +**"You"** (or **"Your"**) shall mean an individual or Legal Entity exercising permissions granted by this License. + +**"Source"** form shall mean the preferred form for making modifications, including but not limited to software source code, documentation source, and +configuration files. + +**"Object"** form shall mean any form resulting from mechanical transformation or translation of a Source form, including but not limited to compiled object +code, generated documentation, and conversions to other media types. + +**"Work"** shall mean the work of authorship, whether in Source or Object form, made available under the License, as indicated by a copyright notice that is +included in or attached to the work (an example is provided in the Appendix below). + +**"Derivative Works"** shall mean any work, whether in Source or Object form, that is based on (or derived from) the Work and for which the editorial revisions, +annotations, elaborations, or other modifications represent, as a whole, an original work of authorship. For the purposes of this License, Derivative Works +shall not include works that remain separable from, or merely link (or bind by name) to the interfaces of, the Work and Derivative Works thereof. + +**"Contribution"** shall mean any work of authorship, including the original version of the Work and any modifications or additions to that Work or Derivative +Works thereof, that is intentionally submitted to Licensor for inclusion in the Work by the copyright owner or by an individual or Legal Entity authorized to +submit on behalf of the copyright owner. For the purposes of this definition, **"submitted"** means any form of electronic, verbal, or written communication +sent to the Licensor or its representatives, including but not limited to communication on electronic mailing lists, source code control systems, and issue +tracking systems that are managed by, or on behalf of, the Licensor for the purpose of discussing and improving the Work, but excluding communication that is +conspicuously marked or otherwise designated in writing by the copyright owner as **"Not a Contribution."** + +**"Contributor"** shall mean Licensor and any individual or Legal Entity on behalf of whom a Contribution has been received by Licensor and subsequently +incorporated within the Work. + +2. Grant of Copyright License. +============================== +Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, +irrevocable copyright license to reproduce, prepare Derivative Works of, publicly display, publicly perform, sublicense, and distribute the Work and such +Derivative Works in Source or Object form. + +3. Grant of Patent License. +=========================== +Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, +irrevocable (except as stated in this section) patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Work, where such +license applies only to those patent claims licensable by such Contributor that are necessarily infringed by their Contribution(s) alone or by combination of +their Contribution(s) with the Work to which such Contribution(s) was submitted. If You institute patent litigation against any entity (including a cross-claim +or counterclaim in a lawsuit) alleging that the Work or a Contribution incorporated within the Work constitutes direct or contributory patent infringement, then +any patent licenses granted to You under this License for that Work shall terminate as of the date such litigation is filed. + +4. Redistribution. +================== +You may reproduce and distribute copies of the Work or Derivative Works thereof in any medium, with or without modifications, and in Source or Object form, +provided that You meet the following conditions: + +* You must give any other recipients of the Work or Derivative Works a copy of this License; and +* You must cause any modified files to carry prominent notices stating that You changed the files; and +* You must retain, in the Source form of any Derivative Works that You distribute, all copyright, patent, trademark, and attribution notices from the Source + form of the Work, excluding those notices that do not pertain to any part of the Derivative Works; and +* If the Work includes a **"NOTICE"** text file as part of its distribution, then any Derivative Works that You distribute must include a readable copy of the + attribution notices contained within such NOTICE file, excluding those notices that do not pertain to any part of the Derivative Works, in at least one of the + following places: within a NOTICE text file distributed as part of the Derivative Works; within the Source form or documentation, if provided along with the + Derivative Works; or, within a display generated by the Derivative Works, if and wherever such third-party notices normally appear. The contents of the NOTICE + file are for informational purposes only and do not modify the License. You may add Your own attribution notices within Derivative Works that You distribute, + alongside or as an addendum to the NOTICE text from the Work, provided that such additional attribution notices cannot be construed as modifying the License. + +You may add Your own copyright statement to Your modifications and may provide additional or different license terms and conditions for use, reproduction, or +distribution of Your modifications, or for any such Derivative Works as a whole, provided Your use, reproduction, and distribution of the Work otherwise +complies with the conditions stated in this License. + +5. Submission of Contributions. +=============================== +Unless You explicitly state otherwise, any Contribution intentionally submitted for inclusion in the Work by You to the Licensor shall be under the terms and +conditions of this License, without any additional terms or conditions. Notwithstanding the above, nothing herein shall supersede or modify the terms of any +separate license agreement you may have executed with Licensor regarding such Contributions. + +6. Trademarks. +============== +This License does not grant permission to use the trade names, trademarks, service marks, or product names of the Licensor, except as required for reasonable +and customary use in describing the origin of the Work and reproducing the content of the NOTICE file. + +7. Disclaimer of Warranty. +========================== +Unless required by applicable law or agreed to in writing, Licensor provides the Work (and each Contributor provides its Contributions) on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, +MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are solely responsible for determining the appropriateness of using or redistributing the Work and +assume any risks associated with Your exercise of permissions under this License. + +8. Limitation of Liability. +=========================== +In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate +and grossly negligent acts) or agreed to in writing, shall any Contributor be liable to You for damages, including any direct, indirect, special, incidental, or +consequential damages of any character arising as a result of this License or out of the use or inability to use the Work (including but not limited to damages +for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if such Contributor has been +advised of the possibility of such damages. + +9. Accepting Warranty or Additional Liability. +============================================== +While redistributing the Work or Derivative Works thereof, You may choose to offer, and charge a fee for, acceptance of support, warranty, indemnity, or other +liability obligations and/or rights consistent with this License. However, in accepting such obligations, You may act only on Your own behalf and on Your sole +responsibility, not on behalf of any other Contributor, and only if You agree to indemnify, defend, and hold each Contributor harmless for any liability +incurred by, or claims asserted against, such Contributor by reason of your accepting any such warranty or additional liability. + +---------------------------------------------------------------------------------------------------------------------------------------------------------------- + +**Appendix: How to apply the Apache License to your work** + +To apply the Apache License to your work, attach the following boilerplate notice, with the fields enclosed by brackets "[]" replaced with your own identifying +information. (Don't include the brackets!) The text should be enclosed in the appropriate comment syntax for the file format. We also recommend that a file or +class name and description of purpose be included on the same "printed page" as the copyright notice for easier identification within third-party archives. + +.. code-block:: none + + Copyright [yyyy] [name of copyright owner] + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. diff --git a/doc/Makefile b/doc/Makefile new file mode 100644 index 0000000..d4bb2cb --- /dev/null +++ b/doc/Makefile @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS ?= +SPHINXBUILD ?= sphinx-build +SOURCEDIR = . +BUILDDIR = _build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/doc/Releases.rst b/doc/Releases.rst new file mode 100644 index 0000000..6d4b20b --- /dev/null +++ b/doc/Releases.rst @@ -0,0 +1,38 @@ +Releases Management +################### + +Releases +******** + +r0 +== + +Versions +******** + + +Branches +******** + + +Tagging +******* + +See context in `#5 `__. + +Tag new releases in the ``main`` branch using a semver compatible value, starting with ``v``: + +.. code-block:: bash + + git checkout main + git tag v0.0.0 + git push upstream v0.0.0 + +Move the corresponding release branch (starting with ``r``) forward by creating a merge commit, and using the merged tag +as the commit message: + +.. code-block:: bash + + git checkout r0 + git merge --no-ff -m 'v0.0.0' v0.0.0 + git push upstream r0 diff --git a/doc/TODO.rst b/doc/TODO.rst new file mode 100644 index 0000000..3144da0 --- /dev/null +++ b/doc/TODO.rst @@ -0,0 +1,4 @@ +TODOs +##### + +.. todolist:: diff --git a/doc/_static/icon.png b/doc/_static/icon.png new file mode 100644 index 0000000..79763da Binary files /dev/null and b/doc/_static/icon.png differ diff --git a/doc/_static/logo.png b/doc/_static/logo.png new file mode 100644 index 0000000..6c62cad Binary files /dev/null and b/doc/_static/logo.png differ diff --git a/doc/conf.py b/doc/conf.py new file mode 100644 index 0000000..d42c29d --- /dev/null +++ b/doc/conf.py @@ -0,0 +1,253 @@ +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +from importlib.util import find_spec +from sys import path as sys_path +from os.path import abspath +from pathlib import Path +from json import loads + +from pyTooling.Packaging import extractVersionInformation + +ROOT = Path(__file__).resolve().parent + +sys_path.insert(0, abspath(".")) +sys_path.insert(0, abspath("..")) +#sys_path.insert(0, abspath("../pyTooling")) +sys_path.insert(0, abspath("_extensions")) + + +# ============================================================================== +# Project information and versioning +# ============================================================================== +# The version info for the project you're documenting, acts as replacement for +# |version| and |release|, also used in various other places throughout the +# built documents. +project = "Actions" + +packageInformationFile = Path(f"../{project}/__init__.py") +versionInformation = extractVersionInformation(packageInformationFile) + +author = versionInformation.Author +copyright = versionInformation.Copyright +version = ".".join(versionInformation.Version.split(".")[:2]) # e.g. 2.3 The short X.Y version. +release = versionInformation.Version + + +# ============================================================================== +# Miscellaneous settings +# ============================================================================== +# The master toctree document. +master_doc = "index" + +# Add any paths that contain templates here, relative to this directory. +templates_path = ["_templates"] + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This pattern also affects html_static_path and html_extra_path. +exclude_patterns = [ + "_build", + "_theme", + "Thumbs.db", + ".DS_Store" +] + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = "manni" + + +# ============================================================================== +# Restructured Text settings +# ============================================================================== +prologPath = "prolog.inc" +try: + with open(prologPath, "r") as prologFile: + rst_prolog = prologFile.read() +except Exception as ex: + print(f"[ERROR:] While reading '{prologPath}'.") + print(ex) + rst_prolog = "" + + +# ============================================================================== +# Options for HTML output +# ============================================================================== +html_context = {} +ctx = ROOT / "context.json" +if ctx.is_file(): + html_context.update(loads(ctx.open('r').read())) + +if (ROOT / "_theme").is_dir(): + html_theme_path = ["."] + html_theme = "_theme" + html_theme_options = { + "logo_only": True, + "home_breadcrumbs": False, + "vcs_pageview_mode": 'blob', +# "body_max_width": None +# "navigation_depth": 5, + } +elif find_spec("sphinx_rtd_theme") is not None: + html_theme = "sphinx_rtd_theme" + html_theme_options = { + "logo_only": True, + "vcs_pageview_mode": 'blob', +# "navigation_depth": 5, + } +else: + html_theme = "alabaster" + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ["_static"] + +html_logo = str(Path(html_static_path[0]) / "logo.png") +html_favicon = str(Path(html_static_path[0]) / "icon.png") + +# Output file base name for HTML help builder. +htmlhelp_basename = "ActionsDoc" + +# If not None, a 'Last updated on:' timestamp is inserted at every page +# bottom, using the given strftime format. +# The empty string is equivalent to '%b %d, %Y'. +html_last_updated_fmt = "%d.%m.%Y" + +# ============================================================================== +# Python settings +# ============================================================================== +modindex_common_prefix = [ + f"{project}." +] + +# ============================================================================== +# Options for LaTeX / PDF output +# ============================================================================== +from textwrap import dedent + +latex_elements = { + # The paper size ('letterpaper' or 'a4paper'). + "papersize": "a4paper", + + # The font size ('10pt', '11pt' or '12pt'). + #'pointsize': '10pt', + + # Additional stuff for the LaTeX preamble. + "preamble": dedent(r""" + % ================================================================================ + % User defined additional preamble code + % ================================================================================ + % Add more Unicode characters for pdfLaTeX. + % - Alternatively, compile with XeLaTeX or LuaLaTeX. + % - https://GitHub.com/sphinx-doc/sphinx/issues/3511 + % + \ifdefined\DeclareUnicodeCharacter + \DeclareUnicodeCharacter{2265}{$\geq$} + \DeclareUnicodeCharacter{21D2}{$\Rightarrow$} + \fi + + + % ================================================================================ + """), + + # Latex figure (float) alignment + #'figure_align': 'htbp', +} + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, +# author, documentclass [howto, manual, or own class]). +latex_documents = [ + ( master_doc, + "Actions.tex", + "The pyTooling Actions Documentation", + "Patrick Lehmann", + "manual" + ), +] + + +# ============================================================================== +# Extensions +# ============================================================================== +extensions = [ +# Standard Sphinx extensions + "sphinx.ext.coverage", + "sphinx.ext.extlinks", + "sphinx.ext.intersphinx", + "sphinx.ext.todo", + "sphinx.ext.graphviz", + "sphinx.ext.mathjax", + "sphinx.ext.ifconfig", + "sphinx.ext.viewcode", +# SphinxContrib extensions + "sphinxcontrib.mermaid", +# Other extensions + "sphinx_fontawesome", +] + + +# ============================================================================== +# Sphinx.Ext.InterSphinx +# ============================================================================== +intersphinx_mapping = { + "python": ("https://docs.python.org/3", None), +} + + +# ============================================================================== +# Sphinx.Ext.AutoDoc +# ============================================================================== +# see: https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#configuration +#autodoc_default_options = { +# "private-members": True, +# "special-members": True, +# "inherited-members": True, +# "exclude-members": "__weakref__" +#} +#autodoc_class_signature = "separated" +autodoc_member_order = "bysource" # alphabetical, groupwise, bysource +autodoc_typehints = "both" +#autoclass_content = "both" + + +# ============================================================================== +# Sphinx.Ext.ExtLinks +# ============================================================================== +extlinks = { + "gh": ("https://GitHub.com/%s", "gh:"), + "ghissue": ("https://GitHub.com/pyTooling/Actions/issues/%s", "issue #"), + "ghpull": ("https://GitHub.com/pyTooling/Actions/pull/%s", "pull request #"), + "ghsrc": ("https://GitHub.com/pyTooling/Actions/blob/main/%s", ""), + "wiki": ("https://en.wikipedia.org/wiki/%s", ""), +} + + +# ============================================================================== +# Sphinx.Ext.Graphviz +# ============================================================================== +graphviz_output_format = "svg" + + +# ============================================================================== +# SphinxContrib.Mermaid +# ============================================================================== +mermaid_params = [ + '--backgroundColor', 'transparent', +] +mermaid_verbose = True + + +# ============================================================================== +# Sphinx.Ext.ToDo +# ============================================================================== +# If true, `todo` and `todoList` produce output, else they produce nothing. +todo_include_todos = True +todo_link_only = True + + +# ============================================================================== +# Sphinx.Ext.Coverage +# ============================================================================== +coverage_show_missing_items = True diff --git a/doc/index.rst b/doc/index.rst new file mode 100644 index 0000000..27d2adc --- /dev/null +++ b/doc/index.rst @@ -0,0 +1,179 @@ +.. include:: shields.inc + +.. raw:: latex + + \part{Introduction} + +.. only:: html + + | |SHIELD:svg:pyTooling-github| |SHIELD:svg:pyTooling-src-license| |SHIELD:svg:pyTooling-ghp-doc| |SHIELD:svg:pyTooling-doc-license| + | |SHIELD:svg:pyTooling-tag| |SHIELD:svg:pyTooling-date| + +.. Disabled shields: |SHIELD:svg:pyTooling-gitter| + +.. only:: latex + + |SHIELD:png:pyTooling-github| |SHIELD:png:pyTooling-src-license| |SHIELD:png:pyTooling-ghp-doc| |SHIELD:png:pyTooling-doc-license| + |SHIELD:png:pyTooling-tag| |SHIELD:png:pyTooling-date| + +.. Disabled shields: |SHIELD:svg:pyTooling-gitter| + +-------------------------------------------------------------------------------- + +pyTooling Actions Documentation +############################### + +**pyTooling Actions** are reusable steps and workflows for GitHub Actions easing the creation and maintenance of +workflows for Python projects on GitHub. + +Introduction +************ + +GitHub Actions workflows, actions and documentation are mostly focused on JavaScript/TypeScript as the scripting +language for writing reusable CI code. +However, Python being equally popular and capable, usage of JS/TS might be bypassed, with some caveats. +This repository gathers reusable CI tooling for testing, packaging and distributing Python projects and documentation. + + +GitHub Action Job Templates +*************************** + +**Global Templates** + +* :ref:`JOBTMPL/Parameters` + +**Unit Tests, Code Coverage, ...** + +* :ref:`JOBTMPL/UnitTesting` +* :ref:`JOBTMPL/CodeCoverage` +* :ref:`JOBTMPL/StaticTypeChecking` + +**Build and Packaging** + +* :ref:`JOBTMPL/Package` + +**Documentation** + +* :ref:`JOBTMPL/VerifyDocumentation` +* :ref:`JOBTMPL/BuildTheDocs` + +**Publishing** + +* :ref:`JOBTMPL/GitHubReleasePage` +* :ref:`JOBTMPL/PyPI` +* :ref:`JOBTMPL/PublishTestResults` +* :ref:`JOBTMPL/PublishToGitHubPages` + +**Cleanups** + +* :ref:`JOBTMPL/ArtifactCleanup` + + +Example Pipelines +================= + +``ExamplePipeline.yml`` is an example Workflow which uses all of the Reusable Workflows. +Python package/tool developers can copy it into their repos, in order to use al the reusable workflows straightaway. +Minimal required modifications are the following: + +- Set the ``name`` input of job ``Parameters``. +- Specify the ``commands`` input of job ``StaticTypeCheck``. + +Find further usage cases in the following list of projects: + +- `edaa-org/pyEDAA.ProjectModel `__ +- `edaa-org/pySVModel `__ +- `VHDL/pyVHDLModel `__ + + +GitHub Actions +************** + +* :ref:`ACTION/Releaser` +* :ref:`ACTION/WithPostStep` + +References +********** + +- `hdl/containers#48 `__ + +Contributors +************ + +* `Patrick Lehmann `__ +* `Unai Martinez-Corral `__ (Maintainer) +* `and more... `__ + + +License +******* + +.. only:: html + + This Python package (source code) is licensed under `Apache License 2.0 `__. |br| + The accompanying documentation is licensed under `Creative Commons - Attribution 4.0 (CC-BY 4.0) `__. + +.. only:: latex + + This Python package (source code) is licensed under **Apache License 2.0**. |br| + The accompanying documentation is licensed under **Creative Commons - Attribution 4.0 (CC-BY 4.0)**. + + +------------------------------------ + +.. |docdate| date:: %b %d, %Y - %H:%M + +.. only:: html + + This document was generated on |docdate|. + +.. toctree:: + :caption: Overview + :hidden: + + Background + Releases + Dependency + +.. raw:: latex + + \part{Main Documentation} + +.. toctree:: + :caption: Actions + :hidden: + + Action/index + Action/Releaser + Action/With-post-step + +.. toctree:: + :caption: Job Templates + :hidden: + + JobTemplate/index + JobTemplate/Parameters + JobTemplate/CoverageCollection + JobTemplate/UnitTesting + JobTemplate/StaticTypeCheck + JobTemplate/PublishTestResults + JobTemplate/Package + JobTemplate/PublishOnPyPI + JobTemplate/VerifyDocs + JobTemplate/BuildTheDocs + JobTemplate/PublishToGitHubPages + JobTemplate/Release + JobTemplate/ArtifactCleanUp + +.. raw:: latex + + \part{Appendix} + +.. toctree:: + :caption: Appendix + :hidden: + + License + Doc-License + genindex + TODO diff --git a/doc/make.bat b/doc/make.bat new file mode 100644 index 0000000..39e6f08 --- /dev/null +++ b/doc/make.bat @@ -0,0 +1,36 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=. +set BUILDDIR=_build +set SPHINXOPTS=-v + +if "%1" == "" goto help + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.http://sphinx-doc.org/ + exit /b 1 +) + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% + +:end +popd diff --git a/doc/prolog.inc b/doc/prolog.inc new file mode 100644 index 0000000..75463a8 --- /dev/null +++ b/doc/prolog.inc @@ -0,0 +1,59 @@ +.. # Load pre-defined aliases and graphical characters like Β© from docutils + # is used to denote the special path + # \Lib\site-packages\docutils\parsers\rst\include +.. include:: +.. include:: + +.. # define a hard line break for HTML +.. |br| raw:: html + +
+ +.. # define horizontal line for HTML +.. |hr| raw:: html + +
+ +.. # define additional CSS based styles and ReST roles for HTML +.. raw:: html + + + +.. role:: bolditalic + :class: bolditalic + +.. role:: underline + :class: underline + +.. role:: strike + :class: strike + +.. role:: xlarge + :class: xlarge + +.. role:: red + :class: colorred +.. role:: green + :class: colorgreen +.. role:: blue + :class: colorblue +.. role:: purple + :class: colorpurple + +.. role:: deletion + :class: colorred strike +.. role:: addition + :class: colorgreen + +.. role:: pycode(code) + :language: python + :class: highlight diff --git a/doc/requirements.txt b/doc/requirements.txt new file mode 100644 index 0000000..1756b55 --- /dev/null +++ b/doc/requirements.txt @@ -0,0 +1,23 @@ +-r ../requirements.txt + +pyTooling>=2.5.0 + +# Enforce latest version on ReadTheDocs +sphinx>=5.3.0 + +# Sphinx Extenstions +#sphinx.ext.coverage +#sphinxcontrib-actdiag>=0.8.5 +sphinxcontrib-mermaid>=0.7.1 +#sphinxcontrib-seqdiag>=0.8.5 +#sphinxcontrib-textstyle>=0.2.1 +#sphinxcontrib-spelling>=2.2.0 +autoapi +sphinx_fontawesome>=0.0.6 +sphinx_autodoc_typehints>=1.19.4 +# changelog>=0.3.5 + +# BuildTheDocs Extensions (mostly patched Sphinx extensions) + +# For pyTooling.Configuration.YAML documentation +ruamel.yaml>=0.17 diff --git a/doc/shields.inc b/doc/shields.inc new file mode 100644 index 0000000..039867c --- /dev/null +++ b/doc/shields.inc @@ -0,0 +1,74 @@ +.. # Use http://b64.io/ to encode any image to base64. Then replace `/` with + # `%2F` and `+` with `%2B` (or use http://meyerweb.com/eric/tools/dencoder/). + # Beware that `?logo=data:image/png;base64,` must also be converted to + # percent encoding so that the URL is properly parsed. + +.. # Sourcecode link to GitHub +.. |SHIELD:svg:pyTooling-github| image:: https://img.shields.io/badge/pyTooling-Actions-63bf7f.svg?longCache=true&style=flat-square&longCache=true&logo=GitHub + :alt: Sourcecode on GitHub + :height: 22 + :target: https://GitHub.com/pyTooling/pyTooling +.. |SHIELD:png:pyTooling-github| image:: https://raster.shields.io/badge/pyTooling-Actions-63bf7f.svg?longCache=true&style=flat-square&longCache=true&logo=GitHub + :alt: Sourcecode on GitHub + :height: 22 + :target: https://GitHub.com/pyTooling/pyTooling + +.. # Sourcecode license +.. |SHIELD:svg:pyTooling-src-license| image:: https://img.shields.io/pypi/l/pyTooling?longCache=true&style=flat-square&logo=Apache&label=code + :alt: Code license + :height: 22 + :target: Code-License.html +.. |SHIELD:png:pyTooling-src-license| image:: https://img.shields.io/pypi/l/pyTooling?longCache=true&style=flat-square&logo=Apache&label=code + :alt: Code license + :height: 22 + :target: https://GitHub.com/pyTooling/Actions/blob/main/LICENSE.md + +.. # GitHub tag +.. |SHIELD:svg:pyTooling-tag| image:: https://img.shields.io/github/v/tag/pyTooling/Actions?longCache=true&style=flat-square&logo=GitHub&include_prereleases + :alt: GitHub tag (latest SemVer incl. pre-release + :height: 22 + :target: https://GitHub.com/pyTooling/Actions/tags +.. |SHIELD:png:pyTooling-tag| image:: https://raster.shields.io/github/v/tag/pyTooling/Actions?longCache=true&style=flat-square&logo=GitHub&include_prereleases + :alt: GitHub tag (latest SemVer incl. pre-release + :height: 22 + :target: https://GitHub.com/pyTooling/Actions/tags + +.. # GitHub release date +.. |SHIELD:svg:pyTooling-date| image:: https://img.shields.io/github/release-date/pyTooling/Actions?longCache=true&style=flat-square&logo=GitHub + :alt: GitHub release date + :height: 22 + :target: https://GitHub.com/pyTooling/Actions/releases +.. |SHIELD:png:pyTooling-date| image:: https://raster.shields.io/github/release-date/pyTooling/Actions?longCache=true&style=flat-square&logo=GitHub + :alt: GitHub release date + :height: 22 + :target: https://GitHub.com/pyTooling/Actions/releases + +.. # Documentation license +.. |SHIELD:svg:pyTooling-doc-license| image:: https://img.shields.io/badge/doc-CC--BY%204.0-green?longCache=true&style=flat-square&logo=CreativeCommons&logoColor=fff + :alt: Documentation License + :height: 22 + :target: License.html +.. |SHIELD:png:pyTooling-doc-license| image:: https://raster.shields.io/badge/doc-CC--BY%204.0-green?longCache=true&style=flat-square&logo=CreativeCommons&logoColor=fff + :alt: Documentation License + :height: 22 + :target: https://GitHub.com/pyTooling/Actions/blob/main/doc/License.rst + +.. # GHPages - read now +.. |SHIELD:svg:pyTooling-ghp-doc| image:: https://img.shields.io/website?longCache=true&style=flat-square&label=pyTooling.github.io%2FpyTooling&logo=GitHub&logoColor=fff&up_color=blueviolet&up_message=Read%20now%20%E2%9E%9A&url=https%3A%2F%2FpyTooling.github.io%2FpyTooling%2Findex.html + :alt: Documentation - Read Now! + :height: 22 + :target: https://pyTooling.github.io/pyTooling/ +.. |SHIELD:png:pyTooling-ghp-doc| image:: https://raster.shields.io/website?longCache=true&style=flat-square&label=pyTooling.github.io%2FpyTooling&logo=GitHub&logoColor=fff&up_color=blueviolet&up_message=Read%20now%20%E2%9E%9A&url=https%3A%2F%2FpyTooling.github.io%2FpyTooling%2Findex.html + :alt: Documentation - Read Now! + :height: 22 + :target: https://pyTooling.github.io/pyTooling/ + +.. # Gitter +.. |SHIELD:svg:pyTooling-gitter| image:: https://img.shields.io/badge/chat-on%20gitter-4db797.svg?longCache=true&style=flat-square&logo=gitter&logoColor=e8ecef + :alt: Documentation License + :height: 22 + :target: https://gitter.im/hdl/community +.. |SHIELD:png:pyTooling-gitter| image:: https://raster.shields.io/badge/chat-on%20gitter-4db797.svg?longCache=true&style=flat-square&logo=gitter&logoColor=e8ecef + :alt: Documentation License + :height: 22 + :target: https://gitter.im/hdl/community diff --git a/requirements.txt b/requirements.txt new file mode 100644 index 0000000..e69de29