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.

Features

• Build documentation using Sphinx as HTML and upload as artifact.
  (see html_artifact).

• Build documentation using Sphinx as LaTeX and upload as artifact.
  (see latex_artifact).

  • Workaround sphinx-doc/sphinx#13189

  • Workaround sphinx-doc/sphinx#13190

• Optionally: download code coverage artifact (JSON format) given by coverage_json_artifact.

• Optionally: download unit test report artifact (XML format) given by unittest_xml_artifact.

Behavior

1. Checkout repository.

2. Install system dependencies.

3. Setup Python environment and install Python dependencies.

4. Download optional artifacts for integration of further reports into the documentation.

5. Build the HTML documentation using Sphinx.

6. Build the LaTeX documentation using Sphinx.

   1. Apply LaTeX workaround I.

   2. Apply LaTeX workaround II.

7. Upload the HTML and LaTeX artifacts.

Job Execution

Dependencies

• GitHub: actions/checkout

• GitHub: actions/setup-python

• GitHub: pyTooling/download-artifact

  • GitHub: actions/download-artifact

• GitHub: pyTooling/upload-artifact

  • GitHub: actions/upload-artifact

• apt

  • graphviz

• pip

  • PyPI: wheel

  • Python packages specified via requirements parameter.

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.13'
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.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 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.