pyTooling/Actions
1
0
Fork 0
mirror of https://github.com/pyTooling/Actions.git synced 2026-02-12 02:56:56 +08:00
Code Issues Packages Projects Releases Wiki Activity

Partially documented SphinxDocumentation and LaTeXDocumentation.

Browse Source
This commit is contained in:
Patrick Lehmann
2025-08-23 19:56:51 +02:00
parent 817c84af2e
commit 277df7ea7f
8 changed files with 440 additions and 23 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
doc/JobTemplate/AllInOne/CompletePipeline.rst
View File

@@ -258,7 +258,7 @@ Parameter Summary
| :ref:`JOBTMPL/CompletePipeline/Input/cleanup` | no | string | ``'true'`` |
+---------------------------------------------------------------------+----------+----------+-------------------------------------------------+
.. rubric:: Goto Goto :ref:`secrets <JOBTMPL/CompletePipeline/Secrets>`
.. rubric:: Goto :ref:`secrets <JOBTMPL/CompletePipeline/Secrets>`
+-----------------------------------------------------------+----------+----------+--------------+
| Token Name | Required | Type | Default |
@@ -270,7 +270,7 @@ Parameter Summary
| :ref:`JOBTMPL/CompletePipeline/Secret/CODACY_TOKEN` | no | string | — — — — |
+-----------------------------------------------------------+----------+----------+--------------+
.. rubric:: Goto Goto :ref:`output parameters <JOBTMPL/CompletePipeline/Outputs>`
.. rubric:: Goto :ref:`output parameters <JOBTMPL/CompletePipeline/Outputs>`
This job template has no output parameters.

175
doc/JobTemplate/Documentation/LaTeXDocumentation.rst
View File

@@ -3,20 +3,181 @@
LatexDocumentation
##################
.. todo:: LatexDocumentation:Needs documentation.
The ``LatexDocumentation`` job template ................
**Behavior:**
.. topic:: Features
.. todo:: LatexDocumentation:Behavior needs documentation.
* Translate a LaTeX document to PDF.
**Dependencies:**
.. topic:: Behavior:
.. todo:: LatexDocumentation:Dependencies needs documentation.
.. todo:: LatexDocumentation:Behavior needs documentation.
.. topic:: Job Execution
.. image:: ../../_static/pyTooling-Actions-LatexDocumentation.png
:width: 600px
.. topic:: Dependencies
* :gh:`pyTooling/download-artifact`
* :gh:`actions/download-artifact`
* :gh:`pyTooling/upload-artifact`
* :gh:`actions/upload-artifact`
* :gh:`addnab/docker-run-action`
* :dockerhub:`pytooling/miktex:sphinx`
.. _JOBTMPL/LatexDocumentation/Instantiation:
Instantiation
*************
Simple Example
The following instantiation example creates a job `Params` derived from job template `Parameters` version `r0`. It only
requires a `name` parameter to create the artifact names.
.. code-block:: yaml
name: Pipeline
on:
push:
workflow_dispatch:
jobs:
UnitTestingParams:
uses: pyTooling/Actions/.github/workflows/Parameters.yml@r5
with:
package_name: myPackage
Documentation:
uses: pyTooling/Actions/.github/workflows/SphinxDocumentation.yml@r5
needs:
- UnitTestingParams
with:
python_version: ${{ needs.UnitTestingParams.outputs.python_version }}
html_artifact: ${{ fromJson(needs.UnitTestingParams.outputs.artifact_names).documentation_html }}
latex_artifact: ${{ fromJson(needs.UnitTestingParams.outputs.artifact_names).documentation_latex }}
PDFDocumentation:
uses: pyTooling/Actions/.github/workflows/LaTeXDocumentation.yml@r5
needs:
- UnitTestingParams
- Documentation
with:
document: pyEDAA.ProjectModel
latex_artifact: ${{ fromJson(needs.UnitTestingParams.outputs.artifact_names).documentation_latex }}
pdf_artifact: ${{ fromJson(needs.UnitTestingParams.outputs.artifact_names).documentation_pdf }}
.. seealso::
:ref:`JOBTMPL/TagReleaseCommit`
``LatexDocumentation`` is usualy
.. _JOBTMPL/LatexDocumentation/Parameters:
Parameter Summary
*****************
.. rubric:: Goto :ref:`input parameters <JOBTMPL/LatexDocumentation/Inputs>`
+---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+
| Parameter Name | Required | Type | Default |
+=====================================================================+==========+==========+===================================================================+
| :ref:`JOBTMPL/LatexDocumentation/Input/ubuntu_image_version` | no | string | ``'24.04'`` |
+---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+
| :ref:`JOBTMPL/LatexDocumentation/Input/document` | yes | string | — — — — |
+---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+
| :ref:`JOBTMPL/LatexDocumentation/Input/latex_artifact` | no | string | ``''`` |
+---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+
| :ref:`JOBTMPL/LatexDocumentation/Input/pdf_artifact` | no | string | ``''`` |
+---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+
.. rubric:: Goto :ref:`secrets <JOBTMPL/LatexDocumentation/Secrets>`
This job template needs no secrets.
.. rubric:: Goto :ref:`output parameters <JOBTMPL/LatexDocumentation/Outputs>`
This job template has no output parameters.
.. _JOBTMPL/LatexDocumentation/Inputs:
Input Parameters
****************
.. _JOBTMPL/LatexDocumentation/Input/ubuntu_image_version:
ubuntu_image_version
====================
:Type: string
:Required: no
:Default Value: ``'24.04'``
:Possible Values: See `actions/runner-images - Available Images <https://github.com/actions/runner-images?tab=readme-ov-file#available-images>`__
for available Ubuntu image versions.
:Description: Version of the Ubuntu image used to run this job.
.. note::
Unfortunately, GitHub Actions has only a `limited set of functions <https://docs.github.com/en/actions/reference/workflows-and-actions/expressions#functions>`__,
thus, the usual Ubuntu image name like ``'ubuntu-24.04'`` can't be split into image name and image
version.
.. _JOBTMPL/LatexDocumentation/Input/document:
document
========
:Type: string
:Required: yes
:Default Value: — — — —
:Possible Values: tbd
:Description: tbd
.. _JOBTMPL/LatexDocumentation/Input/latex_artifact:
latex_artifact
==============
.. todo:: LatexDocumentation:Simple example needs documentation.
:Type: string
:Required: no
:Default Value: ``''``
:Possible Values: tbd
:Description: tbd
.. _JOBTMPL/LatexDocumentation/Input/pdf_artifact:
pdf_artifact
============
:Type: string
:Required: no
:Default Value: ``''``
:Possible Values: tbd
:Description: tbd
.. _JOBTMPL/LatexDocumentation/Secrets:
Secrets
*******
This job template needs no secrets.
.. _JOBTMPL/LatexDocumentation/Outputs:
Outputs
*******
This job template has no output parameters.

270
doc/JobTemplate/Documentation/SphinxDocumentation.rst
View File

@@ -3,20 +3,276 @@
SphinxDocumentation
###################
.. todo:: SphinxDocumentation:Needs documentation.
The ``SphinxDocumentation`` job template ..........
**Behavior:**
.. topic:: Features
.. todo:: SphinxDocumentation:Behavior needs documentation.
* Build documentation using Sphinx as HTML and upload as artifact. |br|
(see :ref:`JOBTMPL/SphinxDocumentation/Input/html_artifact`).
* Build documentation using Sphinx as LaTeX and upload as artifact. |br|
(see :ref:`JOBTMPL/SphinxDocumentation/Input/latex_artifact`).
**Dependencies:**
* Workaround `sphinx-doc/sphinx#13189 <https://github.com/sphinx-doc/sphinx/issues/13189>`__
* Workaround `sphinx-doc/sphinx#13190 <https://github.com/sphinx-doc/sphinx/issues/13190>`__
.. todo:: SphinxDocumentation:Dependencies needs documentation.
* Optionally: download code coverage artifact (JSON format) given by :ref:`JOBTMPL/SphinxDocumentation/Input/coverage_json_artifact`.
* Optionally: download unit test report artifact (XML format) given by :ref:`JOBTMPL/SphinxDocumentation/Input/unittest_xml_artifact`.
.. topic:: Behavior:
.. todo:: SphinxDocumentation:Behavior needs documentation.
.. topic:: Job Execution
.. image:: ../../_static/pyTooling-Actions-SphinxDocumentation.png
:width: 600px
.. topic:: Dependencies
* :gh:`actions/checkout`
* :gh:`actions/setup-python`
* :gh:`pyTooling/download-artifact`
* :gh:`actions/download-artifact`
* :gh:`pyTooling/upload-artifact`
* :gh:`actions/upload-artifact`
* apt
* `graphviz <https://graphviz.org/>`__
* pip
* :pip:`wheel`
* Python packages specified via :ref:`JOBTMPL/SphinxDocumentation/Input/requirements`.
.. _JOBTMPL/SphinxDocumentation/Instantiation:
Instantiation
*************
Simple Example
The following instantiation example creates a job `Params` derived from job template `Parameters` version `r0`. It only
requires a `name` parameter to create the artifact names.
.. code-block:: yaml
name: Pipeline
on:
push:
workflow_dispatch:
jobs:
UnitTestingParams:
uses: pyTooling/Actions/.github/workflows/Parameters.yml@r5
with:
package_name: myPackage
Documentation:
uses: pyTooling/Actions/.github/workflows/SphinxDocumentation.yml@r5
needs:
- UnitTestingParams
with:
python_version: ${{ needs.UnitTestingParams.outputs.python_version }}
html_artifact: ${{ fromJson(needs.UnitTestingParams.outputs.artifact_names).documentation_html }}
latex_artifact: ${{ fromJson(needs.UnitTestingParams.outputs.artifact_names).documentation_latex }}
.. seealso::
:ref:`JOBTMPL/TagReleaseCommit`
``SphinxDocumentation`` is usualy
.. _JOBTMPL/SphinxDocumentation/Parameters:
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 | ``''`` |
+-------------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+
.. rubric:: Goto :ref:`secrets <JOBTMPL/SphinxDocumentation/Secrets>`
This job template needs no secrets.
.. rubric:: Goto :ref:`output parameters <JOBTMPL/SphinxDocumentation/Outputs>`
This job template has no output parameters.
.. _JOBTMPL/SphinxDocumentation/Inputs:
Input Parameters
****************
.. _JOBTMPL/SphinxDocumentation/Input/ubuntu_image_version:
ubuntu_image_version
====================
:Type: string
:Required: no
:Default Value: ``'24.04'``
:Possible Values: See `actions/runner-images - Available Images <https://github.com/actions/runner-images?tab=readme-ov-file#available-images>`__
for available Ubuntu image versions.
:Description: Version of the Ubuntu image used to run this job.
.. note::
Unfortunately, GitHub Actions has only a `limited set of functions <https://docs.github.com/en/actions/reference/workflows-and-actions/expressions#functions>`__,
thus, the usual Ubuntu image name like ``'ubuntu-24.04'`` can't be split into image name and image
version.
.. _JOBTMPL/SphinxDocumentation/Input/python_version:
python_version
==============
.. todo:: SphinxDocumentation:Simple example needs documentation.
:Type: string
:Required: no
:Default Value: ``'3.13'``
:Possible Values: Any valid Python version conforming to the pattern ``<major>.<minor>`` or ``pypy-<major>.<minor>``. |br|
See `actions/python-versions - available Python versions <https://github.com/actions/python-versions>`__
and `actions/setup-python - configurable Python versions <https://github.com/actions/setup-python>`__.
:Description: Python version used as default for other jobs requiring a single Python version. |br|
In case :ref:`JOBTMPL/Parameters/Input/python_version_list` is an empty string, this version is used
to populate the version list.
.. _JOBTMPL/SphinxDocumentation/Input/requirements:
requirements
============
:Type: string
:Required: no
:Default Value: ``'-r doc/requirements.txt'``
:Possible Values: tbd
:Description: tbd
.. _JOBTMPL/SphinxDocumentation/Input/doc_directory:
doc_directory
=============
:Type: string
:Required: no
:Default Value: ``'doc'``
:Possible Values: tbd
:Description: tbd
.. _JOBTMPL/SphinxDocumentation/Input/coverage_report_json_directory:
coverage_report_json_directory
==============================
:Type: string
:Required: no
:Default Value: ``''``
:Possible Values: tbd
:Description: tbd
.. _JOBTMPL/SphinxDocumentation/Input/coverage_json_artifact:
coverage_json_artifact
======================
:Type: string
:Required: no
:Default Value: ``''``
:Possible Values: tbd
:Description: tbd
.. _JOBTMPL/SphinxDocumentation/Input/unittest_xml_artifact:
unittest_xml_artifact
=====================
:Type: string
:Required: no
:Default Value: ``''``
:Possible Values: tbd
:Description: tbd
.. _JOBTMPL/SphinxDocumentation/Input/unittest_xml_directory:
unittest_xml_directory
======================
:Type: string
:Required: no
:Default Value: ``''``
:Possible Values: tbd
:Description: tbd
.. _JOBTMPL/SphinxDocumentation/Input/html_artifact:
html_artifact
=============
:Type: string
:Required: no
:Default Value: ``''``
:Possible Values: tbd
:Description: tbd
.. _JOBTMPL/SphinxDocumentation/Input/latex_artifact:
latex_artifact
==============
:Type: string
:Required: no
:Default Value: ``''``
:Possible Values: tbd
:Description: tbd
.. _JOBTMPL/SphinxDocumentation/Secrets:
Secrets
*******
This job template needs no secrets.
.. _JOBTMPL/SphinxDocumentation/Outputs:
Outputs
*******
This job template has no output parameters.

4
doc/JobTemplate/Setup/ExtractConfiguration.rst
View File

@@ -112,11 +112,11 @@ Parameter Summary
| :ref:`JOBTMPL/ExtractConfiguration/Input/coverage_config` | no | string | ``'pyproject.toml'`` |
+---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+
.. rubric:: Goto Goto :ref:`secrets <JOBTMPL/ExtractConfiguration/Secrets>`
.. rubric:: Goto :ref:`secrets <JOBTMPL/ExtractConfiguration/Secrets>`
This job template needs no secrets.
.. rubric:: Goto Goto :ref:`output parameters <JOBTMPL/ExtractConfiguration/Outputs>`
.. rubric:: Goto :ref:`output parameters <JOBTMPL/ExtractConfiguration/Outputs>`
+---------------------------------------------------------------------------------+----------+-------------------------------------------------------------------+
| Result Name | Type | Description |

4
doc/JobTemplate/Setup/Parameters.rst
View File

@@ -187,11 +187,11 @@ Parameter Summary
| :ref:`JOBTMPL/Parameters/Input/pipeline-delay` | no | number | ``0`` |
+---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+
.. rubric:: Goto Goto :ref:`secrets <JOBTMPL/Parameters/Secrets>`
.. rubric:: Goto :ref:`secrets <JOBTMPL/Parameters/Secrets>`
This job template needs no secrets.
.. rubric:: Goto Goto :ref:`output parameters <JOBTMPL/Parameters/Outputs>`
.. rubric:: Goto :ref:`output parameters <JOBTMPL/Parameters/Outputs>`
+---------------------------------------------------------------------+----------+-------------------------------------------------------------------+
| Result Name | Type | Description |

4
doc/JobTemplate/Setup/PrepareJob.rst
View File

@@ -113,11 +113,11 @@ Parameter Summary
| :ref:`JOBTMPL/PrepareJob/Input/release_tag_pattern` | no | string | ``'(v|r)?[0-9]+(\.[0-9]+){0,2}(-(dev|alpha|beta|rc)([0-9]*))?'`` |
+---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+
.. rubric:: Goto Goto :ref:`secrets <JOBTMPL/PrepareJob/Secrets>`
.. rubric:: Goto :ref:`secrets <JOBTMPL/PrepareJob/Secrets>`
This job template needs no secrets.
.. rubric:: Goto Goto :ref:`output parameters <JOBTMPL/PrepareJob/Outputs>`
.. rubric:: Goto :ref:`output parameters <JOBTMPL/PrepareJob/Outputs>`
+---------------------------------------------------------------------+----------+-------------------------------------------------------------------+
| Result Name | Type | Description |

BIN
doc/_static/pyTooling-Actions-SphinxDocumentation.png vendored Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 150 KiB