SphinxDocumentation

The SphinxDocumentation job template compiles the ReStructured Text documentation using Sphinx to an HTML website and a LaTeX documentation. This LaTeX document can be translated using e.g. MikTeX to a PDF file.

Instantiation

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

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

requirements

no

string

'-r doc/requirements.txt'

doc_directory

no

string

'doc'

coverage_json_artifact

no

string

''

coverage_report_json

no

string (JSON)

{"directory": "report/coverage"}

unittest_xml_artifact

no

string

''

unittest_xml

no

string (JSON)

{"directory": "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 the 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.14'

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 to run Python code in the job.

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

coverage_report_json

Type:

string (JSON)

Required:

no

Default Value:
{ "directory": "reports/coverage",
}
Possible Values:

Any valid JSON string containing a JSON object with fields:

directory:

Directory or sub-directory where the code coverage JSON report will be extracted from artifact.

Description:

Directory as JSON object where the code coverage JSON report will be extracted.
This path is configured in pyproject.toml and can be extracted by ExtractConfiguration.

Example:
ConfigParams:
  uses: pyTooling/Actions/.github/workflows/ExtractConfiguration.yml@r6

Documentation:
  uses: pyTooling/Actions/.github/workflows/SphinxDocumentation.yml@r6
  needs:
    - ConfigParams
  with:
    ...
    coverage_report_json: ${{ needs.ConfigParams.outputs.coverage_report_json }}

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

Type:

string (JSON)

Required:

no

Default Value:
{ "directory": "reports/unit",
}
Possible Values:

Any valid JSON string containing a JSON object with fields:

directory:

Directory or sub-directory where the unittest JUnit XML report will be extracted from artifact.

Description:

Directory as JSON object where the unittest JUnit XML report will be extracted.
This path is configured in pyproject.toml and can be extracted by ExtractConfiguration.

Example:
ConfigParams:
  uses: pyTooling/Actions/.github/workflows/ExtractConfiguration.yml@r6

Documentation:
  uses: pyTooling/Actions/.github/workflows/SphinxDocumentation.yml@r6
  needs:
    - ConfigParams
  with:
    ...
    unittest_xml: ${{ needs.ConfigParams.outputs.unittest_xml }}

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.