From 57f88b158f56f68f3457aed3ee4e02733080324f Mon Sep 17 00:00:00 2001 From: Patrick Lehmann Date: Tue, 9 Sep 2025 07:48:42 +0200 Subject: [PATCH] Fine tuning documentation pages. --- .github/workflows/CompletePipeline.yml | 2 +- doc/JobTemplate/AllInOne/CompletePipeline.rst | 458 ++++++++++-------- .../Cleanup/IntermediateCleanup.rst | 3 +- doc/JobTemplate/Deprecated/BuildTheDocs.rst | 71 +-- .../Deprecated/CoverageCollection.rst | 164 +------ doc/JobTemplate/Deprecated/NightlyRelease.rst | 18 +- .../Documentation/LaTeXDocumentation.rst | 23 +- .../PublishToGitHubPages.rst | 0 .../Documentation/SphinxDocumentation.rst | 23 +- doc/JobTemplate/Documentation/VerifyDocs.rst | 42 -- doc/JobTemplate/Documentation/index.rst | 8 +- doc/JobTemplate/Package/InstallPackage.rst | 36 +- doc/JobTemplate/Package/Package.rst | 6 - doc/JobTemplate/Package/index.rst | 6 +- .../Publish/PublishCoverageResults.rst | 6 - .../Publish/PublishTestResults.rst | 11 +- doc/JobTemplate/Publish/index.rst | 2 - doc/JobTemplate/Quality/VerifyDocs.rst | 6 + doc/JobTemplate/Quality/index.rst | 6 +- .../Release/PublishReleaseNotes.rst | 5 - doc/JobTemplate/Release/TagReleaseCommit.rst | 7 - doc/JobTemplate/Release/index.rst | 4 +- .../Setup/ExtractConfiguration.rst | 14 +- doc/JobTemplate/Setup/Parameters.rst | 23 +- doc/JobTemplate/Setup/PrepareJob.rst | 46 +- .../Testing/ApplicationTesting.rst | 22 +- doc/JobTemplate/Testing/index.rst | 4 +- 27 files changed, 368 insertions(+), 648 deletions(-) rename doc/JobTemplate/{Publish => Documentation}/PublishToGitHubPages.rst (100%) delete mode 100644 doc/JobTemplate/Documentation/VerifyDocs.rst create mode 100644 doc/JobTemplate/Quality/VerifyDocs.rst diff --git a/.github/workflows/CompletePipeline.yml b/.github/workflows/CompletePipeline.yml index cf9ae86..5caf58c 100644 --- a/.github/workflows/CompletePipeline.yml +++ b/.github/workflows/CompletePipeline.yml @@ -97,7 +97,7 @@ on: description: 'Publish merged coverage and unittest reports to Codecov.' required: false default: 'false' - type: string + type: string codacy: description: 'Publish merged coverage report to Codacy.' required: false diff --git a/doc/JobTemplate/AllInOne/CompletePipeline.rst b/doc/JobTemplate/AllInOne/CompletePipeline.rst index 03fa0f5..f13f6bc 100644 --- a/doc/JobTemplate/AllInOne/CompletePipeline.rst +++ b/doc/JobTemplate/AllInOne/CompletePipeline.rst @@ -74,7 +74,218 @@ It can be used for simple Python packages as well as namespace packages. .. topic:: Behavior - .. todo:: CompletePipeline:Behavior needs documentation. + 1. Infer information from ``${{ github.ref }}`` variable. + 2. Extract Python project settings from :file:`pyproject.toml`. + 3. Compute job matrix based on system, Python version, environment, ... for job variants. + 4. Run unit tests using pytest and collect code coverage. + 5. Run platform tests using pytest and collect code coverage. + 6. Run application tests using pytest. + 7. Package code as wheel. + 8. Check documentation coverage using docstr_coverage and interrogate. + 9. Verify type annotation using static typing analysis using mypy. + 10. Merge unit test results and code coverage results. + 11. Generate HTML and LaTeX documentations using Sphinx. + 12. Translate LaTeX documentation to PDF using MikTeX. + 13. Publish unit test and code coverage results to cloud services. + 14. Publish documentation to GitHub Pages. + 15. Publish wheel to PyPI. + 16. Create a GitHub release page and upload release assets. + + +.. topic:: Pipeline Graph + + .. image:: ../../_static/pyTooling-Actions-SimplePackage.png + +.. topic:: Dependencies + + .. dropdown:: Expand List + :animate: fade-in-slide-down + :icon: codescan + :color: muted + + .. grid:: 2 + + .. grid-item:: + :columns: 6 + + * :ref:`pyTooling/Actions/.github/workflows/PrepareJob.yml ` + + * :gh:`actions/checkout` + * :gh:`GitHub command line tool 'gh' ` + + * :ref:`pyTooling/Actions/.github/workflows/Parameters.yml ` + * :ref:`pyTooling/Actions/.github/workflows/ExtractConfiguration.yml ` + + * :gh:`actions/checkout` + * :gh:`actions/setup-python` + + * :pypi:`wheel` + * :pypi:`tomli` + + * :ref:`pyTooling/Actions/.github/workflows/UnitTesting.yml ` + + * :gh:`actions/checkout` + * :gh:`msys2/setup-msys2` + * :gh:`actions/setup-python` + * :gh:`pyTooling/download-artifact` + + * :gh:`actions/download-artifact` + + * :gh:`pyTooling/upload-artifact` + + * :gh:`actions/upload-artifact` + + * apt: Packages specified via :ref:`JOBTMPL/UnitTesting/Input/apt` parameter. + * homebrew: Packages specified via :ref:`JOBTMPL/UnitTesting/Input/brew` parameter. + * MSYS2: Packages specified via :ref:`JOBTMPL/UnitTesting/Input/pacboy` parameter. + * pip + + * :pypi:`wheel` + * :pypi:`tomli` + * Python packages specified via :ref:`JOBTMPL/UnitTesting/Input/requirements` or + :ref:`JOBTMPL/UnitTesting/Input/mingw_requirements` parameter. + + * :ref:`pyTooling/Actions/.github/workflows/ApplicationTesting.yml ` + * :ref:`pyTooling/Actions/.github/workflows/CheckDocumentation.yml ` + + * :gh:`actions/checkout` + * :gh:`actions/setup-python` + * pip + + * :pypi:`docstr_coverage` + * :pypi:`interrogate` + + * :ref:`pyTooling/Actions/.github/workflows/StaticTypeCheck.yml ` + * :ref:`pyTooling/Actions/.github/workflows/Package.yml ` + + * :gh:`actions/checkout` + * :gh:`actions/setup-python` + * :gh:`pyTooling/upload-artifact` + + * :gh:`actions/upload-artifact` + + * pip + + * :pypi:`build` + * :pypi:`wheel` + + * :ref:`pyTooling/Actions/.github/workflows/PublishTestResults.yml ` + + * :gh:`actions/checkout` + * :gh:`pyTooling/download-artifact` + + * :gh:`actions/download-artifact` + + * pip + + * :pypi:`pyEDAA.Reports` + + * :gh:`dorny/test-reporter` + * :gh:`codecov/test-results-action` + * :gh:`pyTooling/upload-artifact` + + * :gh:`actions/upload-artifact` + + .. grid-item:: + :columns: 6 + + * :ref:`pyTooling/Actions/.github/workflows/PublishCoverageResults.yml ` + + * :gh:`actions/checkout` + * :gh:`pyTooling/download-artifact` + + * :gh:`actions/download-artifact` + + * pip + + * :pypi:`coverage` + * :pypi:`tomli` + + * :gh:`pyTooling/upload-artifact` + + * :gh:`actions/upload-artifact` + + * :gh:`codecov/codecov-action` + * :gh:`codacy/codacy-coverage-reporter-action` + + * :ref:`pyTooling/Actions/.github/workflows/SphinxDocumentation.yml ` + + * :gh:`actions/checkout` + * :gh:`actions/setup-python` + * :gh:`pyTooling/download-artifact` + + * :gh:`actions/download-artifact` + + * :gh:`pyTooling/upload-artifact` + + * :gh:`actions/upload-artifact` + + * apt + + * `graphviz `__ + + * pip + + * :pypi:`wheel` + * Python packages specified via :ref:`JOBTMPL/SphinxDocumentation/Input/requirements` parameter. + + * :ref:`pyTooling/Actions/.github/workflows/LaTeXDocumentation.yml ` + + * :gh:`pyTooling/download-artifact` + + * :gh:`actions/download-artifact` + + * :gh:`pyTooling/upload-artifact` + + * :gh:`actions/upload-artifact` + + * :gh:`addnab/docker-run-action` + + * :dockerhub:`pytooling/miktex ` + + * :ref:`pyTooling/Actions/.github/workflows/PublishToGitHubPages.yml ` + * :ref:`pyTooling/Actions/.github/workflows/PublishOnPyPI.yml ` + + * :gh:`pyTooling/download-artifact` + + * :gh:`actions/download-artifact` + * :gh:`actions/setup-python` + * :gh:`geekyeggo/delete-artifact` + + * pip + + * :pypi:`wheel` + * :pypi:`twine` + + * :ref:`pyTooling/Actions/.github/workflows/TagReleaseCommit.yml ` + + * :gh:`actions/github-script` + + * :ref:`pyTooling/Actions/.github/workflows/PublishReleaseNotes.yml ` + + * :gh:`actions/checkout` + * ``gh`` (GitHub command line interface) + * ``jq`` (JSON processing) + * apt + + * zstd + + * :ref:`pyTooling/Actions/.github/workflows/IntermediateCleanUp.yml ` + + * :gh:`geekyeggo/delete-artifact` + + * :ref:`pyTooling/Actions/.github/workflows/ArtifactCleanUp.yml ` + + * :gh:`geekyeggo/delete-artifact` + + +.. _JOBTMPL/CompletePipeline/Instantiation: + +Instantiation +************* + +The following instantiation example creates a ``SimplePackage`` job derived from job template ``CompletePipeline`` +version ``@r5``. It only requires the `package_name` parameter to run a full pipeline suitable for a Python project. .. grid:: 2 @@ -146,203 +357,6 @@ It can be used for simple Python packages as well as namespace packages. 🐍ModuleB.py -.. topic:: Pipeline Graph - - .. image:: ../../_static/pyTooling-Actions-SimplePackage.png - -.. topic:: Dependencies - - * :ref:`pyTooling/Actions/.github/workflows/PrepareJob.yml ` - - * :gh:`actions/checkout` - * :gh:`GitHub command line tool 'gh' ` - - * :ref:`pyTooling/Actions/.github/workflows/Parameters.yml ` - * :ref:`pyTooling/Actions/.github/workflows/ExtractConfiguration.yml ` - - * :gh:`actions/checkout` - * :gh:`actions/setup-python` - - * :pypi:`wheel` - * :pypi:`tomli` - - * :ref:`pyTooling/Actions/.github/workflows/UnitTesting.yml ` - - * :gh:`actions/checkout` - * :gh:`msys2/setup-msys2` - * :gh:`actions/setup-python` - * :gh:`pyTooling/download-artifact` - - * :gh:`actions/download-artifact` - - * :gh:`pyTooling/upload-artifact` - - * :gh:`actions/upload-artifact` - - * apt: Packages specified via :ref:`JOBTMPL/UnitTesting/Input/apt` parameter. - * homebrew: Packages specified via :ref:`JOBTMPL/UnitTesting/Input/brew` parameter. - * MSYS2: Packages specified via :ref:`JOBTMPL/UnitTesting/Input/pacboy` parameter. - * pip - - * :pypi:`wheel` - * :pypi:`tomli` - * Python packages specified via :ref:`JOBTMPL/UnitTesting/Input/requirements` or - :ref:`JOBTMPL/UnitTesting/Input/mingw_requirements` parameter. - - * :ref:`pyTooling/Actions/.github/workflows/ApplicationTesting.yml ` - * :ref:`pyTooling/Actions/.github/workflows/CheckDocumentation.yml ` - - * :gh:`actions/checkout` - * :gh:`actions/setup-python` - * pip - - * :pypi:`docstr_coverage` - * :pypi:`interrogate` - - * :ref:`pyTooling/Actions/.github/workflows/StaticTypeCheck.yml ` - * :ref:`pyTooling/Actions/.github/workflows/Package.yml ` - - * :gh:`actions/checkout` - * :gh:`actions/setup-python` - * :gh:`pyTooling/upload-artifact` - - * :gh:`actions/upload-artifact` - - * pip - - * :pypi:`build` - * :pypi:`wheel` - - * :ref:`pyTooling/Actions/.github/workflows/PublishTestResults.yml ` - - * :gh:`actions/checkout` - * :gh:`pyTooling/download-artifact` - - * :gh:`actions/download-artifact` - - * pip - - * :pypi:`pyEDAA.Reports` - - * :gh:`dorny/test-reporter` - * :gh:`codecov/test-results-action` - * :gh:`pyTooling/upload-artifact` - - * :gh:`actions/upload-artifact` - - * :ref:`pyTooling/Actions/.github/workflows/PublishCoverageResults.yml ` - - * :gh:`actions/checkout` - * :gh:`pyTooling/download-artifact` - - * :gh:`actions/download-artifact` - - * pip - - * :pypi:`coverage` - * :pypi:`tomli` - - * :gh:`pyTooling/upload-artifact` - - * :gh:`actions/upload-artifact` - - * :gh:`codecov/codecov-action` - * :gh:`codacy/codacy-coverage-reporter-action` - - * :ref:`pyTooling/Actions/.github/workflows/SphinxDocumentation.yml ` - - * :gh:`actions/checkout` - * :gh:`actions/setup-python` - * :gh:`pyTooling/download-artifact` - - * :gh:`actions/download-artifact` - - * :gh:`pyTooling/upload-artifact` - - * :gh:`actions/upload-artifact` - - * apt - - * `graphviz `__ - - * pip - - * :pypi:`wheel` - * Python packages specified via :ref:`JOBTMPL/SphinxDocumentation/Input/requirements` parameter. - - * :ref:`pyTooling/Actions/.github/workflows/LaTeXDocumentation.yml ` - - * :gh:`pyTooling/download-artifact` - - * :gh:`actions/download-artifact` - - * :gh:`pyTooling/upload-artifact` - - * :gh:`actions/upload-artifact` - - * :gh:`addnab/docker-run-action` - - * :dockerhub:`pytooling/miktex ` - - * :ref:`pyTooling/Actions/.github/workflows/PublishToGitHubPages.yml ` - * :ref:`pyTooling/Actions/.github/workflows/PublishOnPyPI.yml ` - - * :gh:`pyTooling/download-artifact` - - * :gh:`actions/download-artifact` - * :gh:`actions/setup-python` - * :gh:`geekyeggo/delete-artifact` - - * pip - - * :pypi:`wheel` - * :pypi:`twine` - - * :ref:`pyTooling/Actions/.github/workflows/TagReleaseCommit.yml ` - - * :gh:`actions/github-script` - - * :ref:`pyTooling/Actions/.github/workflows/PublishReleaseNotes.yml ` - - * :gh:`actions/checkout` - * ``gh`` (GitHub command line interface) - * ``jq`` (JSON processing) - * apt - - zstd - - * :ref:`pyTooling/Actions/.github/workflows/IntermediateCleanUp.yml ` - - * :gh:`geekyeggo/delete-artifact` - - * :ref:`pyTooling/Actions/.github/workflows/ArtifactCleanUp.yml ` - - * :gh:`geekyeggo/delete-artifact` - - -.. _JOBTMPL/CompletePipeline/Instantiation: - -Instantiation -************* - -The following instantiation example creates a ``Params`` job derived from job template ``Parameters`` version ``@r5``. -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/CompletePipeline.yml@r5 - with: - package_name: myPackage - - .. _JOBTMPL/CompletePipeline/Parameters: Parameter Summary @@ -563,7 +577,10 @@ unittest_include_list :Required: no :Default Value: ``''`` :Possible Values: A space separated list of ``:`` tuples. -:Description: +:Description: List of space-separated ``:`` tuples to be included into the list of unittest + variants. + + For more details see :ref:`JOBTMPL/Parameters/Input/include_list`. .. _JOBTMPL/CompletePipeline/Input/unittest_exclude_list: @@ -575,7 +592,10 @@ unittest_exclude_list :Required: no :Default Value: ``'windows-arm:3.9 windows-arm:3.10'`` :Possible Values: A space separated list of ``:`` tuples. -:Description: +:Description: List of space-separated ``:`` tuples to be excluded from the list of unittest + variants. + + For more details see :ref:`JOBTMPL/Parameters/Input/exclude_list`. .. _JOBTMPL/CompletePipeline/Input/unittest_disable_list: @@ -587,7 +607,11 @@ unittest_disable_list :Required: no :Default Value: ``'windows-arm:pypy-3.10 windows-arm:pypy-3.11'`` :Possible Values: A space separated list of ``:`` tuples. -:Description: +:Description: List of space-separated ``:`` tuples to be temporarily disabled from the list + of unittest variants. |br| + Each disabled item creates a warning in the workflow log. + + For more details see :ref:`JOBTMPL/Parameters/Input/disable_list`. .. _JOBTMPL/CompletePipeline/Input/apptest_python_version: @@ -649,7 +673,10 @@ apptest_include_list :Required: no :Default Value: ``''`` :Possible Values: A space separated list of ``:`` tuples. -:Description: +:Description: List of space-separated ``:`` tuples to be included into the list of + application test variants. + + For more details see :ref:`JOBTMPL/Parameters/Input/include_list`. .. _JOBTMPL/CompletePipeline/Input/apptest_exclude_list: @@ -661,7 +688,10 @@ apptest_exclude_list :Required: no :Default Value: ``'windows-arm:3.9 windows-arm:3.10'`` :Possible Values: A space separated list of ``:`` tuples. -:Description: +:Description: List of space-separated ``:`` tuples to be excluded from the list of + appliation test variants. + + For more details see :ref:`JOBTMPL/Parameters/Input/exclude_list`. .. _JOBTMPL/CompletePipeline/Input/apptest_disable_list: @@ -673,7 +703,11 @@ apptest_disable_list :Required: no :Default Value: ``'windows-arm:pypy-3.10 windows-arm:pypy-3.11'`` :Possible Values: A space separated list of ``:`` tuples. -:Description: +:Description: List of space-separated ``:`` tuples to be temporarily disabled from the list + of application test variants. |br| + Each disabled item creates a warning in the workflow log. + + For more details see :ref:`JOBTMPL/Parameters/Input/disable_list`. .. _JOBTMPL/CompletePipeline/Input/codecov: @@ -685,7 +719,8 @@ codecov :Required: no :Default Value: ``'false'`` :Possible Values: ``'true'``, ``'false'`` -:Description: +:Description: If *true*, publish merged code coverage results and a merged unit test summary to CodeCov. |br| + Secret :ref:`JOBTMPL/CompletePipeline/Secret/CODECOV_TOKEN` must be set. .. _JOBTMPL/CompletePipeline/Input/codacy: @@ -697,7 +732,8 @@ codacy :Required: no :Default Value: ``'false'`` :Possible Values: ``'true'``, ``'false'`` -:Description: +:Description: If *true*, publish merged code coverage results to Codacy. |br| + Secret :ref:`JOBTMPL/CompletePipeline/Secret/CODACY_TOKEN` must be set. .. _JOBTMPL/CompletePipeline/Input/dorny: @@ -709,7 +745,7 @@ dorny :Required: no :Default Value: ``'false'`` :Possible Values: ``'true'``, ``'false'`` -:Description: +:Description: If *true*, publish a merged unit test summary as pipeline result. .. _JOBTMPL/CompletePipeline/Input/cleanup: @@ -721,7 +757,8 @@ cleanup :Required: no :Default Value: ``'true'`` :Possible Values: ``'true'``, ``'false'`` -:Description: +:Description: If *false*, do not remove intermediate artifacts. |br| + This might help debugging artifact handovers between jobs. .. _JOBTMPL/CompletePipeline/Secrets: @@ -780,5 +817,6 @@ Optimizations The following optimizations can be used to reduce the template's runtime. -TBD - tbd tbd tbd +.. todo:: + + CompletePipeline::Optimizations Needs a list of optimizations. diff --git a/doc/JobTemplate/Cleanup/IntermediateCleanup.rst b/doc/JobTemplate/Cleanup/IntermediateCleanup.rst index d5d2840..246fc53 100644 --- a/doc/JobTemplate/Cleanup/IntermediateCleanup.rst +++ b/doc/JobTemplate/Cleanup/IntermediateCleanup.rst @@ -51,7 +51,8 @@ requires a `name` parameter to create the artifact names. .. seealso:: :ref:`JOBTMPL/ArtifactCleanup` - ``ArtifactCleanup`` is usualy + ``ArtifactCleanup`` is used to remove artifacts like unit test report artifacts after artifact's content has been + (post-)processed or published. .. _JOBTMPL/IntermediateCleanUp/Parameters: diff --git a/doc/JobTemplate/Deprecated/BuildTheDocs.rst b/doc/JobTemplate/Deprecated/BuildTheDocs.rst index 24a8867..4fe76eb 100644 --- a/doc/JobTemplate/Deprecated/BuildTheDocs.rst +++ b/doc/JobTemplate/Deprecated/BuildTheDocs.rst @@ -3,73 +3,8 @@ BuildTheDocs ############ -This jobs compiles the documentation written in ReStructured Text with Sphinx using BuildTheDocs. +.. attention:: -**Behavior:** + The ``BuildTheDocs`` job template is deprecated. -1. Checkout repository. -2. Build the documentation. -3. Upload the HTML documentation as an artifact. -4. Publish the HTML documentation to GitHub Pages. - -**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@r5 - - -Complex Example -=============== - -.. code-block:: yaml - - jobs: - BuildTheDocs: - uses: pyTooling/Actions/.github/workflows/BuildTheDocs.yml@r5 - needs: - - Params - with: - artifact: ${{ fromJson(needs.Params.outputs.artifact_names).documentation_html }} - - -Parameters -********** - -artifact -======== - -+----------------+----------+----------+--------------+ -| Parameter Name | Required | Type | Default | -+================+==========+==========+==============+ -| artifact | optional | string | ``""`` | -+----------------+----------+----------+--------------+ - -Name of the documentation artifact. - -If no artifact name is given, the job directly publishes the documentation's HTML content to GitHub Pages. - - -Secrets -******* - -This job template needs no secrets. - -Results -******* - -This job template has no output parameters. + See :ref:`JOBTMPL/SphinxDocumentation` and :ref:`JOBTMPL/LaTeXDocumentation`. diff --git a/doc/JobTemplate/Deprecated/CoverageCollection.rst b/doc/JobTemplate/Deprecated/CoverageCollection.rst index 6d9d976..45a0d01 100644 --- a/doc/JobTemplate/Deprecated/CoverageCollection.rst +++ b/doc/JobTemplate/Deprecated/CoverageCollection.rst @@ -3,166 +3,8 @@ CoverageCollection ################## -This jobs runs the specified unit tests with activated code coverage collection (incl. branch coverage). +.. attention:: -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 `__. + The ``CoverageCollection`` job template is deprecated. -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@r5 - with: - artifact: Coverage - secrets: inherit - -Complex Example -=============== - -.. code-block:: yaml - - jobs: - Coverage: - uses: pyTooling/Actions/.github/workflows/CoverageCollection.yml@r5 - needs: - - Params - with: - python_version: ${{ needs.Params.outputs.python_version }} - artifact: ${{ fromJson(needs.Params.outputs.artifact_names).codecoverage_html }} - secrets: inherit - -Parameters -********** - -python_version -============== - -+----------------+----------+----------+----------+ -| Parameter Name | Required | Type | Default | -+================+==========+==========+==========+ -| python_version | optional | string | 3.11 | -+----------------+----------+----------+----------+ - -Python version used for running unit tests. - - -requirements -============ - -+----------------+----------+----------+-------------------------------+ -| Parameter Name | Required | Type | Default | -+================+==========+==========+===============================+ -| requirements | optional | string | ``-r tests/requirements.txt`` | -+----------------+----------+----------+-------------------------------+ - -Python dependencies to be installed through pip. - - -tests_directory -=============== - -+-----------------+----------+----------+-----------+ -| Parameter Name | Required | Type | Default | -+=================+==========+==========+===========+ -| tests_directory | optional | string | ``tests`` | -+-----------------+----------+----------+-----------+ - -Path to the directory containing tests (test working directory). - - -unittest_directory -================== - -+--------------------+----------+----------+-----------+ -| Parameter Name | Required | Type | Default | -+====================+==========+==========+===========+ -| unittest_directory | optional | string | ``unit`` | -+--------------------+----------+----------+-----------+ - -Path to the directory containing unit tests (relative to tests_directory). - - -coverage_config -=============== - -+-----------------+----------+----------+--------------------+ -| Parameter Name | Required | Type | Default | -+=================+==========+==========+====================+ -| coverage_config | optional | string | ``pyproject.toml`` | -+-----------------+----------+----------+--------------------+ - -Path to the ``.coveragerc`` file. Use ``pyproject.toml`` by default. - - -artifact -======== - -+----------------+----------+----------+--------------+ -| Parameter Name | Required | Type | Default | -+================+==========+==========+==============+ -| artifact | yes | string | β€” β€” β€” β€” | -+----------------+----------+----------+--------------+ - -Name of the coverage artifact. - - -Secrets -******* - -codacy_token -============ - -+----------------+----------+----------+--------------+ -| Secret Name | Required | Type | Default | -+================+==========+==========+==============+ -| codacy_token | yes | string | β€” β€” β€” β€” | -+----------------+----------+----------+--------------+ - -Token to push result to codacy. - - -Results -******* - -This job template has no output parameters. + See :ref:`JOBTMPL/UnitTesting` and :ref:`JOBTMPL/PublishCoverageResults`. diff --git a/doc/JobTemplate/Deprecated/NightlyRelease.rst b/doc/JobTemplate/Deprecated/NightlyRelease.rst index 54e850a..5c0f5b3 100644 --- a/doc/JobTemplate/Deprecated/NightlyRelease.rst +++ b/doc/JobTemplate/Deprecated/NightlyRelease.rst @@ -3,20 +3,8 @@ NightlyRelease ############## -.. todo:: NightlyRelease:Needs documentation. +.. attention:: -**Behavior:** + The ``NightlyRelease`` job template is deprecated. -.. todo:: NightlyRelease:Behavior needs documentation. - -**Dependencies:** - -.. todo:: NightlyRelease:Dependencies needs documentation. - -Instantiation -************* - -Simple Example -============== - -.. todo:: NightlyRelease:Simple example needs documentation. + See :ref:`JOBTMPL/PublishReleaseNotes`. diff --git a/doc/JobTemplate/Documentation/LaTeXDocumentation.rst b/doc/JobTemplate/Documentation/LaTeXDocumentation.rst index c0e4187..064a00f 100644 --- a/doc/JobTemplate/Documentation/LaTeXDocumentation.rst +++ b/doc/JobTemplate/Documentation/LaTeXDocumentation.rst @@ -3,9 +3,11 @@ LatexDocumentation ################## -The ``LatexDocumentation`` job template ................ +The ``LatexDocumentation`` job template downloads an artifact containing a LaTeX document and translates to a PDF file +using MikTeX. -* uses xelatex and latexmk +The translation process uses ``latexmk`` for handling multiple passes. The default LaTeX processor is ``xelatex``, but +can be switched by a parameter. .. topic:: Features @@ -13,12 +15,9 @@ The ``LatexDocumentation`` job template ................ .. topic:: Behavior - .. todo:: LatexDocumentation:Behavior needs documentation. - -.. topic:: Job Execution - - .. image:: ../../_static/pyTooling-Actions-LatexDocumentation.png - :width: 600px + 1. Download the LaTeX artifact. + 2. Build the PDF using ``latexmk``. + 3. Upload the generated PDF as an artifact. .. topic:: Dependencies @@ -40,9 +39,6 @@ The ``LatexDocumentation`` job template ................ Instantiation ************* -The following instantiation example creates a ``Params`` job derived from job template ``Parameters`` version ``@r5``. It only -requires a `name` parameter to create the artifact names. - .. code-block:: yaml name: Pipeline @@ -77,11 +73,6 @@ requires a `name` parameter to create the artifact names. pdf_artifact: ${{ fromJson(needs.UnitTestingParams.outputs.artifact_names).documentation_pdf }} -.. seealso:: - - :ref:`JOBTMPL/TagReleaseCommit` - ``LatexDocumentation`` is usualy - .. _JOBTMPL/LatexDocumentation/Parameters: Parameter Summary diff --git a/doc/JobTemplate/Publish/PublishToGitHubPages.rst b/doc/JobTemplate/Documentation/PublishToGitHubPages.rst similarity index 100% rename from doc/JobTemplate/Publish/PublishToGitHubPages.rst rename to doc/JobTemplate/Documentation/PublishToGitHubPages.rst diff --git a/doc/JobTemplate/Documentation/SphinxDocumentation.rst b/doc/JobTemplate/Documentation/SphinxDocumentation.rst index 7b69015..10600ea 100644 --- a/doc/JobTemplate/Documentation/SphinxDocumentation.rst +++ b/doc/JobTemplate/Documentation/SphinxDocumentation.rst @@ -3,7 +3,8 @@ SphinxDocumentation ################### -The ``SphinxDocumentation`` job template .......... +The ``SphinxDocumentation`` job template compiles the ReStructured Text documentation using Sphinx to an HTML website +and a LaTeX documentation. This LaTeX document can be translated using e.g. MikTeX to a PDF file. .. topic:: Features @@ -20,7 +21,17 @@ The ``SphinxDocumentation`` job template .......... .. topic:: Behavior - .. todo:: SphinxDocumentation:Behavior needs documentation. + 1. Checkout repository. + 2. Install system dependencies. + 3. Setup Python environment and install Python dependencies. + 4. Download optional artifacts for integration of futher reports into the documentation. + 5. Build the HTML documentation using Sphinx. + 6. Build the LaTeX documentation using Sphinx. + + 1. Apply LaTeX workaround I. + 2. Apply LaTeX workaround II. + + 7. Upload the HTML and LaTeX artifacts. .. topic:: Job Execution @@ -54,9 +65,6 @@ The ``SphinxDocumentation`` job template .......... Instantiation ************* -The following instantiation example creates a ``Params`` job derived from job template ``Parameters`` version ``@r5``. It only -requires a `name` parameter to create the artifact names. - .. code-block:: yaml name: Pipeline @@ -81,11 +89,6 @@ requires a `name` parameter to create the artifact names. latex_artifact: ${{ fromJson(needs.UnitTestingParams.outputs.artifact_names).documentation_latex }} -.. seealso:: - - :ref:`JOBTMPL/TagReleaseCommit` - ``SphinxDocumentation`` is usualy - .. _JOBTMPL/SphinxDocumentation/Parameters: Parameter Summary diff --git a/doc/JobTemplate/Documentation/VerifyDocs.rst b/doc/JobTemplate/Documentation/VerifyDocs.rst deleted file mode 100644 index 535021a..0000000 --- a/doc/JobTemplate/Documentation/VerifyDocs.rst +++ /dev/null @@ -1,42 +0,0 @@ -.. _JOBTMPL/VerifyDocs: - -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/Documentation/index.rst b/doc/JobTemplate/Documentation/index.rst index e923b85..b3d6d39 100644 --- a/doc/JobTemplate/Documentation/index.rst +++ b/doc/JobTemplate/Documentation/index.rst @@ -5,13 +5,13 @@ Documentation The category *documentation* provides workflow templates implementing -* :ref:`JOBTMPL/VerifyDocs` - -* :ref:`JOBTMPL/SphinxDocumentation` - -* :ref:`JOBTMPL/LaTeXDocumentation` - +* :ref:`JOBTMPL/SphinxDocumentation` - Translate ReStructured Text to HTML and LaTeX using Sphinx. +* :ref:`JOBTMPL/LaTeXDocumentation` - Translate LaTeX to PDF using MikTeX. +* :ref:`JOBTMPL/PublishToGitHubPages` - Upload HTML content to GitHub Pages. .. toctree:: :hidden: - VerifyDocs SphinxDocumentation LaTeXDocumentation + PublishToGitHubPages diff --git a/doc/JobTemplate/Package/InstallPackage.rst b/doc/JobTemplate/Package/InstallPackage.rst index bd8af99..f97b5db 100644 --- a/doc/JobTemplate/Package/InstallPackage.rst +++ b/doc/JobTemplate/Package/InstallPackage.rst @@ -42,28 +42,9 @@ the installation is verified. This aims for packaging and dependency mistakes in Instantiation ************* -The following instantiation example creates a ``Params`` job derived from job template ``Parameters`` version ``@r5``. It only -requires a `name` parameter to create the artifact names. +.. todo:: -.. code-block:: yaml - - name: Pipeline - - on: - push: - workflow_dispatch: - - jobs: - Params: - uses: pyTooling/Actions/.github/workflows/ExtractConfiguration.yml@r5 - with: - name: pyTooling - - -.. seealso:: - - :ref:`JOBTMPL/Package` - ``InstallPackage`` is usualy + InstallPackage:: Needs instantiation instructions. .. _JOBTMPL/InstallPackage/Parameters: @@ -73,11 +54,9 @@ Parameter Summary .. rubric:: Goto :ref:`input parameters ` -+---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ -| Parameter Name | Required | Type | Default | -+=====================================================================+==========+==========+===================================================================+ -| :ref:`JOBTMPL/InstallPackage/Input/ubuntu_image` | no | string | ``'ubuntu-24.04'`` | -+---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ +.. todo:: + + InstallPackage:: Needs a parameter list. .. rubric:: Goto :ref:`secrets ` @@ -93,10 +72,9 @@ This job template has no output parameters. Input Parameters **************** -.. _JOBTMPL/InstallPackage/Input/ubuntu_image: +.. todo:: -ubuntu_image -============ + InstallPackage:: Needs input parameter descriptions. .. _JOBTMPL/InstallPackage/Secrets: diff --git a/doc/JobTemplate/Package/Package.rst b/doc/JobTemplate/Package/Package.rst index f295909..7603adb 100644 --- a/doc/JobTemplate/Package/Package.rst +++ b/doc/JobTemplate/Package/Package.rst @@ -24,7 +24,6 @@ as an artifact. * If parameter :ref:`JOBTMPL/Package/Input/requirements` is non-empty, use :pypi:`setuptools` for package and execute ``python setup.py ...``. - .. topic:: Job Execution .. image:: ../../_static/pyTooling-Actions-Package.png @@ -77,11 +76,6 @@ Complex Example artifact: ${{ fromJson(needs.Params.outputs.artifact_names).package_all }} -.. seealso:: - - :ref:`JOBTMPL/PublishOnPyPI` - - .. _JOBTMPL/Package/Parameters: Parameter Summary diff --git a/doc/JobTemplate/Package/index.rst b/doc/JobTemplate/Package/index.rst index fa610ee..293a168 100644 --- a/doc/JobTemplate/Package/index.rst +++ b/doc/JobTemplate/Package/index.rst @@ -5,9 +5,9 @@ Packaging The category *packaging* provides workflow templates implementing -* :ref:`JOBTMPL/Package` - -* :ref:`JOBTMPL/InstallPackage` - -* :ref:`JOBTMPL/PublishOnPyPI` - +* :ref:`JOBTMPL/Package` - Package Python packages and modules as wheel. +* :ref:`JOBTMPL/InstallPackage` - Install Python package (wheel) on target platforms. +* :ref:`JOBTMPL/PublishOnPyPI` - Upload Python package (wheel) to PyPI. .. toctree:: :hidden: diff --git a/doc/JobTemplate/Publish/PublishCoverageResults.rst b/doc/JobTemplate/Publish/PublishCoverageResults.rst index 80afeb9..5865b77 100644 --- a/doc/JobTemplate/Publish/PublishCoverageResults.rst +++ b/doc/JobTemplate/Publish/PublishCoverageResults.rst @@ -116,12 +116,6 @@ The following CODACY_TOKEN: ${{ secrets.CODACY_TOKEN }} -.. seealso:: - - :ref:`JOBTMPL/UnitTesting` - ``UnitTesting`` is usualy - - .. _JOBTMPL/PublishCoverageResults/Parameters: Parameter Summary diff --git a/doc/JobTemplate/Publish/PublishTestResults.rst b/doc/JobTemplate/Publish/PublishTestResults.rst index ff8f4ce..bd0747d 100644 --- a/doc/JobTemplate/Publish/PublishTestResults.rst +++ b/doc/JobTemplate/Publish/PublishTestResults.rst @@ -8,7 +8,7 @@ JUnit test summary reports to multiple services for visualization and longterm s Supported services are: -* GitHub Actions - Job results using :gh:`dorny/test-reporter` +* GitHub Actions job results using :gh:`dorny/test-reporter` * `Codecov `__ .. topic:: Features @@ -99,13 +99,6 @@ Complex Example - CodeCoverage - UnitTesting -.. seealso:: - - :ref:`JOBTMPL/UnitTesting` - tbd - :ref:`JOBTMPL/PublishCoverageResults` - tbd - .. _JOBTMPL/PublishTestResults/Parameters: @@ -343,5 +336,3 @@ Optimizations ************* This template offers no optimizations (reduced job runtime). - -merged_junit_artifact diff --git a/doc/JobTemplate/Publish/index.rst b/doc/JobTemplate/Publish/index.rst index 16e1c0f..65e8a50 100644 --- a/doc/JobTemplate/Publish/index.rst +++ b/doc/JobTemplate/Publish/index.rst @@ -7,11 +7,9 @@ The category *publish* provides workflow templates implementing * :ref:`JOBTMPL/PublishTestResults` - * :ref:`JOBTMPL/PublishCoverageResults` - -* :ref:`JOBTMPL/PublishToGitHubPages` - .. toctree:: :hidden: PublishTestResults PublishCoverageResults - PublishToGitHubPages diff --git a/doc/JobTemplate/Quality/VerifyDocs.rst b/doc/JobTemplate/Quality/VerifyDocs.rst new file mode 100644 index 0000000..f85eb83 --- /dev/null +++ b/doc/JobTemplate/Quality/VerifyDocs.rst @@ -0,0 +1,6 @@ +.. _JOBTMPL/VerifyDocs: + +VerifyDocs (idea) +################# + +.. todo:: VerifyDocs:: Needs documentation. diff --git a/doc/JobTemplate/Quality/index.rst b/doc/JobTemplate/Quality/index.rst index 11a8158..dcfca99 100644 --- a/doc/JobTemplate/Quality/index.rst +++ b/doc/JobTemplate/Quality/index.rst @@ -5,11 +5,13 @@ Quality The category *quality* provides workflow templates implementing -* :ref:`JOBTMPL/CheckDocumentation` - -* :ref:`JOBTMPL/StaticTypeCheck` - +* :ref:`JOBTMPL/VerifyDocs` - Verify code snippets in documentations for correctness. +* :ref:`JOBTMPL/CheckDocumentation` - Check documentation coverage in Python modules. +* :ref:`JOBTMPL/StaticTypeCheck` - Check type annotations using mypy. .. toctree:: :hidden: + VerifyDocs StaticTypeCheck CheckDocumentation diff --git a/doc/JobTemplate/Release/PublishReleaseNotes.rst b/doc/JobTemplate/Release/PublishReleaseNotes.rst index f191378..df0152f 100644 --- a/doc/JobTemplate/Release/PublishReleaseNotes.rst +++ b/doc/JobTemplate/Release/PublishReleaseNotes.rst @@ -75,11 +75,6 @@ Instantiation tag: ${{ needs.Prepare.outputs.version }} secrets: inherit -.. seealso:: - - :ref:`JOBTMPL/TagReleaseCommit` - ``TagReleaseCommit`` is - .. _JOBTMPL/PublishReleaseNotes/ReleaseNotes: diff --git a/doc/JobTemplate/Release/TagReleaseCommit.rst b/doc/JobTemplate/Release/TagReleaseCommit.rst index 468737c..6476db9 100644 --- a/doc/JobTemplate/Release/TagReleaseCommit.rst +++ b/doc/JobTemplate/Release/TagReleaseCommit.rst @@ -88,13 +88,6 @@ other reason. Its outputs are used to either run a ``TriggerTaggedRelease`` job tag: ${{ needs.Prepare.outputs.version }} secrets: inherit -.. seealso:: - - :ref:`JOBTMPL/PrepareJob` - ``PrepareJob`` ... - :ref:`JOBTMPL/PublishReleaseNotes` - ``PublishReleaseNotes`` ... - .. _JOBTMPL/TagReleaseCommit/Parameters: diff --git a/doc/JobTemplate/Release/index.rst b/doc/JobTemplate/Release/index.rst index b416466..3f04fd0 100644 --- a/doc/JobTemplate/Release/index.rst +++ b/doc/JobTemplate/Release/index.rst @@ -5,8 +5,8 @@ Release The category *release* provides workflow templates implementing -* :ref:`JOBTMPL/TagReleaseCommit` - -* :ref:`JOBTMPL/PublishReleaseNotes` - +* :ref:`JOBTMPL/TagReleaseCommit` - Automatically tag current commit in Git using the associate pull-requests title. +* :ref:`JOBTMPL/PublishReleaseNotes` - Create GitHub release page and upload release assets. .. toctree:: :hidden: diff --git a/doc/JobTemplate/Setup/ExtractConfiguration.rst b/doc/JobTemplate/Setup/ExtractConfiguration.rst index 0cdbf9f..d7f3ed5 100644 --- a/doc/JobTemplate/Setup/ExtractConfiguration.rst +++ b/doc/JobTemplate/Setup/ExtractConfiguration.rst @@ -3,8 +3,9 @@ ExtractConfiguration #################### -The ``ExtractConfiguration`` job template is a ..... - +The ``ExtractConfiguration`` job template extracts Python project settings from :file:`pyproject.toml` and shares the +values via output parameters with other jobs. Thus, only a single centralized implementation is needed to avoid code +duplications within jobs. .. topic:: Features @@ -21,7 +22,14 @@ The ``ExtractConfiguration`` job template is a ..... .. topic:: Behavior - .. todo:: ExtractConfiguration:Behavior needs documentation. + 1. Checkout repository. + 2. Install Python dependencies. + 3. Compute the full package name and the package source directory. + 4. Read :file:`pyproject.toml` and extract settings for: + + * pytest + * Coverage.py + * pyEDAA.Reports .. topic:: Job Execution diff --git a/doc/JobTemplate/Setup/Parameters.rst b/doc/JobTemplate/Setup/Parameters.rst index 6a8ac20..c90526e 100644 --- a/doc/JobTemplate/Setup/Parameters.rst +++ b/doc/JobTemplate/Setup/Parameters.rst @@ -6,14 +6,27 @@ 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. +It generates output parameters containing a list of artifact names and a job matrix to be used in later running jobs. .. topic:: Features - * Generate names for various artifacts. - * Generate a matrix of job combinations made from systems, Python versions and environments as a JSON string. + * Generate artifact names for various artifacts. + * Generate a matrix of job combinations as a JSON string made from: + + * systems (Ubuntu, macOS, Windows) + * architecture (x64-64, aarch64) + * Python versions (3.9, 3.10, ..., 3.13), + * Python implementation (CPython, PyPy), and + * environments (Native, MinGW64, UCRT64, ...). + * Provide a (default) Python version for other jobs. +.. topic:: Behavior + + 1. Delay job execution by :ref:`JOBTMPL/Parameters/Input/pipeline-delay` seconds. + 2. Compute job matrix using an embedded Python script. + 3. Assemble artifact names using a common prefix derived from Python namespace and package name. + .. topic:: Job Execution .. image:: ../../_static/pyTooling-Actions-Parameters.png @@ -430,8 +443,8 @@ disable_list :Possible Values: A space separated list of ``:`` tuples. :Description: List of space-separated ``:`` tuples to be temporarily disabled from the list of test variants. |br| - Each disabled item creates a warning in the workflow log: -:Example: + Each disabled item creates a warning in the workflow log. +:Warning Example: .. code-block:: yaml jobs: diff --git a/doc/JobTemplate/Setup/PrepareJob.rst b/doc/JobTemplate/Setup/PrepareJob.rst index b11cff4..edbec9a 100644 --- a/doc/JobTemplate/Setup/PrepareJob.rst +++ b/doc/JobTemplate/Setup/PrepareJob.rst @@ -13,7 +13,7 @@ The job template generates various output parameters derived from .. topic:: Features * Provide branch name or tag name from ``${{ github.ref }}`` variable. - * Check if pipeline is a branch or tag pipeline. + * Check if pipeline is a branch, tag or pull-request pipeline. * Check if a commit is a merge commit. * Check if a commit is a release commit. * Check if a tag is a nightly tag (rolling release tag). @@ -21,23 +21,30 @@ The job template generates various output parameters derived from * Find associated pull-request (PR) for a merge commit/release commit. * Provide a version from tag name or pull-request name. -.. note:: + .. note:: - Due to GitHub Action's broken type system and missing implicit type conversions in YAML files, *boolean* values need - to be returned as *string* values otherwise type compatibility and comparison are broken. This also requires all - inputs to be *string* parameters, otherwise step's, job's or template's output cannot be assigned to a template's - input. + Due to GitHub Action's broken type system and missing implicit type conversions in YAML files, *boolean* values need + to be returned as *string* values otherwise type compatibility and comparison are broken. This also requires all + inputs to be *string* parameters, otherwise step's, job's or template's output cannot be assigned to a template's + input. - **Problems:** + **Problems:** - 1. Scripts (Bash, Python, ...) return results as strings. There is no option or operation provided by GitHub Actions - to convert outputs of ``printf`` to a ``boolean`` in the YAML file. - 2. Unlike job template inputs, outputs have no type information. These are all considered *string* values. Again no - implicit or explicit type conversion is provided. - 3. While inputs might be defined as ``boolean`` and a matching default can be set as a *boolean* value (e.g., - ``false``), a connected variable from ``${{ needs }}`` context will either cause a typing error or a later - comparison will not work as expected. Either the comparison works with ``inputs.param == false`` for the default - value, **or** it works with a value from ``${{ needs }}`` context, which is a string ``inputs.param == 'false'``. + 1. Scripts (Bash, Python, ...) return results as strings. There is no option or operation provided by GitHub Actions + to convert outputs of ``printf`` to a ``boolean`` in the YAML file. + 2. Unlike job template inputs, outputs have no type information. These are all considered *string* values. Again no + implicit or explicit type conversion is provided. + 3. While inputs might be defined as ``boolean`` and a matching default can be set as a *boolean* value (e.g., + ``false``), a connected variable from ``${{ needs }}`` context will either cause a typing error or a later + comparison will not work as expected. Either the comparison works with ``inputs.param == false`` for the default + value, **or** it works with a value from ``${{ needs }}`` context, which is a string ``inputs.param == 'false'``. + +.. topic:: Behavior + + 1. Checkout repository. + 2. Classify ``${{ github.ref }}`` into branch, tag or pull-request. + 3. Compute output parameters. + 4. Find associated pull-request. .. topic:: Job Execution @@ -377,11 +384,12 @@ ref_kind Moreover, if the tag matches the :ref:`JOBTMPL/PrepareJob/Input/release_tag_pattern`, the extracted version is available in the job's :ref:`JOBTMPL/PrepareJob/Output/version` result. -.. note:: + .. note:: - GitHub doesn't provide standalone branch or tag information, but provides the variable ``${{ github.ref }}`` - specifying the currently active reference (branch, tag, pull, ...). This job template parses the context's variable - and derives if a pipeline runs for a commit on a branch or a tagged commit. + GitHub doesn't provide standalone branch or tag information, but provides the variable + ``${{ github.ref }}`` specifying the currently active reference (branch, tag, pull, ...). This job + template parses the context's variable and derives if a pipeline runs for a commit on a branch or a + tagged commit. .. _JOBTMPL/PrepareJob/Output/branch: diff --git a/doc/JobTemplate/Testing/ApplicationTesting.rst b/doc/JobTemplate/Testing/ApplicationTesting.rst index 5b93f49..d507e87 100644 --- a/doc/JobTemplate/Testing/ApplicationTesting.rst +++ b/doc/JobTemplate/Testing/ApplicationTesting.rst @@ -1,22 +1,6 @@ .. _JOBTMPL/ApplicationTesting: -ApplicationTesting -################## +ApplicationTesting (idea) +######################### -.. todo:: ApplicationTesting:Needs documentation. - -**Behavior:** - -.. todo:: ApplicationTesting:Behavior needs documentation. - -**Dependencies:** - -.. todo:: ApplicationTesting:Dependencies needs documentation. - -Instantiation -************* - -Simple Example -============== - -.. todo:: ApplicationTesting:Simple example needs documentation. +.. todo:: ApplicationTesting:: Needs documentation. diff --git a/doc/JobTemplate/Testing/index.rst b/doc/JobTemplate/Testing/index.rst index 4dd822f..8ec3a2e 100644 --- a/doc/JobTemplate/Testing/index.rst +++ b/doc/JobTemplate/Testing/index.rst @@ -5,8 +5,8 @@ Testing The category *testing* provides workflow templates implementing -* :ref:`JOBTMPL/UnitTesting` - -* :ref:`JOBTMPL/ApplicationTesting` - +* :ref:`JOBTMPL/UnitTesting` - Run unit tests and collect code coverage. +* :ref:`JOBTMPL/ApplicationTesting` - Run application tests. .. toctree:: :hidden: