From b9bda84fc64f0e7301e6cc3c84d2fa2de1ed02f7 Mon Sep 17 00:00:00 2001 From: Patrick Lehmann Date: Thu, 26 Dec 2024 18:39:20 +0100 Subject: [PATCH] Updated README. --- README.md | 94 +++++++++++++++++++++++++++++++++++++++---------------- 1 file changed, 67 insertions(+), 27 deletions(-) diff --git a/README.md b/README.md index ef17387b..38d10909 100644 --- a/README.md +++ b/README.md @@ -10,7 +10,15 @@ This repository gathers reusable CI tooling for testing, packaging and distribut See [GitHub Actions and GitHub Reusable Workflows](https://pytooling.github.io/Actions/Background.html) for more background information. -## Reusable workflows +## Reusable Actions + +- Artifacts: + - [pyTooling/upload-artifact](https://github.com/pyTooling/upload-artifact): The upload-artifact action will preserve + file attributes like permissions. + - [pyTooling/download-artifact](https://github.com/pyTooling/download-artifact): The download-artifact action will + preserve file attributes like permissions. + +## Reusable Workflows This repository provides 10+ *Reusable Workflows* based on the CI pipelines of the repos in this GitHub organisation, [EDA²](https://github.com/edaa-org), [VHDL](https://github.com/vhdl), and others. By combining them, Python packages can @@ -23,35 +31,67 @@ Optionally, coverage and static type check reports can be gathered and integrate As shown in the screenshots above, the expected order is: -- Global: - - [Parameters](.github/workflows/Parameters.yml): a workaround for the limitations to handle global variables in - GitHub Actions workflows (see [actions/runner#480](https://github.com/actions/runner/issues/480)). - It generates outputs with artifact names and job matrices to be used in later running jobs. -- Code testing/analysis: - - [UnitTesting](.github/workflows/UnitTesting.yml): run unit test with `pytest` using multiple versions of Python, and - optionally upload results as XML reports. Configuration options to `pytest` should be given via section - `[tool.pytest.ini_options]` in a `pyproject.toml` file. - - [CoverageCollection](.github/workflows/CoverageCollection.yml): collect code coverage data (incl. branch coverage) - with `pytest`/`pytest-cov`/`coverage.py` using a single version of Python (latest). It generates HTML and Cobertura - (XML)reports, upload the HTML report as an artifact, and upload the test results to Codecov and Codacy. Configuration - options to `pytest` and `coverage.py` should be given via section `[tool.pytest.ini_options]` and `[tool.coverage.*]` - in a `pyproject.toml` file. - - [StaticTypeCheck](.github/workflows/StaticTypeCheck.yml): collect static type check result with `mypy`, and - optionally upload results as an HTML report. - Example `commands`: - - - [VerifyDocs](.github/workflows/VerifyDocs.yml): extract code examples from the README and test these code snippets. +- **Global:** + [**Parameters**](.github/workflows/Parameters.yml): It generates output parameters with artifact names and job matrices + to be used in later running jobs. + It's a workaround for the limitations to handle global variables in GitHub Actions workflows (see + [actions/runner#480](https://github.com/actions/runner/issues/480)). + + [**ExtractConfiguration**](.github/workflows/ExtractConfiguration.yml): extracts configuration values from + `pyproject.toml` and exposes configured paths and filenames as job output parameters. +- **Predefined pipelines:** + [**CompletePipeline**](.github/workflows/CompletePipeline.yml): is a predefined pipeline for typical Python projects + using all predefined job templates of pyTooling at once: (unit testing, code coverage, static typing, documentation + report generation and publishing, packaging, releasing, ...) +- **Code testing/analysis:** + [**ApplicationTesting**](.github/workflows/ApplicationTesting.yml): like UnitTesting, but running tests using an + installed Python package. + + [**UnitTesting**](.github/workflows/UnitTesting.yml): run unit test with `pytest` using multiple versions of Python, and + optionally upload results as XML reports. Configuration options to `pytest` should be given via section + `[tool.pytest.ini_options]` in a `pyproject.toml` file. + Besides test results, also code coverage data (incl. branch coverage) can be collected using + `pytest`/`pytest-cov`/`coverage.py`. Configuration options to `coverage.py` should be given via section + `[tool.coverage.*]` in a `pyproject.toml` file. + While multiple report formats can be created in the job, it's recommended to use `PublishTestResults` and/or + `PublishCoverageResults` to merge results from matrix runs and then generate final reports as XML, JSON or HTML. + Finally, reports can be published to GitHub Pages or cloud services like Codecov and Codacy. + + [**StaticTypeCheck**](.github/workflows/StaticTypeCheck.yml): collect static type check result with `mypy`, and + optionally upload results as an HTML report. + + [**VerifyDocs**](.github/workflows/VerifyDocs.yml): extract code examples from the README and test these code snippets. - Packaging and releasing: - - [Release](.github/workflows/Release.yml): publish GitHub Release. - - [Package](.github/workflows/Package.yml): generate source and wheel packages, and upload them as an artifact. - - [PublishOnPyPI](.github/workflows/PublishOnPyPI.yml): publish source and wheel packages to PyPI. - - [PublishTestResults](.github/workflows/PublishTestResults.yml): publish unit test results through GH action `dorny/test-reporter`. + [**Package**](.github/workflows/Package.yml): generate source and wheel packages, and upload them as an artifact. + + [**PublishOnPyPI**](.github/workflows/PublishOnPyPI.yml): publish source and wheel packages to PyPI. + + [**PublishTestResults**](.github/workflows/PublishTestResults.yml): publish unit test results through GH action `dorny/test-reporter`. + + [**PublishCoverageResults**](.github/workflows/PublishCoverageResults.yml): publish ucode coverage results. + + [**NightlyRelease**](.github/workflows/NightlyRelease.yml): publish GitHub Release. + + [**Release**](.github/workflows/Release.yml): publish GitHub Release. - Documentation: - - [BuildTheDocs](.github/workflows/BuildTheDocs.yml): build Sphinx documentation with BuildTheDocs, and upload HTML as - an artifact. - - [PublishToGitHubPages](.github/workflows/PublishToGitHubPages.yml): publish HTML documentation to GitHub Pages. + [SphinxDocumentation**](.github/workflows/PublishCoverageResults.yml): create HTML and LaTeX documentation using + Sphinx. + + [LaTeXDocumentation**](.github/workflows/LaTeXDocumentation.yml): compile LaTeX documentation to a PDF file using + MikTeX. + + [PublishToGitHubPages**](.github/workflows/PublishToGitHubPages.yml): publish HTML documentation to GitHub Pages. - Cleanup: - - [ArtifactCleanUp](.github/workflows/ArtifactCleanUp.yml): delete artifacts. + [**IntermediateCleanUp**](.github/workflows/IntermediateCleanUp.yml): delete intermediate artifacts. + + [**ArtifactCleanUp**](.github/workflows/ArtifactCleanUp.yml): delete artifacts. +- ⚠ Deprecated ⚠: + [**CoverageCollection**](.github/workflows/CoverageCollection.yml): Use `UnitTesting`, because is can collect code + coverage too. This avoids code duplication in job templates. + + [**BuildTheDocs**](.github/workflows/BuildTheDocs.yml): Use `SphinxDocumentation`, `LaTeXDocumentation` and + `PublishToGitHubPages`. BuildTheDocs isn't maintained anymore. + ### Example pipeline