diff --git a/.github/workflows/LaTeXDocumentation.yml b/.github/workflows/LaTeXDocumentation.yml index 89d844f..a842d2c 100644 --- a/.github/workflows/LaTeXDocumentation.yml +++ b/.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: - description: 'Name of the LaTeX documentation artifact.' + processor: + 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 - run: | - tree -pash . +# - name: Debug +# run: | +# 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 - pwd - ls -lAh + # which ${{ inputs.processor }} + # pwd + # ls -lAh - latexmk -xelatex ${{ inputs.document }}.tex + latexmk -${{ inputs.processor }} "${{ inputs.document }}.tex" - name: 📤 Upload 'PDF Documentation' artifact uses: pyTooling/upload-artifact@v4 diff --git a/.github/workflows/SphinxDocumentation.yml b/.github/workflows/SphinxDocumentation.yml index fe6270d..145ffd4 100644 --- a/.github/workflows/SphinxDocumentation.yml +++ b/.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 diff --git a/doc/JobTemplate/AllInOne/CompletePipeline.rst b/doc/JobTemplate/AllInOne/CompletePipeline.rst index 0872132..a42b1c3 100644 --- a/doc/JobTemplate/AllInOne/CompletePipeline.rst +++ b/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 diff --git a/doc/JobTemplate/Documentation/LaTeXDocumentation.rst b/doc/JobTemplate/Documentation/LaTeXDocumentation.rst index e2cd7df..ac308ee 100644 --- a/doc/JobTemplate/Documentation/LaTeXDocumentation.rst +++ b/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 ` .. _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 -:Description: tbd +:Possible Values: Any valid document name. +:Description: Name of the LaTeX document -.. _JOBTMPL/LatexDocumentation/Input/latex_artifact: +.. _JOBTMPL/LatexDocumentation/Input/processor: -latex_artifact -============== +processor +========= :Type: string :Required: no -:Default Value: ``''`` -:Possible Values: tbd -:Description: tbd +:Default Value: ``'xelatex'`` +:Possible Values: Any supported LaTeX processor supported by MikTeX and ``latexmk``. +: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 -:Description: tbd +:Possible Values: Any valid artifact name. +: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. diff --git a/doc/JobTemplate/Documentation/SphinxDocumentation.rst b/doc/JobTemplate/Documentation/SphinxDocumentation.rst index eb234cf..94a8ee2 100644 --- a/doc/JobTemplate/Documentation/SphinxDocumentation.rst +++ b/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 -:Description: tbd +:Possible Values: Any valid list of parameters for ``pip install``. |br| + 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 -:Description: tbd +:Possible Values: Any valid directory or sub-directory. +: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 -:Description: tbd +:Possible Values: Any valid artifact name. +: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 -:Description: tbd +:Possible Values: Any valid artifact name. +: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: ``''`` -:Possible Values: tbd -:Description: tbd +:Default Value: ``'report/unit'`` +:Possible Values: Any valid directory or sub-directory. +: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 -:Description: tbd +:Possible Values: Any valid artifact name. +: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 -:Description: tbd +:Possible Values: Any valid artifact name. +: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. diff --git a/doc/JobTemplate/Setup/ExtractConfiguration.rst b/doc/JobTemplate/Setup/ExtractConfiguration.rst index edc4b48..874cb03 100644 --- a/doc/JobTemplate/Setup/ExtractConfiguration.rst +++ b/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). diff --git a/doc/JobTemplate/Setup/Parameters.rst b/doc/JobTemplate/Setup/Parameters.rst index 8f51751..2a318d6 100644 --- a/doc/JobTemplate/Setup/Parameters.rst +++ b/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. diff --git a/doc/JobTemplate/Setup/PrepareJob.rst b/doc/JobTemplate/Setup/PrepareJob.rst index 97adba3..06f0739 100644 --- a/doc/JobTemplate/Setup/PrepareJob.rst +++ b/doc/JobTemplate/Setup/PrepareJob.rst @@ -449,3 +449,11 @@ pr_number :ref:`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). diff --git a/doc/conf.py b/doc/conf.py index 1b683e0..eb5cd72 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -214,12 +214,13 @@ autodoc_typehints = "both" # Sphinx.Ext.ExtLinks # ============================================================================== extlinks = { - "gh": (f"https://GitHub.com/%s", "GitHub: %s"), - "ghissue": (f"https://GitHub.com/{githubNamespace}/{githubProject}/issues/%s", "issue #%s"), - "ghpull": (f"https://GitHub.com/{githubNamespace}/{githubProject}/pull/%s", "pull request #%s"), - "ghsrc": (f"https://GitHub.com/{githubNamespace}/{githubProject}/blob/main/%s", None), - "wiki": (f"https://en.wikipedia.org/wiki/%s", None), - "pypi": (f"https://pypi.org/project/%s/", "PyPI: %s"), + "gh": (f"https://GitHub.com/%s", "GitHub: %s"), + "ghissue": (f"https://GitHub.com/{githubNamespace}/{githubProject}/issues/%s", "issue #%s"), + "ghpull": (f"https://GitHub.com/{githubNamespace}/{githubProject}/pull/%s", "pull request #%s"), + "ghsrc": (f"https://GitHub.com/{githubNamespace}/{githubProject}/blob/main/%s", None), + "wiki": (f"https://en.wikipedia.org/wiki/%s", None), + "pypi": (f"https://pypi.org/project/%s/", "PyPI: %s"), + "dockerhub": (f"https://hub.docker.com/r/%s", "Docker Hub: %s"), }