VerifyDocs

Attention

Development of this job template is on hold. It is implemented, but it is instantiated nowhere - the job is commented out in CompletePipeline as well as in the repository’s own verification pipelines. Extracting a runnable example from documentation in a general way is not solved yet: the current implementation takes the first fenced code block of README.md and nothing else.

The VerifyDocs job template checks that the first Python code example in README.md still runs against the current code. A broken example is a documentation defect the test suite cannot catch, because the example lives in Markdown and is never imported by the tests.

Features

• Install the package from the checked out sources, so the example runs against the branch and not against a released version.

• Extract the first py or python fenced code block from README.md.

• Execute the extracted snippet and fail the job if it raises.

Behavior

1. Checkout repository.

2. Setup Python (python_version).

3. Install the package from the checked out sources using pip3 install ..

4. Extract the first Python code block from README.md and write it to tests/docs/example.py.

5. Print the extracted snippet into the job log, so a failure can be understood without reproducing it locally.

6. Run the snippet with tests/docs as working directory.

Attention

The job requires an existing tests/docs directory, and it fails if README.md contains no Python code block at all.

Dependencies

• GitHub: actions/checkout

• GitHub: actions/setup-python

Instantiation

The following instantiation example creates a VerifyDocs job derived from job template VerifyDocs version @r8.

jobs:
  VerifyDocs:
    uses: pyTooling/Actions/.github/workflows/VerifyDocs.yml@r8
    with:
      python_version: '3.14'

See also

CheckDocumentation

Checks how much of the API carries doc-strings, while VerifyDocs checks that the documented example works.

Parameter Summary

Goto input parameters

Parameter Name	Required	Type	Default
ubuntu_image_version	no	string	'26.04'
python_version	no	string	'3.14'

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.

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.

Secrets

This job template needs no secrets.

Outputs

This job template has no output parameters.