From 53a32fbf35550008035cff0bf96d897dff0bfce0 Mon Sep 17 00:00:00 2001
From: Patrick Lehmann <Paebbels@gmail.com>
Date: Wed, 24 Sep 2025 00:17:43 +0200
Subject: [PATCH] Also use JSON objects for SphinxDocumentation.

---
 .github/workflows/CompletePipeline.yml        |  12 +-
 .github/workflows/SphinxDocumentation.yml     |  25 ++--
 .github/workflows/_Checking_JobTemplates.yml  |  14 +-
 doc/Instantiation.rst                         |   8 +-
 .../Documentation/LaTeXDocumentation.rst      |   6 -
 .../Documentation/SphinxDocumentation.rst     | 138 +++++++++++-------
 .../Quality/CheckDocumentation.rst            |   6 -
 doc/JobTemplate/Release/TagReleaseCommit.rst  |   6 -
 doc/JobTemplate/Setup/Parameters.rst          |   6 -
 doc/JobTemplate/Setup/PrepareJob.rst          |   6 -
 doc/JobTemplate/index.rst                     |   2 +
 11 files changed, 125 insertions(+), 104 deletions(-)

diff --git a/.github/workflows/CompletePipeline.yml b/.github/workflows/CompletePipeline.yml
index fc60c8f..bd07107 100644
--- a/.github/workflows/CompletePipeline.yml
+++ b/.github/workflows/CompletePipeline.yml
@@ -301,12 +301,12 @@ jobs:
 #      - VerifyDocs
     if: success() || failure()
     with:
-      python_version:                 ${{ needs.UnitTestingParams.outputs.python_version }}
-      coverage_report_json_directory: ${{ fromJson(needs.ConfigParams.outputs.coverage_report_json).directory }}
-      unittest_xml_artifact:          ${{ fromJson(needs.UnitTestingParams.outputs.artifact_names).unittesting_xml }}
-      coverage_json_artifact:         ${{ fromJson(needs.UnitTestingParams.outputs.artifact_names).codecoverage_json }}
-      html_artifact:                  ${{ fromJson(needs.UnitTestingParams.outputs.artifact_names).documentation_html }}
-      latex_artifact:                 ${{ fromJson(needs.UnitTestingParams.outputs.artifact_names).documentation_latex }}
+      python_version:         ${{ needs.UnitTestingParams.outputs.python_version }}
+      coverage_report_json:   ${{ needs.ConfigParams.outputs.coverage_report_json }}
+      unittest_xml_artifact:  ${{ fromJson(needs.UnitTestingParams.outputs.artifact_names).unittesting_xml }}
+      coverage_json_artifact: ${{ fromJson(needs.UnitTestingParams.outputs.artifact_names).codecoverage_json }}
+      html_artifact:          ${{ fromJson(needs.UnitTestingParams.outputs.artifact_names).documentation_html }}
+      latex_artifact:         ${{ fromJson(needs.UnitTestingParams.outputs.artifact_names).documentation_latex }}
 
   IntermediateCleanUp:
     uses: pyTooling/Actions/.github/workflows/IntermediateCleanUp.yml@dev
diff --git a/.github/workflows/SphinxDocumentation.yml b/.github/workflows/SphinxDocumentation.yml
index ab8a21b..997faed 100644
--- a/.github/workflows/SphinxDocumentation.yml
+++ b/.github/workflows/SphinxDocumentation.yml
@@ -44,24 +44,29 @@ on:
         required: false
         default: 'doc'
         type: string
-      coverage_report_json_directory:
-        description: 'report/coverage'
-        required: false
-        type: string
       coverage_json_artifact:
         description: 'Name of the coverage JSON artifact.'
         required: false
         default: ''
         type: string
+      coverage_report_json:
+        description: 'Directory where coverage JSON artifact will be extracted.'
+        required: false
+        default: >-
+          { "directory": "report/coverage"
+          }
+        type: string
       unittest_xml_artifact:
         description: 'Name of the unittest XML artifact.'
         required: false
         default: ''
         type: string
-      unittest_xml_directory:
+      unittest_xml:
         description: 'Directory where unittest XML artifact will be extracted.'
         required: false
-        default: 'report/unit'
+        default: >-
+          { "directory": "report/unit"
+          }
         type: string
       html_artifact:
         description: 'Name of the HTML documentation artifact.'
@@ -104,7 +109,7 @@ jobs:
         if: inputs.unittest_xml_artifact != ''
         with:
           name: ${{ inputs.unittest_xml_artifact }}
-          path: ${{ inputs.unittest_xml_directory }}
+          path: ${{ fromJson(inputs.unittest_xml).directory }}
           investigate: true
 
       - name: 📥 Download artifacts '${{ inputs.coverage_json_artifact }}' from 'PublishCoverageResults' job
@@ -112,7 +117,7 @@ jobs:
         if: inputs.coverage_json_artifact != ''
         with:
           name: ${{ inputs.coverage_json_artifact }}
-          path: ${{ inputs.coverage_report_json_directory }}
+          path: ${{ fromJson(inputs.coverage_report_json).directory }}
           investigate: true
 
       - name: ☑ Generate HTML documentation
@@ -163,7 +168,7 @@ jobs:
         if: inputs.unittest_xml_artifact != ''
         with:
           name: ${{ inputs.unittest_xml_artifact }}
-          path: ${{ inputs.unittest_xml_directory }}
+          path: ${{ fromJson(inputs.unittest_xml).directory }}
           investigate: true
 
       - name: 📥 Download artifacts '${{ inputs.coverage_json_artifact }}' from 'PublishCoverageResults' job
@@ -171,7 +176,7 @@ jobs:
         if: inputs.coverage_json_artifact != ''
         with:
           name: ${{ inputs.coverage_json_artifact }}
-          path: ${{ inputs.coverage_report_json_directory }}
+          path: ${{ fromJson(inputs.coverage_report_json).directory }}
           investigate: true
 
       - name: ☑ Generate LaTeX documentation
diff --git a/.github/workflows/_Checking_JobTemplates.yml b/.github/workflows/_Checking_JobTemplates.yml
index 34cab02..68f28d2 100644
--- a/.github/workflows/_Checking_JobTemplates.yml
+++ b/.github/workflows/_Checking_JobTemplates.yml
@@ -171,13 +171,13 @@ jobs:
       - PublishCoverageResults
 #      - VerifyDocs
     with:
-      python_version:                 ${{ needs.UnitTestingParams.outputs.python_version }}
-      unittest_xml_directory:         ${{ fromJson(needs.ConfigParams.outputs.unittest_report_xml).directory }}
-      coverage_report_json_directory: ${{ fromJson(needs.ConfigParams.outputs.coverage_report_json).directory }}
-      unittest_xml_artifact:          ${{ fromJson(needs.UnitTestingParams.outputs.artifact_names).unittesting_xml }}
-      coverage_json_artifact:         ${{ fromJson(needs.UnitTestingParams.outputs.artifact_names).codecoverage_json }}
-      html_artifact:                  ${{ fromJson(needs.UnitTestingParams.outputs.artifact_names).documentation_html }}
-      latex_artifact:                 ${{ fromJson(needs.UnitTestingParams.outputs.artifact_names).documentation_latex }}
+      python_version:         ${{ needs.UnitTestingParams.outputs.python_version }}
+      unittest_xml:           ${{ needs.ConfigParams.outputs.unittest_report_xml }}
+      coverage_report_json:   ${{ needs.ConfigParams.outputs.coverage_report_json }}
+      unittest_xml_artifact:  ${{ fromJson(needs.UnitTestingParams.outputs.artifact_names).unittesting_xml }}
+      coverage_json_artifact: ${{ fromJson(needs.UnitTestingParams.outputs.artifact_names).codecoverage_json }}
+      html_artifact:          ${{ fromJson(needs.UnitTestingParams.outputs.artifact_names).documentation_html }}
+      latex_artifact:         ${{ fromJson(needs.UnitTestingParams.outputs.artifact_names).documentation_latex }}
 
   IntermediateCleanUp:
     uses: pyTooling/Actions/.github/workflows/IntermediateCleanUp.yml@dev
diff --git a/doc/Instantiation.rst b/doc/Instantiation.rst
index 296958d..54fe8fa 100644
--- a/doc/Instantiation.rst
+++ b/doc/Instantiation.rst
@@ -36,10 +36,13 @@ to handover input parameters to the template.
    on:
      push:
      workflow_dispatch:
+     schedule:
+   # Every Friday at 22:00 - rerun pipeline to check for dependency-based issues
+       - cron: '0 22 * * 5'
 
    jobs:
      <InstanceName>:
-       uses: <GitHubOrganization>/<Repository>/.github/workflows/<Template>.yml@v0
+       uses: <GitHubOrganization>/<Repository>/.github/workflows/<Template>.yml@r5
        with:
          <Param1>: <Value>
 
@@ -57,6 +60,9 @@ Documentation Only (Sphinx)
    on:
      push:
      workflow_dispatch:
+     schedule:
+   # Every Friday at 22:00 - rerun pipeline to check for dependency-based issues
+       - cron: '0 22 * * 5'
 
    jobs:
      BuildTheDocs:
diff --git a/doc/JobTemplate/Documentation/LaTeXDocumentation.rst b/doc/JobTemplate/Documentation/LaTeXDocumentation.rst
index 958670b..189c74a 100644
--- a/doc/JobTemplate/Documentation/LaTeXDocumentation.rst
+++ b/doc/JobTemplate/Documentation/LaTeXDocumentation.rst
@@ -44,12 +44,6 @@ Instantiation
 
 .. code-block:: yaml
 
-   name: Pipeline
-
-   on:
-     push:
-     workflow_dispatch:
-
    jobs:
      UnitTestingParams:
        uses: pyTooling/Actions/.github/workflows/Parameters.yml@r5
diff --git a/doc/JobTemplate/Documentation/SphinxDocumentation.rst b/doc/JobTemplate/Documentation/SphinxDocumentation.rst
index 7e1a23b..f6c5264 100644
--- a/doc/JobTemplate/Documentation/SphinxDocumentation.rst
+++ b/doc/JobTemplate/Documentation/SphinxDocumentation.rst
@@ -6,8 +6,8 @@
 SphinxDocumentation
 ###################
 
-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.
+The ``SphinxDocumentation`` job template compiles the ReStructured Text documentation using :term:`Sphinx` to an HTML
+website and a LaTeX documentation. This LaTeX document can be translated using e.g. :term:`MikTeX` to a PDF file.
 
 .. topic:: Features
 
@@ -70,12 +70,6 @@ Instantiation
 
 .. code-block:: yaml
 
-   name: Pipeline
-
-   on:
-     push:
-     workflow_dispatch:
-
    jobs:
      UnitTestingParams:
        uses: pyTooling/Actions/.github/workflows/Parameters.yml@r5
@@ -99,29 +93,29 @@ Parameter Summary
 
 .. rubric:: Goto :ref:`input parameters <JOBTMPL/SphinxDocumentation/Inputs>`
 
-+-------------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+
-| Parameter Name                                                          | Required | Type     | Default                                                           |
-+=========================================================================+==========+==========+===================================================================+
-| :ref:`JOBTMPL/SphinxDocumentation/Input/ubuntu_image_version`           | no       | string   | ``'24.04'``                                                       |
-+-------------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+
-| :ref:`JOBTMPL/SphinxDocumentation/Input/python_version`                 | no       | string   | ``'3.13'``                                                        |
-+-------------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+
-| :ref:`JOBTMPL/SphinxDocumentation/Input/requirements`                   | no       | string   | ``'-r doc/requirements.txt'``                                     |
-+-------------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+
-| :ref:`JOBTMPL/SphinxDocumentation/Input/doc_directory`                  | no       | string   | ``'doc'``                                                         |
-+-------------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+
-| :ref:`JOBTMPL/SphinxDocumentation/Input/coverage_report_json_directory` | no       | string   | ``''``                                                            |
-+-------------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+
-| :ref:`JOBTMPL/SphinxDocumentation/Input/coverage_json_artifact`         | no       | string   | ``''``                                                            |
-+-------------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+
-| :ref:`JOBTMPL/SphinxDocumentation/Input/unittest_xml_artifact`          | no       | string   | ``''``                                                            |
-+-------------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+
-| :ref:`JOBTMPL/SphinxDocumentation/Input/unittest_xml_directory`         | no       | string   | ``'report/unit'``                                                 |
-+-------------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+
-| :ref:`JOBTMPL/SphinxDocumentation/Input/html_artifact`                  | no       | string   | ``''``                                                            |
-+-------------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+
-| :ref:`JOBTMPL/SphinxDocumentation/Input/latex_artifact`                 | no       | string   | ``''``                                                            |
-+-------------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+
++-------------------------------------------------------------------------+----------+----------------+-------------------------------------------------------------------+
+| Parameter Name                                                          | Required | Type           | Default                                                           |
++=========================================================================+==========+================+===================================================================+
+| :ref:`JOBTMPL/SphinxDocumentation/Input/ubuntu_image_version`           | no       | string         | ``'24.04'``                                                       |
++-------------------------------------------------------------------------+----------+----------------+-------------------------------------------------------------------+
+| :ref:`JOBTMPL/SphinxDocumentation/Input/python_version`                 | no       | string         | ``'3.13'``                                                        |
++-------------------------------------------------------------------------+----------+----------------+-------------------------------------------------------------------+
+| :ref:`JOBTMPL/SphinxDocumentation/Input/requirements`                   | no       | string         | ``'-r doc/requirements.txt'``                                     |
++-------------------------------------------------------------------------+----------+----------------+-------------------------------------------------------------------+
+| :ref:`JOBTMPL/SphinxDocumentation/Input/doc_directory`                  | no       | string         | ``'doc'``                                                         |
++-------------------------------------------------------------------------+----------+----------------+-------------------------------------------------------------------+
+| :ref:`JOBTMPL/SphinxDocumentation/Input/coverage_json_artifact`         | no       | string         | ``''``                                                            |
++-------------------------------------------------------------------------+----------+----------------+-------------------------------------------------------------------+
+| :ref:`JOBTMPL/SphinxDocumentation/Input/coverage_report_json`           | no       | string (JSON)  | :jsoncode:`{"directory": "report/coverage"}`                      |
++-------------------------------------------------------------------------+----------+----------------+-------------------------------------------------------------------+
+| :ref:`JOBTMPL/SphinxDocumentation/Input/unittest_xml_artifact`          | no       | string         | ``''``                                                            |
++-------------------------------------------------------------------------+----------+----------------+-------------------------------------------------------------------+
+| :ref:`JOBTMPL/SphinxDocumentation/Input/unittest_xml`                   | no       | string (JSON)  | :jsoncode:`{"directory": "report/unit"}`                          |
++-------------------------------------------------------------------------+----------+----------------+-------------------------------------------------------------------+
+| :ref:`JOBTMPL/SphinxDocumentation/Input/html_artifact`                  | no       | string         | ``''``                                                            |
++-------------------------------------------------------------------------+----------+----------------+-------------------------------------------------------------------+
+| :ref:`JOBTMPL/SphinxDocumentation/Input/latex_artifact`                 | no       | string         | ``''``                                                            |
++-------------------------------------------------------------------------+----------+----------------+-------------------------------------------------------------------+
 
 .. rubric:: Goto :ref:`secrets <JOBTMPL/SphinxDocumentation/Secrets>`
 
@@ -178,18 +172,6 @@ doc_directory
                      adjusted as well.
 
 
-.. _JOBTMPL/SphinxDocumentation/Input/coverage_report_json_directory:
-
-coverage_report_json_directory
-==============================
-
-:Type:            string
-:Required:        no
-:Default Value:   ``''``
-:Possible Values: Any valid directory or sub-directory.
-:Description:     tbd
-
-
 .. _JOBTMPL/SphinxDocumentation/Input/coverage_json_artifact:
 
 coverage_json_artifact
@@ -202,6 +184,40 @@ coverage_json_artifact
 :Description:     Name of the artifact containing the code coverage report in JSON format.
 
 
+.. _JOBTMPL/SphinxDocumentation/Input/coverage_report_json:
+
+coverage_report_json
+====================
+
+:Type:            string (JSON)
+:Required:        no
+:Default Value:
+                  .. code-block:: json
+
+                     { "directory": "reports/coverage",
+                     }
+:Possible Values: Any valid JSON string containing a JSON object with fields:
+
+                  :directory: Directory or sub-directory where the code coverage JSON report will be extracted from
+                  :ref:`artifact <JOBTMPL/SphinxDocumentation/Input/coverage_json_artifact>`.
+:Description:     Directory as JSON object where the code coverage JSON report will be extracted. |br|
+                  This path is configured in :file:`pyproject.toml` and can be extracted by
+                  :ref:`JOBTMPL/ExtractConfiguration`.
+:Example:
+                  .. code-block:: yaml
+
+                     ConfigParams:
+                       uses: pyTooling/Actions/.github/workflows/ExtractConfiguration.yml@r5
+
+                     Documentation:
+                       uses: pyTooling/Actions/.github/workflows/SphinxDocumentation.yml@r5
+                       needs:
+                         - ConfigParams
+                       with:
+                         ...
+                         coverage_report_json: ${{ needs.ConfigParams.outputs.coverage_report_json }}
+
+
 .. _JOBTMPL/SphinxDocumentation/Input/unittest_xml_artifact:
 
 unittest_xml_artifact
@@ -214,16 +230,38 @@ unittest_xml_artifact
 :Description:     Name of the artifact containing the unittest XML report summary in XML format.
 
 
-.. _JOBTMPL/SphinxDocumentation/Input/unittest_xml_directory:
+.. _JOBTMPL/SphinxDocumentation/Input/unittest_xml:
 
-unittest_xml_directory
-======================
+unittest_xml
+============
 
-:Type:            string
+:Type:            string (JSON)
 :Required:        no
-:Default Value:   ``'report/unit'``
-:Possible Values: Any valid directory or sub-directory.
-:Description:     Directory where unittest XML artifact will be extracted.
+:Default Value:
+                  .. code-block:: json
+
+                     { "directory": "reports/unit",
+                     }
+:Possible Values: Any valid JSON string containing a JSON object with fields:
+
+                  :directory: Directory or sub-directory where the unittest JUnit XML report will be extracted from
+                  :ref:`artifact <JOBTMPL/SphinxDocumentation/Input/unittest_xml_artifact>`.
+:Description:     Directory as JSON object where the unittest JUnit XML report will be extracted. |br|
+                  This path is configured in :file:`pyproject.toml` and can be extracted by
+                  :ref:`JOBTMPL/ExtractConfiguration`.
+:Example:
+                  .. code-block:: yaml
+
+                     ConfigParams:
+                       uses: pyTooling/Actions/.github/workflows/ExtractConfiguration.yml@r5
+
+                     Documentation:
+                       uses: pyTooling/Actions/.github/workflows/SphinxDocumentation.yml@r5
+                       needs:
+                         - ConfigParams
+                       with:
+                         ...
+                         unittest_xml: ${{ needs.ConfigParams.outputs.unittest_xml }}
 
 
 .. _JOBTMPL/SphinxDocumentation/Input/html_artifact:
diff --git a/doc/JobTemplate/Quality/CheckDocumentation.rst b/doc/JobTemplate/Quality/CheckDocumentation.rst
index 6cadf93..33f26b9 100644
--- a/doc/JobTemplate/Quality/CheckDocumentation.rst
+++ b/doc/JobTemplate/Quality/CheckDocumentation.rst
@@ -46,12 +46,6 @@ requires a `name` parameter to create the artifact names.
 
 .. code-block:: yaml
 
-   name: Pipeline
-
-   on:
-     push:
-     workflow_dispatch:
-
    jobs:
      ConfigParams:
        uses: pyTooling/Actions/.github/workflows/ExtractConfiguration.yml@r5
diff --git a/doc/JobTemplate/Release/TagReleaseCommit.rst b/doc/JobTemplate/Release/TagReleaseCommit.rst
index c280f4c..af72e54 100644
--- a/doc/JobTemplate/Release/TagReleaseCommit.rst
+++ b/doc/JobTemplate/Release/TagReleaseCommit.rst
@@ -54,12 +54,6 @@ other reason. Its outputs are used to either run a ``TriggerTaggedRelease`` job
 
 .. code-block:: yaml
 
-   name: Pipeline
-
-   on:
-     push:
-     workflow_dispatch:
-
    jobs:
      Prepare:
        uses: pyTooling/Actions/.github/workflows/PrepareJob.yml@r5
diff --git a/doc/JobTemplate/Setup/Parameters.rst b/doc/JobTemplate/Setup/Parameters.rst
index 232a05b..570ae04 100644
--- a/doc/JobTemplate/Setup/Parameters.rst
+++ b/doc/JobTemplate/Setup/Parameters.rst
@@ -60,12 +60,6 @@ Simple Example
 
       .. code-block:: yaml
 
-         name: Pipeline
-
-         on:
-           push:
-           workflow_dispatch:
-
          jobs:
            Params:
              uses: pyTooling/Actions/.github/workflows/Parameters.yml@r5
diff --git a/doc/JobTemplate/Setup/PrepareJob.rst b/doc/JobTemplate/Setup/PrepareJob.rst
index 615d806..99721ff 100644
--- a/doc/JobTemplate/Setup/PrepareJob.rst
+++ b/doc/JobTemplate/Setup/PrepareJob.rst
@@ -71,12 +71,6 @@ pull-request titles.
 
 .. code-block:: yaml
 
-   name: Pipeline
-
-   on:
-     push:
-     workflow_dispatch:
-
    jobs:
      Prepare:
        uses: pyTooling/Actions/.github/workflows/PrepareJob.yml@r5
diff --git a/doc/JobTemplate/index.rst b/doc/JobTemplate/index.rst
index 8037a99..c4fac2e 100644
--- a/doc/JobTemplate/index.rst
+++ b/doc/JobTemplate/index.rst
@@ -34,6 +34,8 @@ Some templates might provide output parameters, which can be used in dependent j
 
 .. code-block:: yaml
 
+   name: Pipeline
+
    on:
      push:
      workflow_dispatch: