From d3eb6e611d25ff7cdef6081515391a81e1cc8072 Mon Sep 17 00:00:00 2001 From: Patrick Lehmann Date: Tue, 1 Nov 2022 23:35:08 +0100 Subject: [PATCH] Documented Realease and StaticTypeCheck. --- .github/workflows/StaticTypeCheck.yml | 2 +- doc/JobTemplate/PublishToGitHubPages.rst | 11 ++ doc/JobTemplate/Release.rst | 57 +++++++--- doc/JobTemplate/StaticTypeCheck.rst | 135 ++++++++++++++++++----- doc/JobTemplate/VerifyDocs.rst | 37 +++---- 5 files changed, 180 insertions(+), 62 deletions(-) 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/doc/JobTemplate/PublishToGitHubPages.rst b/doc/JobTemplate/PublishToGitHubPages.rst index 2a32de1..2f7520a 100644 --- a/doc/JobTemplate/PublishToGitHubPages.rst +++ b/doc/JobTemplate/PublishToGitHubPages.rst @@ -5,6 +5,17 @@ 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 ************* diff --git a/doc/JobTemplate/Release.rst b/doc/JobTemplate/Release.rst index 485a46c..51832a8 100644 --- a/doc/JobTemplate/Release.rst +++ b/doc/JobTemplate/Release.rst @@ -3,7 +3,31 @@ Release ####### -publish GitHub 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 ************* @@ -13,31 +37,34 @@ Simple Example .. code-block:: yaml - TBD + jobs: + Release: + uses: pyTooling/Actions/.github/workflows/Release.yml@r0 + Complex Example =============== - - .. code-block:: yaml - TBD + jobs: + Release: + uses: pyTooling/Actions/.github/workflows/Release.yml@r0 + if: startsWith(github.ref, 'refs/tags') + needs: + - Package Parameters ********** -TBD 1 -===== +This job template needs no input parameters. -TBD +Secrets +******* -TBD 1 -===== +This job template needs no secrets. -TBD +Results +******* -Template Results -**************** - -*None* +This job template has no output parameters. diff --git a/doc/JobTemplate/StaticTypeCheck.rst b/doc/JobTemplate/StaticTypeCheck.rst index a05bf56..e6ecfbc 100644 --- a/doc/JobTemplate/StaticTypeCheck.rst +++ b/doc/JobTemplate/StaticTypeCheck.rst @@ -3,7 +3,60 @@ StaticTypeCheck ############### -collect static type check result with mypy, and optionally upload results as an HTML report. +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``: @@ -30,38 +83,66 @@ Example ``commands``: cd Parent mypy --html-report ../htmlmypy -p ToolName - -Instantiation -************* - -Simple Example -============== - -.. code-block:: yaml - - TBD - -Complex Example -=============== - - - -.. code-block:: yaml - - TBD - Parameters ********** -TBD 1 -===== +python_version +============== -TBD +Python version. -TBD 1 -===== ++----------+----------+-----------------+ +| Required | Type | Default | ++==========+==========+=================+ +| optional | string | ``3.11`` | ++----------+----------+-----------------+ -TBD + +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 ******* diff --git a/doc/JobTemplate/VerifyDocs.rst b/doc/JobTemplate/VerifyDocs.rst index 72894e4..9ce0438 100644 --- a/doc/JobTemplate/VerifyDocs.rst +++ b/doc/JobTemplate/VerifyDocs.rst @@ -3,7 +3,15 @@ VerifyDocs ########## -extract code examples from the README and test these code snippets. +This job extracts code examples from the README and tests these code snippets. + +**Behavior:** + +TBD + +**Dependencies:** + +TBD Instantiation ************* @@ -11,33 +19,24 @@ Instantiation Simple Example ============== -.. code-block:: yaml - - TBD +.. todo:: VerifyDocs:SimpleExample Needs documentation. Complex Example =============== - - -.. code-block:: yaml - - TBD +.. todo:: VerifyDocs:ComplexExample Needs documentation. Parameters ********** -TBD 1 -===== +.. todo:: VerifyDocs:Parameters Needs documentation. -TBD +Secrets +******* -TBD 1 -===== +This job template needs no secrets. -TBD +Results +******* -Template Results -**************** - -*None* +This job template has no output parameters.