Restructured chapters.

doc/JobTemplate/Publish/PublishCoverageResults.rst

@@ -0,0 +1,22 @@
+.. _JOBTMPL/PublishCoverageResults:
+
+PublishCoverageResults
+######################
+
+.. todo:: PublishCoverageResults:Needs documentation.
+
+**Behavior:**
+
+.. todo:: PublishCoverageResults:Behavior needs documentation.
+
+**Dependencies:**
+
+.. todo:: PublishCoverageResults:Dependencies needs documentation.
+
+Instantiation
+*************
+
+Simple Example
+==============
+
+.. todo:: PublishCoverageResults:Simple example needs documentation.

doc/JobTemplate/Publish/PublishReleaseNotes.rst

@@ -0,0 +1,96 @@
+.. _JOBTMPL/PublishReleaseNotes:
+
+PublishReleaseNotes
+###################
+
+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
+   * tbd
+
+   # Changes
+
+   * tbd
+   * tbd
+
+   # Bug Fixes
+
+   * tbd
+   * tbd
+
+   # Documentation
+
+   * tbd
+   * tbd
+
+   # Unit Tests
+
+   * tbd
+   * tbd
+
+   ----------
+   # Related Issues and Pull-Requests
+
+   * tbd
+   * tbd
+
+
+**Behavior:**
+
+1. Extract information from environment variables provided by GitHub Actions.
+2. Create a Release Page on GitHub
+
+**Dependencies:**
+
+* :gh:`actions/create-release` (unmaintained)
+
+Instantiation
+*************
+
+Simple Example
+==============
+
+.. code-block:: yaml
+
+   jobs:
+     Release:
+       uses: pyTooling/Actions/.github/workflows/Release.yml@r5
+
+
+Complex Example
+===============
+
+.. code-block:: yaml
+
+   jobs:
+     Release:
+       uses: pyTooling/Actions/.github/workflows/Release.yml@r5
+       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.

doc/JobTemplate/Publish/PublishTestResults.rst

@@ -0,0 +1,88 @@
+.. _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@r5
+
+Complex Example
+===============
+
+.. code-block:: yaml
+
+   jobs:
+     CodeCoverage:
+       # ...
+
+     UnitTesting:
+       # ...
+
+     PublishTestResults:
+       uses: pyTooling/Actions/.github/workflows/PublishTestResults.yml@r5
+       needs:
+         - CodeCoverage
+         - UnitTesting
+
+
+Parameters
+**********
+
+report_files
+============
+
++----------------+----------+----------+---------------------------------+
+| Parameter Name | Required | Type     | Default                         |
++================+==========+==========+=================================+
+| report_files   | optional | string   | ``artifacts/**/*.xml``          |
++----------------+----------+----------+---------------------------------+
+
+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.
+
+
+Secrets
+*******
+
+This job template needs no secrets.
+
+Results
+*******
+
+This job template has no output parameters.

doc/JobTemplate/Publish/PublishToGitHubPages.rst

@@ -0,0 +1,106 @@
+.. _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@r5
+       needs:
+         - BuildTheDocs
+       with:
+         doc: Documentation
+
+
+Complex Example
+===============
+
+.. code-block:: yaml
+
+   jobs:
+     PublishToGitHubPages:
+       uses: pyTooling/Actions/.github/workflows/PublishToGitHubPages.yml@r5
+       needs:
+         - Params
+         - BuildTheDocs
+         - Coverage
+         - StaticTypeCheck
+       with:
+         doc: ${{ fromJson(needs.Params.outputs.artifact_names).documentation_html }}
+         coverage: ${{ fromJson(needs.Params.outputs.artifact_names).codecoverage_html }}
+         typing: ${{ fromJson(needs.Params.outputs.artifact_names).statictyping_html }}
+
+
+Parameters
+**********
+
+doc
+===
+
++----------------+----------+----------+--------------+
+| Parameter Name | Required | Type     | Default      |
++================+==========+==========+==============+
+| doc            | yes      | string   | — — — —      |
++----------------+----------+----------+--------------+
+
+Name of the documentation artifact.
+
+
+coverage
+========
+
++----------------+----------+----------+-----------------+
+| Parameter Name | Required | Type     | Default         |
++================+==========+==========+=================+
+| coverage       | optional | string   | ``""``          |
++----------------+----------+----------+-----------------+
+
+Name of the coverage artifact.
+
+
+typing
+======
+
++----------------+----------+----------+-----------------+
+| Parameter Name | Required | Type     | Default         |
++================+==========+==========+=================+
+| typing         | optional | string   | ``""``          |
++----------------+----------+----------+-----------------+
+
+Name of the typing artifact.
+
+
+
+Secrets
+*******
+
+This job template needs no secrets.
+
+Results
+*******
+
+This job template has no output parameters.

doc/JobTemplate/Publish/index.rst

@@ -0,0 +1,19 @@
+.. _JOBTMPL/Publish:
+
+Publish
+#######
+
+The category *publish* provides workflow templates implementing
+
+* :ref:`JOBTMPL/PublishTestResults` -
+* :ref:`JOBTMPL/PublishCoverageResults` -
+* :ref:`JOBTMPL/PublishReleaseNotes` -
+* :ref:`JOBTMPL/PublishToGitHubPages` -
+
+.. toctree::
+   :hidden:
+
+   PublishTestResults
+   PublishCoverageResults
+   PublishReleaseNotes
+   PublishToGitHubPages