SphinxDocumentation

The SphinxDocumentation job template ……….

Instantiation

The following instantiation example creates a Params job derived from job template Parameters version @r5. It only requires a name parameter to create the artifact names.

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

Parameter Summary

Goto input parameters

Parameter Name	Required	Type	Default
ubuntu_image_version	no	string	`'24.04'`
python_version	no	string	`'3.13'`
requirements	no	string	`'-r doc/requirements.txt'`
doc_directory	no	string	`'doc'`
coverage_report_json_directory	no	string	`''`
coverage_json_artifact	no	string	`''`
unittest_xml_artifact	no	string	`''`
unittest_xml_directory	no	string	`'report/unit'`
html_artifact	no	string	`''`
latex_artifact	no	string	`''`

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:: '24.04'
Possible Values:: See actions/runner-images - 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, thus, the usual Ubuntu image name like 'ubuntu-24.04' can’t be split into image name and image version.

python_version

Type:: string
Required:: no
Default Value:: '3.13'
Possible Values:: Any valid Python version conforming to the pattern <major>.<minor> or pypy-<major>.<minor>.
See actions/python-versions - available Python versions and actions/setup-python - configurable Python versions.
Description:: Python version used as default for other jobs requiring a single Python version.
In case python_version_list is an empty string, this version is used to populate the version list.

requirements

Type:: string
Required:: no
Default Value:: '-r doc/requirements.txt'
Possible Values:: Any valid list of parameters for pip install.
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.

doc_directory

Type:: string
Required:: no
Default Value:: 'doc'
Possible Values:: Any valid directory or sub-directory.
Description:: Directory where the Sphinx documentation is located.

Attention

When this parameter gets changed, requirements needs to be adjusted as well.

coverage_report_json_directory

Type:: string
Required:: no
Default Value:: ''
Possible Values:: Any valid directory or sub-directory.
Description:: tbd

coverage_json_artifact

Type:: string
Required:: no
Default Value:: ''
Possible Values:: Any valid artifact name.
Description:: Name of the artifact containing the code coverage report in JSON format.

unittest_xml_artifact

Type:: string
Required:: no
Default Value:: ''
Possible Values:: Any valid artifact name.
Description:: Name of the artifact containing the unittest XML report summary in XML format.

unittest_xml_directory

Type:: string
Required:: no
Default Value:: 'report/unit'
Possible Values:: Any valid directory or sub-directory.
Description:: Directory where unittest XML artifact will be extracted.

html_artifact

Type:: string
Required:: no
Default Value:: ''
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.

latex_artifact

Type:: string
Required:: no
Default Value:: ''
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.

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 HTML website generation and HTML artifact: If parameter html_artifact is empty, no HTML website will be generated and uploaded.
Disable LaTeX document generation and laTeX artifact: If parameter latex_artifact is empty, no LaTeX document will be generated and uploaded.