Improved SphinxDocumentation and LaTeXDocumentation.

.github/workflows/LaTeXDocumentation.yml

@@ -29,14 +29,18 @@ on:
         required: false
         default: '24.04'
         type: string
+      latex_artifact:
+        description: 'Name of the LaTeX documentation artifact.'
+        required: true
+        type: string
       document:
         description: 'LaTeX root document without *.tex extension.'
         required: true
         type: string
-      latex_artifact:
+      processor:
-        description: 'Name of the LaTeX documentation artifact.'
+        description: 'Name of the used LaTeX processor.'
         required: false
-        default: ''
+        default: 'xelatex'
         type: string
       pdf_artifact:
         description: 'Name of the PDF documentation artifact.'
@@ -55,21 +59,22 @@ jobs:
           name: ${{ inputs.latex_artifact }}
           path: latex
 
-      - name: Debug
+#      - name: Debug
-        run: |
+#        run: |
-          tree -pash .
+#          tree -pash .
 
       - name: Build LaTeX document using 'pytooling/miktex:sphinx'
         uses: addnab/docker-run-action@v3
+        if: inputs.pdf_artifact != ''
         with:
           image: pytooling/miktex:sphinx
           options: -v ${{ github.workspace }}/latex:/latex --workdir /latex
           run: |
-            which pdflatex
+            # which ${{ inputs.processor }}
-            pwd
+            # pwd
-            ls -lAh
+            # ls -lAh
 
-            latexmk -xelatex ${{ inputs.document }}.tex
+            latexmk -${{ inputs.processor }} "${{ inputs.document }}.tex"
 
       - name: 📤 Upload 'PDF Documentation' artifact
         uses: pyTooling/upload-artifact@v4

.github/workflows/SphinxDocumentation.yml

@@ -59,7 +59,7 @@ on:
         default: ''
         type: string
       unittest_xml_directory:
-        description: 'Directory where unittest XML artifact is extracted.'
+        description: 'Directory where unittest XML artifact will be extracted.'
         required: false
         default: 'report/unit'
         type: string

doc/JobTemplate/AllInOne/CompletePipeline.rst

@@ -639,3 +639,14 @@ Outputs
 *******
 
 This job template has no output parameters.
+
+
+.. _JOBTMPL/CompletePipeline/Optimizations:
+
+Optimizations
+*************
+
+The following optimizations can be used to reduce the template's runtime.
+
+TBD
+  tbd tbd tbd

doc/JobTemplate/Documentation/LaTeXDocumentation.rst

@@ -5,6 +5,8 @@ LatexDocumentation
 
 The ``LatexDocumentation`` job template ................
 
+* uses xelatex and latexmk
+
 .. topic:: Features
 
    * Translate a LaTeX document to PDF.
@@ -30,7 +32,7 @@ The ``LatexDocumentation`` job template ................
 
    * :gh:`addnab/docker-run-action`
 
-     * :dockerhub:`pytooling/miktex:sphinx`
+     * :dockerhub:`pytooling/miktex <pytooling/miktex:sphinx>`
 
 
 .. _JOBTMPL/LatexDocumentation/Instantiation:
@@ -92,9 +94,11 @@ Parameter Summary
 +=====================================================================+==========+==========+===================================================================+
 | :ref:`JOBTMPL/LatexDocumentation/Input/ubuntu_image_version`        | no       | string   | ``'24.04'``                                                       |
 +---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+
+| :ref:`JOBTMPL/LatexDocumentation/Input/latex_artifact`              | yes      | string   | — — — —                                                           |
++---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+
 | :ref:`JOBTMPL/LatexDocumentation/Input/document`                    | yes      | string   | — — — —                                                           |
 +---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+
-| :ref:`JOBTMPL/LatexDocumentation/Input/latex_artifact`              | no       | string   | ``''``                                                            |
+| :ref:`JOBTMPL/LatexDocumentation/Input/processor`                   | no       | string   | ``'xelatex'``                                                     |
 +---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+
 | :ref:`JOBTMPL/LatexDocumentation/Input/pdf_artifact`                | no       | string   | ``''``                                                            |
 +---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+
@@ -131,6 +135,18 @@ ubuntu_image_version
                      thus, the usual Ubuntu image name like ``'ubuntu-24.04'`` can't be split into image name and image
                      version.
 
+.. _JOBTMPL/LatexDocumentation/Input/latex_artifact:
+
+latex_artifact
+==============
+
+:Type:            string
+:Required:        yes
+:Default Value:   — — — —
+:Possible Values: Any valid artifact name.
+:Description:     name of the artifact containing the LaTeX document to translate.
+
+
 .. _JOBTMPL/LatexDocumentation/Input/document:
 
 document
@@ -139,20 +155,20 @@ document
 :Type:            string
 :Required:        yes
 :Default Value:   — — — —
-:Possible Values: tbd
+:Possible Values: Any valid document name.
-:Description:     tbd
+:Description:     Name of the LaTeX document
 
 
-.. _JOBTMPL/LatexDocumentation/Input/latex_artifact:
+.. _JOBTMPL/LatexDocumentation/Input/processor:
 
-latex_artifact
+processor
-==============
+=========
 
 :Type:            string
 :Required:        no
-:Default Value:   ``''``
+:Default Value:   ``'xelatex'``
-:Possible Values: tbd
+:Possible Values: Any supported LaTeX processor supported by MikTeX and ``latexmk``.
-:Description:     tbd
+:Description:     Name of the used LaTeX processor.
 
 
 .. _JOBTMPL/LatexDocumentation/Input/pdf_artifact:
@@ -163,9 +179,12 @@ pdf_artifact
 :Type:            string
 :Required:        no
 :Default Value:   ``''``
-:Possible Values: tbd
+:Possible Values: Any valid artifact name.
-:Description:     tbd
+:Description:     Name of the artifact containing the generated PDF document.
+:Optimization:
+                  .. hint::
 
+                     If this parameter is empty, no PDF file will be generated and no artifact will be uploaded.
 
 .. _JOBTMPL/LatexDocumentation/Secrets:
 
@@ -181,3 +200,14 @@ Outputs
 *******
 
 This job template has no output parameters.
+
+
+.. _JOBTMPL/LatexDocumentation/Optimizations:
+
+Optimizations
+*************
+
+The following optimizations can be used to reduce the template's runtime.
+
+Disable PDF generation and PDF artifact
+  If parameter :ref:`JOBTMPL/LatexDocumentation/Input/pdf_artifact` is empty, no PDF will be generated and uploaded.

doc/JobTemplate/Documentation/SphinxDocumentation.rst

@@ -45,7 +45,7 @@ The ``SphinxDocumentation`` job template ..........
 
    * pip
 
-     * :pip:`wheel`
+     * :pypi:`wheel`
      * Python packages specified via :ref:`JOBTMPL/SphinxDocumentation/Input/requirements`.
 
 
@@ -174,8 +174,10 @@ requirements
 :Type:            string
 :Required:        no
 :Default Value:   ``'-r doc/requirements.txt'``
-:Possible Values: tbd
+:Possible Values: Any valid list of parameters for ``pip install``. |br|
-:Description:     tbd
+                  Either a requirements file can be referenced using ``'-r path/to/requirements.txt'``, or a list of
+                  packages can be specified using a space separated list like ``'Sphinx sphinx_rtd_theme sphinxcontrib-mermaid'``.
+:Description:     Python dependencies to be installed through pip.
 
 
 .. _JOBTMPL/SphinxDocumentation/Input/doc_directory:
@@ -186,8 +188,13 @@ doc_directory
 :Type:            string
 :Required:        no
 :Default Value:   ``'doc'``
-:Possible Values: tbd
+:Possible Values: Any valid directory or sub-directory.
-:Description:     tbd
+:Description:     Directory where the Sphinx documentation is located.
+
+                  .. attention::
+
+                     When this parameter gets changed, :ref:`JOBTMPL/SphinxDocumentation/Input/requirements` needs to be
+                     adjusted as well.
 
 
 .. _JOBTMPL/SphinxDocumentation/Input/coverage_report_json_directory:
@@ -198,7 +205,7 @@ coverage_report_json_directory
 :Type:            string
 :Required:        no
 :Default Value:   ``''``
-:Possible Values: tbd
+:Possible Values: Any valid directory or sub-directory.
 :Description:     tbd
 
 
@@ -210,8 +217,8 @@ coverage_json_artifact
 :Type:            string
 :Required:        no
 :Default Value:   ``''``
-:Possible Values: tbd
+:Possible Values: Any valid artifact name.
-:Description:     tbd
+:Description:     Name of the artifact containing the code coverage report in JSON format.
 
 
 .. _JOBTMPL/SphinxDocumentation/Input/unittest_xml_artifact:
@@ -222,8 +229,8 @@ unittest_xml_artifact
 :Type:            string
 :Required:        no
 :Default Value:   ``''``
-:Possible Values: tbd
+:Possible Values: Any valid artifact name.
-:Description:     tbd
+:Description:     Name of the artifact containing the unittest XML report summary in XML format.
 
 
 .. _JOBTMPL/SphinxDocumentation/Input/unittest_xml_directory:
@@ -233,9 +240,9 @@ unittest_xml_directory
 
 :Type:            string
 :Required:        no
-:Default Value:   ``''``
+:Default Value:   ``'report/unit'``
-:Possible Values: tbd
+:Possible Values: Any valid directory or sub-directory.
-:Description:     tbd
+:Description:     Directory where unittest XML artifact will be extracted.
 
 
 .. _JOBTMPL/SphinxDocumentation/Input/html_artifact:
@@ -246,8 +253,12 @@ html_artifact
 :Type:            string
 :Required:        no
 :Default Value:   ``''``
-:Possible Values: tbd
+:Possible Values: Any valid artifact name.
-:Description:     tbd
+:Description:     Name of the artifact containing the generated HTML website.
+:Optimization:
+                  .. hint::
+
+                     If this parameter is empty, no HTML website will be generated and no artifact will be uploaded.
 
 
 .. _JOBTMPL/SphinxDocumentation/Input/latex_artifact:
@@ -258,8 +269,12 @@ latex_artifact
 :Type:            string
 :Required:        no
 :Default Value:   ``''``
-:Possible Values: tbd
+:Possible Values: Any valid artifact name.
-:Description:     tbd
+:Description:     Name of the artifact containing the generated LaTeX document and resource files (e.g., images).
+:Optimization:
+                  .. hint::
+
+                     If this parameter is empty, no LaTeX document will be generated and no artifact will be uploaded.
 
 
 .. _JOBTMPL/SphinxDocumentation/Secrets:
@@ -276,3 +291,18 @@ Outputs
 *******
 
 This job template has no output parameters.
+
+
+.. _JOBTMPL/SphinxDocumentation/Optimizations:
+
+Optimizations
+*************
+
+The following optimizations can be used to reduce the template's runtime.
+
+Disable HTML website generation and HTML artifact
+  If parameter :ref:`JOBTMPL/SphinxDocumentation/Input/html_artifact` is empty, no HTML website will be generated and
+  uploaded.
+Disable LaTeX document generation and laTeX artifact
+  If parameter :ref:`JOBTMPL/SphinxDocumentation/Input/latex_artifact` is empty, no LaTeX document will be generated and
+  uploaded.

doc/JobTemplate/Setup/ExtractConfiguration.rst

@@ -592,3 +592,11 @@ coverage_report_json
 
                      [tool.coverage.json]
                      output = "report/coverage/coverage.json"
+
+
+.. _JOBTMPL/LatexDocumentation/Optimizations:
+
+Optimizations
+*************
+
+This template offers no optimizations (reduced job runtime).

doc/JobTemplate/Setup/Parameters.rst

@@ -740,3 +740,20 @@ params
                   * ``params['typing']`` |rarr| ``artifact_names['statictyping_html']``
                   * ``params['package']`` |rarr| ``artifact_names['package_all']``
                   * ``params['doc']`` |rarr| ``artifact_names['documentation_html']``
+
+
+.. _JOBTMPL/LatexDocumentation/Optimizations:
+
+Optimizations
+*************
+
+This template offers no optimizations (reduced job runtime).
+
+Nontheless, the generated output :ref:`JOBTMPL/Parameters/Output/python_jobs` is influenced by many input parameters
+generating :math:`N^2` many Python job combinations, which in turn will influence the overall pipeline runtime and how many
+jobs (parallel VMs) are needed to execute the matrix.
+
+.. hint::
+
+   Some VM images (macOS, Windows) have parallelism limitations and run slower then Ubuntu-based jobs. Additionally,
+   environments like MSYS2 require an additional setup time increasing a jobs runtime segnificantly.

doc/JobTemplate/Setup/PrepareJob.rst

@@ -449,3 +449,11 @@ pr_number
                   :ref:`merge commit <JOBTMPL/PrepareJob/Output/is_merge_commit>` and the located pull-request's title
                   for this commit matches :ref:`JOBTMPL/PrepareJob/Input/release_tag_pattern`, otherwise returns an
                   empty string ``''``.
+
+
+.. _JOBTMPL/LatexDocumentation/Optimizations:
+
+Optimizations
+*************
+
+This template offers no optimizations (reduced job runtime).

doc/conf.py

@@ -214,12 +214,13 @@ autodoc_typehints = "both"
 # Sphinx.Ext.ExtLinks
 # ==============================================================================
 extlinks = {
-	"gh":      (f"https://GitHub.com/%s", "GitHub: %s"),
+	"gh":        (f"https://GitHub.com/%s", "GitHub: %s"),
-	"ghissue": (f"https://GitHub.com/{githubNamespace}/{githubProject}/issues/%s", "issue #%s"),
+	"ghissue":   (f"https://GitHub.com/{githubNamespace}/{githubProject}/issues/%s", "issue #%s"),
-	"ghpull":  (f"https://GitHub.com/{githubNamespace}/{githubProject}/pull/%s", "pull request #%s"),
+	"ghpull":    (f"https://GitHub.com/{githubNamespace}/{githubProject}/pull/%s", "pull request #%s"),
-	"ghsrc":   (f"https://GitHub.com/{githubNamespace}/{githubProject}/blob/main/%s", None),
+	"ghsrc":     (f"https://GitHub.com/{githubNamespace}/{githubProject}/blob/main/%s", None),
-	"wiki":    (f"https://en.wikipedia.org/wiki/%s", None),
+	"wiki":      (f"https://en.wikipedia.org/wiki/%s", None),
-	"pypi":    (f"https://pypi.org/project/%s/", "PyPI: %s"),
+	"pypi":      (f"https://pypi.org/project/%s/", "PyPI: %s"),
+	"dockerhub": (f"https://hub.docker.com/r/%s", "Docker Hub: %s"),
 }