Partially documented SphinxDocumentation and LaTeXDocumentation.

doc/JobTemplate/AllInOne/CompletePipeline.rst

@@ -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.
 

doc/JobTemplate/Documentation/LaTeXDocumentation.rst

@@ -3,20 +3,181 @@
 LatexDocumentation
 ##################
 
-.. todo:: LatexDocumentation:Needs documentation.
+The ``LatexDocumentation`` job template ................
 
-**Behavior:**
+.. topic:: Features
+
+   * Translate a LaTeX document to PDF.
+
+.. topic:: Behavior:
 
    .. todo:: LatexDocumentation:Behavior needs documentation.
 
-**Dependencies:**
+.. topic:: Job Execution
 
-.. todo:: LatexDocumentation:Dependencies needs documentation.
+   .. 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.

doc/JobTemplate/Documentation/SphinxDocumentation.rst

@@ -3,20 +3,276 @@
 SphinxDocumentation
 ###################
 
-.. todo:: SphinxDocumentation:Needs documentation.
+The ``SphinxDocumentation`` job template ..........
 
-**Behavior:**
+.. topic:: Features
+
+   * 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`).
+
+     * 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>`__
+
+   * 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.
 
-**Dependencies:**
+.. topic:: Job Execution
 
-.. todo:: SphinxDocumentation:Dependencies needs documentation.
+   .. 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.

doc/JobTemplate/Setup/ExtractConfiguration.rst

@@ -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                                                       |

doc/JobTemplate/Setup/Parameters.rst

@@ -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                                                       |

doc/JobTemplate/Setup/PrepareJob.rst

@@ -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                                                       |

tests/requirements.txt

@@ -9,5 +9,5 @@ pytest-cov ~= 6.2
 
 # Static Type Checking
 mypy ~= 1.17
-typing_extensions ~= 4.14
+typing_extensions ~= 4.15
 lxml ~= 6.0