diff --git a/doc/JobTemplate/Documentation/PublishToGitHubPages.rst b/doc/JobTemplate/Documentation/PublishToGitHubPages.rst index 08331a1..50dd8cc 100644 --- a/doc/JobTemplate/Documentation/PublishToGitHubPages.rst +++ b/doc/JobTemplate/Documentation/PublishToGitHubPages.rst @@ -5,102 +5,171 @@ PublishToGitHubPages This job publishes HTML content from artifacts of other jobs to GitHub Pages. -**Behavior:** +.. topic:: Features -1. Checkout repository. -2. Download artifacts. -3. Push HTML files to branch ``gh-pages``. + tbd -**Dependencies:** -* :gh:`actions/checkout` -* :gh:`actions/download-artifact` +.. topic:: Behavior + + 1. Checkout repository. + 2. Download artifacts. + 3. Push HTML files to branch ``gh-pages``. + +.. topic:: Job Execution + + .. image:: ../../_static/pyTooling-Actions-PublishToGitHubPages.png + :width: 500px + +.. topic:: Dependencies + + * :gh:`actions/checkout` + * :gh:`pyTooling/download-artifact` + + * :gh:`actions/download-artifact` + + +.. _JOBTMPL/Parameters/Instantiation: Instantiation ************* -Simple Example -============== +.. grid:: 2 -.. code-block:: yaml + .. grid-item:: + :columns: 5 - jobs: - BuildTheDocs: - # ... + .. rubric:: Simple Example - PublishToGitHubPages: - uses: pyTooling/Actions/.github/workflows/PublishToGitHubPages.yml@r5 - needs: - - BuildTheDocs - with: - doc: Documentation + .. code-block:: yaml + + jobs: + BuildTheDocs: + # ... + + PublishToGitHubPages: + uses: pyTooling/Actions/.github/workflows/PublishToGitHubPages.yml@r5 + needs: + - BuildTheDocs + with: + doc: Documentation + + .. grid-item:: + :columns: 5 + + .. rubric:: 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 }} -Complex Example -=============== +.. _JOBTMPL/PublishToGitHubPages/Parameters: -.. code-block:: yaml +Parameter Summary +***************** - 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 }} +.. rubric:: Goto :ref:`input parameters ` + ++---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ +| Parameter Name | Required | Type | Default | ++=====================================================================+==========+==========+===================================================================+ +| :ref:`JOBTMPL/PublishToGitHubPages/Input/ubuntu_image_version` | no | string | ``'24.04'`` | ++---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ +| :ref:`JOBTMPL/PublishToGitHubPages/Input/doc` | yes | string | — — — — | ++---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ +| :ref:`JOBTMPL/PublishToGitHubPages/Input/coverage` | no | string | ``''`` | ++---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ +| :ref:`JOBTMPL/PublishToGitHubPages/Input/typing` | no | string | ``''`` | ++---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ + +.. rubric:: Goto :ref:`secrets ` + +This job template needs no secrets. + +.. rubric:: Goto :ref:`output parameters ` + +This job template has no output parameters. -Parameters -********** +.. _JOBTMPL/PublishToGitHubPages/Inputs: + +Input Parameters +**************** + +.. _JOBTMPL/PublishToGitHubPages/Input/ubuntu_image_version: + +.. include:: ../_ubuntu_image_version.rst + + +.. _JOBTMPL/PublishToGitHubPages/Input/doc: doc === -+----------------+----------+----------+--------------+ -| Parameter Name | Required | Type | Default | -+================+==========+==========+==============+ -| doc | yes | string | — — — — | -+----------------+----------+----------+--------------+ +:Type: string +:Required: yes +:Default Value: — — — — +:Possible Values: Any valid artifact name. +:Description: Name of the documentation artifact containing the HTML website. -Name of the documentation artifact. +.. _JOBTMPL/PublishToGitHubPages/Input/coverage: coverage ======== -+----------------+----------+----------+-----------------+ -| Parameter Name | Required | Type | Default | -+================+==========+==========+=================+ -| coverage | optional | string | ``""`` | -+----------------+----------+----------+-----------------+ +:Type: string +:Required: no +:Default Value: ``''`` +:Possible Values: Any valid artifact name. +:Description: Name of the coverage artifact containing the HTML coverage report, which will be integrated as a + subdirectory. -Name of the coverage artifact. +.. _JOBTMPL/PublishToGitHubPages/Input/typing: typing ====== -+----------------+----------+----------+-----------------+ -| Parameter Name | Required | Type | Default | -+================+==========+==========+=================+ -| typing | optional | string | ``""`` | -+----------------+----------+----------+-----------------+ - -Name of the typing artifact. +:Type: string +:Required: no +:Default Value: ``''`` +:Possible Values: Any valid artifact name. +:Description: Name of the type checking artifact containing the HTML type checker report, which will be integrated + as a subdirectory. +.. _JOBTMPL/PublishToGitHubPages/Secrets: Secrets ******* This job template needs no secrets. -Results + +.. _JOBTMPL/PublishToGitHubPages/Outputs: + +Outputs ******* This job template has no output parameters. + + +.. _JOBTMPL/PublishToGitHubPages/Optimizations: + +Optimizations +************* + +This template offers no optimizations (reduced job runtime). diff --git a/doc/JobTemplate/Package/Package.rst b/doc/JobTemplate/Package/Package.rst index 7603adb..3caffc2 100644 --- a/doc/JobTemplate/Package/Package.rst +++ b/doc/JobTemplate/Package/Package.rst @@ -143,6 +143,7 @@ artifact :Type: string :Required: yes +:Default Value: — — — — :Possible Values: Any valid artifact name. :Description: Name of the artifact containing the packaged Python code. diff --git a/doc/JobTemplate/Package/PublishOnPyPI.rst b/doc/JobTemplate/Package/PublishOnPyPI.rst index 45d99bd..62e7cd2 100644 --- a/doc/JobTemplate/Package/PublishOnPyPI.rst +++ b/doc/JobTemplate/Package/PublishOnPyPI.rst @@ -168,6 +168,7 @@ artifact :Type: string :Required: yes +:Default Value: — — — — :Possible Values: Any valid artifact name. :Description: Name of the artifact containing the packaged Python package(s). diff --git a/doc/JobTemplate/Publish/index.rst b/doc/JobTemplate/Publish/index.rst index 65e8a50..0b3b146 100644 --- a/doc/JobTemplate/Publish/index.rst +++ b/doc/JobTemplate/Publish/index.rst @@ -5,8 +5,8 @@ Publish The category *publish* provides workflow templates implementing -* :ref:`JOBTMPL/PublishTestResults` - -* :ref:`JOBTMPL/PublishCoverageResults` - +* :ref:`JOBTMPL/PublishTestResults`- Merge and publish unit test results. +* :ref:`JOBTMPL/PublishCoverageResults` - Merge and publish code coverage results. .. toctree:: :hidden: diff --git a/doc/JobTemplate/Release/TagReleaseCommit.rst b/doc/JobTemplate/Release/TagReleaseCommit.rst index 6476db9..730e699 100644 --- a/doc/JobTemplate/Release/TagReleaseCommit.rst +++ b/doc/JobTemplate/Release/TagReleaseCommit.rst @@ -142,6 +142,7 @@ version :Type: string :Required: yes +:Default Value: — — — — :Possible Values: Any valid Git tag name. :Description: The version string to be used for tagging. @@ -153,6 +154,7 @@ auto_tag :Type: string :Required: yes +:Default Value: — — — — :Possible Values: ``'false'``, ``'true'``` :Description: If *true*, tag the current commit. diff --git a/doc/JobTemplate/Templates.rst b/doc/JobTemplate/Templates.rst index dafeef3..6227bb6 100644 --- a/doc/JobTemplate/Templates.rst +++ b/doc/JobTemplate/Templates.rst @@ -19,10 +19,11 @@ .. rubric:: Documentation * :ref:`JOBTMPL/CheckDocumentation` - * :ref:`JOBTMPL/VerifyDocs` * :ref:`JOBTMPL/SphinxDocumentation` * :ref:`JOBTMPL/LaTeXDocumentation` + .. #* :ref:`JOBTMPL/VerifyDocs` + .. rubric:: Unit Tests, Code Coverage * :ref:`JOBTMPL/ApplicationTesting` diff --git a/doc/_static/pyTooling-Actions-PublishToGitHubPages.png b/doc/_static/pyTooling-Actions-PublishToGitHubPages.png new file mode 100644 index 0000000..8883833 Binary files /dev/null and b/doc/_static/pyTooling-Actions-PublishToGitHubPages.png differ