Skip to content

Commit 53a32fb

Browse files
PaebbelsPaebbels
committed
Also use JSON objects for SphinxDocumentation.
1 parent 91736df commit 53a32fb

11 files changed

Lines changed: 125 additions & 104 deletions

File tree

‎.github/workflows/CompletePipeline.yml‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -301,12 +301,12 @@ jobs:
301301
# - VerifyDocs
302302
if: success() || failure()
303303
with:
304-
python_version: ${{ needs.UnitTestingParams.outputs.python_version }}
305-
coverage_report_json_directory: ${{ fromJson(needs.ConfigParams.outputs.coverage_report_json).directory }}
306-
unittest_xml_artifact: ${{ fromJson(needs.UnitTestingParams.outputs.artifact_names).unittesting_xml }}
307-
coverage_json_artifact: ${{ fromJson(needs.UnitTestingParams.outputs.artifact_names).codecoverage_json }}
308-
html_artifact: ${{ fromJson(needs.UnitTestingParams.outputs.artifact_names).documentation_html }}
309-
latex_artifact: ${{ fromJson(needs.UnitTestingParams.outputs.artifact_names).documentation_latex }}
304+
python_version: ${{ needs.UnitTestingParams.outputs.python_version }}
305+
coverage_report_json: ${{ needs.ConfigParams.outputs.coverage_report_json }}
306+
unittest_xml_artifact: ${{ fromJson(needs.UnitTestingParams.outputs.artifact_names).unittesting_xml }}
307+
coverage_json_artifact: ${{ fromJson(needs.UnitTestingParams.outputs.artifact_names).codecoverage_json }}
308+
html_artifact: ${{ fromJson(needs.UnitTestingParams.outputs.artifact_names).documentation_html }}
309+
latex_artifact: ${{ fromJson(needs.UnitTestingParams.outputs.artifact_names).documentation_latex }}
310310

311311
IntermediateCleanUp:
312312
uses: pyTooling/Actions/.github/workflows/IntermediateCleanUp.yml@dev

‎.github/workflows/SphinxDocumentation.yml‎

Lines changed: 15 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -44,24 +44,29 @@ on:
4444
required: false
4545
default: 'doc'
4646
type: string
47-
coverage_report_json_directory:
48-
description: 'report/coverage'
49-
required: false
50-
type: string
5147
coverage_json_artifact:
5248
description: 'Name of the coverage JSON artifact.'
5349
required: false
5450
default: ''
5551
type: string
52+
coverage_report_json:
53+
description: 'Directory where coverage JSON artifact will be extracted.'
54+
required: false
55+
default: >-
56+
{ "directory": "report/coverage"
57+
}
58+
type: string
5659
unittest_xml_artifact:
5760
description: 'Name of the unittest XML artifact.'
5861
required: false
5962
default: ''
6063
type: string
61-
unittest_xml_directory:
64+
unittest_xml:
6265
description: 'Directory where unittest XML artifact will be extracted.'
6366
required: false
64-
default: 'report/unit'
67+
default: >-
68+
{ "directory": "report/unit"
69+
}
6570
type: string
6671
html_artifact:
6772
description: 'Name of the HTML documentation artifact.'
@@ -104,15 +109,15 @@ jobs:
104109
if: inputs.unittest_xml_artifact != ''
105110
with:
106111
name: ${{ inputs.unittest_xml_artifact }}
107-
path: ${{ inputs.unittest_xml_directory }}
112+
path: ${{ fromJson(inputs.unittest_xml).directory }}
108113
investigate: true
109114

110115
- name: 📥 Download artifacts '${{ inputs.coverage_json_artifact }}' from 'PublishCoverageResults' job
111116
uses: pyTooling/download-artifact@v5
112117
if: inputs.coverage_json_artifact != ''
113118
with:
114119
name: ${{ inputs.coverage_json_artifact }}
115-
path: ${{ inputs.coverage_report_json_directory }}
120+
path: ${{ fromJson(inputs.coverage_report_json).directory }}
116121
investigate: true
117122

118123
- name: ☑ Generate HTML documentation
@@ -163,15 +168,15 @@ jobs:
163168
if: inputs.unittest_xml_artifact != ''
164169
with:
165170
name: ${{ inputs.unittest_xml_artifact }}
166-
path: ${{ inputs.unittest_xml_directory }}
171+
path: ${{ fromJson(inputs.unittest_xml).directory }}
167172
investigate: true
168173

169174
- name: 📥 Download artifacts '${{ inputs.coverage_json_artifact }}' from 'PublishCoverageResults' job
170175
uses: pyTooling/download-artifact@v5
171176
if: inputs.coverage_json_artifact != ''
172177
with:
173178
name: ${{ inputs.coverage_json_artifact }}
174-
path: ${{ inputs.coverage_report_json_directory }}
179+
path: ${{ fromJson(inputs.coverage_report_json).directory }}
175180
investigate: true
176181

177182
- name: ☑ Generate LaTeX documentation

‎.github/workflows/_Checking_JobTemplates.yml‎

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -171,13 +171,13 @@ jobs:
171171
- PublishCoverageResults
172172
# - VerifyDocs
173173
with:
174-
python_version: ${{ needs.UnitTestingParams.outputs.python_version }}
175-
unittest_xml_directory: ${{ fromJson(needs.ConfigParams.outputs.unittest_report_xml).directory }}
176-
coverage_report_json_directory: ${{ fromJson(needs.ConfigParams.outputs.coverage_report_json).directory }}
177-
unittest_xml_artifact: ${{ fromJson(needs.UnitTestingParams.outputs.artifact_names).unittesting_xml }}
178-
coverage_json_artifact: ${{ fromJson(needs.UnitTestingParams.outputs.artifact_names).codecoverage_json }}
179-
html_artifact: ${{ fromJson(needs.UnitTestingParams.outputs.artifact_names).documentation_html }}
180-
latex_artifact: ${{ fromJson(needs.UnitTestingParams.outputs.artifact_names).documentation_latex }}
174+
python_version: ${{ needs.UnitTestingParams.outputs.python_version }}
175+
unittest_xml: ${{ needs.ConfigParams.outputs.unittest_report_xml }}
176+
coverage_report_json: ${{ needs.ConfigParams.outputs.coverage_report_json }}
177+
unittest_xml_artifact: ${{ fromJson(needs.UnitTestingParams.outputs.artifact_names).unittesting_xml }}
178+
coverage_json_artifact: ${{ fromJson(needs.UnitTestingParams.outputs.artifact_names).codecoverage_json }}
179+
html_artifact: ${{ fromJson(needs.UnitTestingParams.outputs.artifact_names).documentation_html }}
180+
latex_artifact: ${{ fromJson(needs.UnitTestingParams.outputs.artifact_names).documentation_latex }}
181181

182182
IntermediateCleanUp:
183183
uses: pyTooling/Actions/.github/workflows/IntermediateCleanUp.yml@dev

‎doc/Instantiation.rst‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -36,10 +36,13 @@ to handover input parameters to the template.
3636
on:
3737
push:
3838
workflow_dispatch:
39+
schedule:
40+
# Every Friday at 22:00 - rerun pipeline to check for dependency-based issues
41+
- cron: '0 22 * * 5'
3942
4043
jobs:
4144
<InstanceName>:
42-
uses: <GitHubOrganization>/<Repository>/.github/workflows/<Template>.yml@v0
45+
uses: <GitHubOrganization>/<Repository>/.github/workflows/<Template>.yml@r5
4346
with:
4447
<Param1>: <Value>
4548
@@ -57,6 +60,9 @@ Documentation Only (Sphinx)
5760
on:
5861
push:
5962
workflow_dispatch:
63+
schedule:
64+
# Every Friday at 22:00 - rerun pipeline to check for dependency-based issues
65+
- cron: '0 22 * * 5'
6066
6167
jobs:
6268
BuildTheDocs:

‎doc/JobTemplate/Documentation/LaTeXDocumentation.rst‎

Lines changed: 0 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -44,12 +44,6 @@ Instantiation
4444

4545
.. code-block:: yaml
4646
47-
name: Pipeline
48-
49-
on:
50-
push:
51-
workflow_dispatch:
52-
5347
jobs:
5448
UnitTestingParams:
5549
uses: pyTooling/Actions/.github/workflows/Parameters.yml@r5

‎doc/JobTemplate/Documentation/SphinxDocumentation.rst‎

Lines changed: 88 additions & 50 deletions
Original file line numberDiff line numberDiff line change
@@ -6,8 +6,8 @@
66
SphinxDocumentation
77
###################
88

9-
The ``SphinxDocumentation`` job template compiles the ReStructured Text documentation using Sphinx to an HTML website
10-
and a LaTeX documentation. This LaTeX document can be translated using e.g. MikTeX to a PDF file.
9+
The ``SphinxDocumentation`` job template compiles the ReStructured Text documentation using :term:`Sphinx` to an HTML
10+
website and a LaTeX documentation. This LaTeX document can be translated using e.g. :term:`MikTeX` to a PDF file.
1111

1212
.. topic:: Features
1313

@@ -70,12 +70,6 @@ Instantiation
7070

7171
.. code-block:: yaml
7272
73-
name: Pipeline
74-
75-
on:
76-
push:
77-
workflow_dispatch:
78-
7973
jobs:
8074
UnitTestingParams:
8175
uses: pyTooling/Actions/.github/workflows/Parameters.yml@r5
@@ -99,29 +93,29 @@ Parameter Summary
9993

10094
.. rubric:: Goto :ref:`input parameters <JOBTMPL/SphinxDocumentation/Inputs>`
10195

102-
+-------------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+
103-
| Parameter Name | Required | Type | Default |
104-
+=========================================================================+==========+==========+===================================================================+
105-
| :ref:`JOBTMPL/SphinxDocumentation/Input/ubuntu_image_version` | no | string | ``'24.04'`` |
106-
+-------------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+
107-
| :ref:`JOBTMPL/SphinxDocumentation/Input/python_version` | no | string | ``'3.13'`` |
108-
+-------------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+
109-
| :ref:`JOBTMPL/SphinxDocumentation/Input/requirements` | no | string | ``'-r doc/requirements.txt'`` |
110-
+-------------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+
111-
| :ref:`JOBTMPL/SphinxDocumentation/Input/doc_directory` | no | string | ``'doc'`` |
112-
+-------------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+
113-
| :ref:`JOBTMPL/SphinxDocumentation/Input/coverage_report_json_directory` | no | string | ``''`` |
114-
+-------------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+
115-
| :ref:`JOBTMPL/SphinxDocumentation/Input/coverage_json_artifact` | no | string | ``''`` |
116-
+-------------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+
117-
| :ref:`JOBTMPL/SphinxDocumentation/Input/unittest_xml_artifact` | no | string | ``''`` |
118-
+-------------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+
119-
| :ref:`JOBTMPL/SphinxDocumentation/Input/unittest_xml_directory` | no | string | ``'report/unit'`` |
120-
+-------------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+
121-
| :ref:`JOBTMPL/SphinxDocumentation/Input/html_artifact` | no | string | ``''`` |
122-
+-------------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+
123-
| :ref:`JOBTMPL/SphinxDocumentation/Input/latex_artifact` | no | string | ``''`` |
124-
+-------------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+
96+
+-------------------------------------------------------------------------+----------+----------------+-------------------------------------------------------------------+
97+
| Parameter Name | Required | Type | Default |
98+
+=========================================================================+==========+================+===================================================================+
99+
| :ref:`JOBTMPL/SphinxDocumentation/Input/ubuntu_image_version` | no | string | ``'24.04'`` |
100+
+-------------------------------------------------------------------------+----------+----------------+-------------------------------------------------------------------+
101+
| :ref:`JOBTMPL/SphinxDocumentation/Input/python_version` | no | string | ``'3.13'`` |
102+
+-------------------------------------------------------------------------+----------+----------------+-------------------------------------------------------------------+
103+
| :ref:`JOBTMPL/SphinxDocumentation/Input/requirements` | no | string | ``'-r doc/requirements.txt'`` |
104+
+-------------------------------------------------------------------------+----------+----------------+-------------------------------------------------------------------+
105+
| :ref:`JOBTMPL/SphinxDocumentation/Input/doc_directory` | no | string | ``'doc'`` |
106+
+-------------------------------------------------------------------------+----------+----------------+-------------------------------------------------------------------+
107+
| :ref:`JOBTMPL/SphinxDocumentation/Input/coverage_json_artifact` | no | string | ``''`` |
108+
+-------------------------------------------------------------------------+----------+----------------+-------------------------------------------------------------------+
109+
| :ref:`JOBTMPL/SphinxDocumentation/Input/coverage_report_json` | no | string (JSON) | :jsoncode:`{"directory": "report/coverage"}` |
110+
+-------------------------------------------------------------------------+----------+----------------+-------------------------------------------------------------------+
111+
| :ref:`JOBTMPL/SphinxDocumentation/Input/unittest_xml_artifact` | no | string | ``''`` |
112+
+-------------------------------------------------------------------------+----------+----------------+-------------------------------------------------------------------+
113+
| :ref:`JOBTMPL/SphinxDocumentation/Input/unittest_xml` | no | string (JSON) | :jsoncode:`{"directory": "report/unit"}` |
114+
+-------------------------------------------------------------------------+----------+----------------+-------------------------------------------------------------------+
115+
| :ref:`JOBTMPL/SphinxDocumentation/Input/html_artifact` | no | string | ``''`` |
116+
+-------------------------------------------------------------------------+----------+----------------+-------------------------------------------------------------------+
117+
| :ref:`JOBTMPL/SphinxDocumentation/Input/latex_artifact` | no | string | ``''`` |
118+
+-------------------------------------------------------------------------+----------+----------------+-------------------------------------------------------------------+
125119

126120
.. rubric:: Goto :ref:`secrets <JOBTMPL/SphinxDocumentation/Secrets>`
127121

@@ -178,18 +172,6 @@ doc_directory
178172
adjusted as well.
179173

180174

181-
.. _JOBTMPL/SphinxDocumentation/Input/coverage_report_json_directory:
182-
183-
coverage_report_json_directory
184-
==============================
185-
186-
:Type: string
187-
:Required: no
188-
:Default Value: ``''``
189-
:Possible Values: Any valid directory or sub-directory.
190-
:Description: tbd
191-
192-
193175
.. _JOBTMPL/SphinxDocumentation/Input/coverage_json_artifact:
194176

195177
coverage_json_artifact
@@ -202,6 +184,40 @@ coverage_json_artifact
202184
:Description: Name of the artifact containing the code coverage report in JSON format.
203185

204186

187+
.. _JOBTMPL/SphinxDocumentation/Input/coverage_report_json:
188+
189+
coverage_report_json
190+
====================
191+
192+
:Type: string (JSON)
193+
:Required: no
194+
:Default Value:
195+
.. code-block:: json
196+
197+
{ "directory": "reports/coverage",
198+
}
199+
:Possible Values: Any valid JSON string containing a JSON object with fields:
200+
201+
:directory: Directory or sub-directory where the code coverage JSON report will be extracted from
202+
:ref:`artifact <JOBTMPL/SphinxDocumentation/Input/coverage_json_artifact>`.
203+
:Description: Directory as JSON object where the code coverage JSON report will be extracted. |br|
204+
This path is configured in :file:`pyproject.toml` and can be extracted by
205+
:ref:`JOBTMPL/ExtractConfiguration`.
206+
:Example:
207+
.. code-block:: yaml
208+
209+
ConfigParams:
210+
uses: pyTooling/Actions/.github/workflows/ExtractConfiguration.yml@r5
211+
212+
Documentation:
213+
uses: pyTooling/Actions/.github/workflows/SphinxDocumentation.yml@r5
214+
needs:
215+
- ConfigParams
216+
with:
217+
...
218+
coverage_report_json: ${{ needs.ConfigParams.outputs.coverage_report_json }}
219+
220+
205221
.. _JOBTMPL/SphinxDocumentation/Input/unittest_xml_artifact:
206222

207223
unittest_xml_artifact
@@ -214,16 +230,38 @@ unittest_xml_artifact
214230
:Description: Name of the artifact containing the unittest XML report summary in XML format.
215231

216232

217-
.. _JOBTMPL/SphinxDocumentation/Input/unittest_xml_directory:
233+
.. _JOBTMPL/SphinxDocumentation/Input/unittest_xml:
218234

219-
unittest_xml_directory
220-
======================
235+
unittest_xml
236+
============
221237

222-
:Type: string
238+
:Type: string (JSON)
223239
:Required: no
224-
:Default Value: ``'report/unit'``
225-
:Possible Values: Any valid directory or sub-directory.
226-
:Description: Directory where unittest XML artifact will be extracted.
240+
:Default Value:
241+
.. code-block:: json
242+
243+
{ "directory": "reports/unit",
244+
}
245+
:Possible Values: Any valid JSON string containing a JSON object with fields:
246+
247+
:directory: Directory or sub-directory where the unittest JUnit XML report will be extracted from
248+
:ref:`artifact <JOBTMPL/SphinxDocumentation/Input/unittest_xml_artifact>`.
249+
:Description: Directory as JSON object where the unittest JUnit XML report will be extracted. |br|
250+
This path is configured in :file:`pyproject.toml` and can be extracted by
251+
:ref:`JOBTMPL/ExtractConfiguration`.
252+
:Example:
253+
.. code-block:: yaml
254+
255+
ConfigParams:
256+
uses: pyTooling/Actions/.github/workflows/ExtractConfiguration.yml@r5
257+
258+
Documentation:
259+
uses: pyTooling/Actions/.github/workflows/SphinxDocumentation.yml@r5
260+
needs:
261+
- ConfigParams
262+
with:
263+
...
264+
unittest_xml: ${{ needs.ConfigParams.outputs.unittest_xml }}
227265
228266
229267
.. _JOBTMPL/SphinxDocumentation/Input/html_artifact:

‎doc/JobTemplate/Quality/CheckDocumentation.rst‎

Lines changed: 0 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -46,12 +46,6 @@ requires a `name` parameter to create the artifact names.
4646

4747
.. code-block:: yaml
4848
49-
name: Pipeline
50-
51-
on:
52-
push:
53-
workflow_dispatch:
54-
5549
jobs:
5650
ConfigParams:
5751
uses: pyTooling/Actions/.github/workflows/ExtractConfiguration.yml@r5

‎doc/JobTemplate/Release/TagReleaseCommit.rst‎

Lines changed: 0 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -54,12 +54,6 @@ other reason. Its outputs are used to either run a ``TriggerTaggedRelease`` job
5454

5555
.. code-block:: yaml
5656
57-
name: Pipeline
58-
59-
on:
60-
push:
61-
workflow_dispatch:
62-
6357
jobs:
6458
Prepare:
6559
uses: pyTooling/Actions/.github/workflows/PrepareJob.yml@r5

‎doc/JobTemplate/Setup/Parameters.rst‎

Lines changed: 0 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -60,12 +60,6 @@ Simple Example
6060

6161
.. code-block:: yaml
6262
63-
name: Pipeline
64-
65-
on:
66-
push:
67-
workflow_dispatch:
68-
6963
jobs:
7064
Params:
7165
uses: pyTooling/Actions/.github/workflows/Parameters.yml@r5

0 commit comments

Comments
 (0)