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

Improved SphinxDocumentation and LaTeXDocumentation.

Browse Source
This commit is contained in:
Patrick Lehmann
2025-08-31 01:46:15 +02:00
parent 0adc72d26a
commit bb03bdcc11
9 changed files with 156 additions and 46 deletions
Download Patch File Download Diff File Expand all files Collapse all files

25
.github/workflows/LaTeXDocumentation.yml vendored
View File

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

2
.github/workflows/SphinxDocumentation.yml vendored
View File

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

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

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

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

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

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

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

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

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

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

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

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

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

13
doc/conf.py
View File

@@ -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"),
}