LaTeXDocumentation

The LaTeXDocumentation job template downloads an artifact containing a LaTeX document and translates to a PDF file using MikTeX.

The translation process uses latexmk for handling multiple passes. The default LaTeX processor is lualatex, but can be switched by a parameter.

Instantiation

jobs:
  UnitTestingParams:
    uses: pyTooling/Actions/.github/workflows/Parameters.yml@r8
    with:
      package_name: myPackage

  Documentation:
    uses: pyTooling/Actions/.github/workflows/SphinxDocumentation.yml@r8
    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@r8
    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 }}

Parameter Summary

Goto input parameters

Parameter Name

Required

Type

Default

ubuntu_image_version

no

string

'26.04'

latex_artifact

yes

string

— — — —

document

yes

string

— — — —

processor

no

string

'lualatex'

pdf_artifact

no

string

''

miktex_image

no

string

'pytooling/miktex:sphinx'

update

no

string

'false'

halt-on-error

no

string

'true'

can-fail

no

string

'false'

Goto secrets

This job template needs no secrets.

Goto output parameters

This job template has no output parameters.

Input Parameters

ubuntu_image_version

Type:

string

Required:

no

Default Value:

'26.04'

Possible Values:

See actions/runner-images - Available Images for available Ubuntu image versions.

Description:

Version of the Ubuntu image used to run the job.

Note

Unfortunately, GitHub Actions has only a limited set of functions, thus, the usual Ubuntu image name like 'ubuntu-26.04' can’t be split into image name and image version.

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.

document

Type:

string

Required:

yes

Default Value:

— — — —

Possible Values:

Any valid document name.

Description:

Name of the LaTeX document

processor

Type:

string

Required:

no

Default Value:

'lualatex'

Possible Values:

Any supported LaTeX processor supported by MikTeX and latexmk.

Description:

Name of the used LaTeX processor.

pdf_artifact

Type:

string

Required:

no

Default Value:

''

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.

miktex_image

Type:

string

Required:

no

Default Value:

'pytooling/miktex:sphinx'

Possible Values:

Any Docker image providing a MikTeX installation with latexmk, e.g. an image of pyTooling/MiKTeX.

Description:

Docker image used to translate the LaTeX sources to PDF.

Hint

The job template accepts any LaTeX artifact, whatever produced it. When the LaTeX code was emitted by Sphinx, an image with the Sphinx specific LaTeX packages preinstalled is recommended - the default image pytooling/miktex:sphinx is such an image.

update

Type:

string

Required:

no

Default Value:

'false'

Possible Values:

'true' / 'false'

Description:

Update MikTeX packages before the document is built.
Updating costs runtime on every run, so this is meant as an escape hatch when the image lags behind a LaTeX package needs.
'true' - update the packages inside the container before building.
'false' - use the packages shipped with the image.

halt-on-error

Type:

string

Required:

no

Default Value:

'true'

Possible Values:

'true' / 'false'

Description:

Pass -halt-on-error to latexmk.
'true' - stop at the first LaTeX error.
'false' - continue as far as possible; a PDF may still be produced from a document with unresolved references.

can-fail

Type:

string

Required:

no

Default Value:

'false'

Possible Values:

'true' / 'false'

Description:

Set continue-on-error on the job.
PDF generation is the most fragile documentation step, so a pipeline that only needs HTML can tolerate its failure.
'true' - a failed translation does not fail the pipeline.
'false' - a failed translation fails the job.

Secrets

This job template needs no secrets.

Outputs

This job template has no output parameters.

Optimizations

The following optimizations can be used to reduce the template’s runtime.

Disable PDF generation and PDF artifact

If parameter pdf_artifact is empty, no PDF will be generated and uploaded.