Documentation rework: cross-check every job template against its workflow

[Paebbels]

New Features

• Three job templates are documented for the first time.

  • ApplicationTesting was a .. todo:: stub titled "ApplicationTesting (idea)", although the template is implemented and used by the SimplePackage verification pipeline and by CompletePipeline via apptest: 'true'.
  • CheckCodeQuality had no page at all.
  • CleanupArtifacts had no page at all — doc/JobTemplate/Cleanup/ArtifactCleanup.rst documents the deprecated ArtifactCleanUp.yml, which is why CompletePipeline linked to the deprecated template for the job it actually instantiates.

• VerifyDocs was a .. todo:: stub too and now describes what the template does and both of its parameters.

• CleanupArtifacts' artifact-json-ids syntax is written down — it had never been documented, although it is the only way to use the template. Entries are keys into the artifact-name dictionary, optionally with a prefix and/or a postfix, and # comments an entry out. The postfix form is what deletes the per-matrix-job artifacts (codecoverage_xml:-*) as opposed to the merged one.

Changes

• No workflow file was touched. This pull-request changes documentation only.

• Every workflow_call input, output and secret of every job template now has a detail section and a summary-table row. Previously undocumented parameters:

  Template	Parameters
  CompletePipeline	apptest, bandit, pylint, documentation_steps, miktex_image, miktex_update, auto_tag
  LaTeXDocumentation	miktex_image, update, halt-on-error, can-fail
  Parameters	pipeline-delay, version_file, documentation_steps, output package_version_file
  PrepareJob	pipeline-delay, outputs default_branch, on_default_branch, has_submodules, git_submodule_count, git_submodule_names, git_submodule_paths
  PublishOnPyPI	cleanup
  PublishReleaseNotes	tarball-name, can-fail, output release-page
  PublishTestResults	testsuite-summary-name, merge-input-dialect, merge-output-dialect
  PublishToGitHubPages	pages, cleanup, output github_pages_url
  UnitTesting	windows_before_script, windows_arm_before_script
  VerifyDocs	python_version, ubuntu_image_version

• The PrepareJob output table had an empty Description column for all 20 outputs. Filled in.

• Thirteen tbd placeholders on PublishTestResults, PublishCoverageResults, PublishToGitHubPages and PublishReleaseNotes were replaced with actual descriptions.

Bug Fixes

• Wrong defaults. Cross-checked every documented default against the YAML, in the summary table and the detail section:

  Parameter	documented	actual
  ubuntu_image_version (15 pages)	'24.04'	'26.04'
  ubuntu_image / ubuntu_arm_image	'ubuntu-24.04'	'ubuntu-26.04'
  macos_intel_image	'macos-13'	'macos-15-intel'
  system_list, unittest_system_list, apptest_system_list	no ubuntu-arm, no windows-arm	both present
  UnitTesting.requirements	'-r tests/requirements.txt'	'-r ./requirements.txt'
  UnitTesting.root_directory	''	'.'
  UnitTesting.coverage_report_html	report/coverage	report/coverage/html
  StaticTypeCheck.requirements	'-r tests/requirements.txt'	'-r tests/typing/requirements.txt'
  PublishOnPyPI.requirements	''	'wheel twine'
  PublishTestResults.unittest_artifacts_pattern	'*-UnitTestReportSummary-XML-*'	'*-*TestReportSummary-XML-*'
  PublishCoverageResults.coverage_html_artifact	'report/coverage/html'	''
  PublishReleaseNotes.latest	false	true

  Report paths were written as reports/... in 33 places, while every default and this repository's own pyproject.toml use report/....

  PublishReleaseNotes.inventory-categories was documented as a colon separated list; the workflow splits it on a comma (readarray -td,).

• SystemList.rst — the table backing the system_list parameter — did not list ubuntu-arm or windows-arm at all and named macOS Ventura 13. Regenerated from the system table in Parameters.yml.

• Described algorithms that did not match the workflow. Each Behavior topic was checked step by step against the YAML:

  • CheckDocumentation runs interrogate first, then docstr_coverage — documented the other way round.
  • Parameters generates the artifact names before the job matrix — documented the other way round.
  • PublishOnPyPI publishes the wheel before the source distribution — documented the other way round.
  • PublishReleaseNotes creates the release page before attaching assets and assembling notes — documented with the notes assembled first. That ordering matters: a failure while uploading assets leaves a draft page behind rather than a published, incomplete release.
  • PublishToGitHubPages was documented as "Checkout repository / Download artifacts / Push HTML files to branch gh-pages". The job does none of those three — it merges up to three artifacts, uploads a Pages artifact and deploys it via actions/deploy-pages, and skips deployment for pull_request events.
  • SphinxDocumentation is two independent jobs running in parallel, not sequential steps of one job.
  • Missing steps: the combine step in PublishCoverageResults (a 14-step list without the step the job exists for), the merged-report upload in PublishTestResults, the MiKTeX update in LaTeXDocumentation, the startup delay and context dump in PrepareJob.
  • CompletePipeline's shared _Behavior.rst listed platform tests, which this template does not run; packaged after application testing although the wheel is application testing's input; and published to PyPI before creating the release page although PyPI publishing depends on it. Version check, installation test, code quality, intermediate cleanup, tagging and final cleanup were missing entirely.

• Dependency lists that named the wrong actions. Regenerated from the uses: statements:

  • The templates migrated to pyTooling/upload-artifact and pyTooling/download-artifact, but the pages still listed the actions/* originals as direct dependencies. They are now shown as what they are — the actions the pyTooling wrappers build on.
  • PublishToGitHubPages listed actions/checkout and actions/download-artifact and was missing actions/upload-pages-artifact, actions/deploy-pages and geekyeggo/delete-artifact — the three that do the work. The job performs no checkout.
  • PublishTestResults uses codecov/codecov-action, not codecov/test-results-action.
  • LaTeXDocumentation runs inside the MiKTeX container via jobs.<id>.container; it does not use addnab/docker-run-action.
  • Parameters was missing actions/checkout, TagReleaseCommit its actions/github-script, PublishOnPyPI its geekyeggo/delete-artifact.
  • doc/Dependency.rst listed actions/create-release and buildthedocs/btd, which no template uses, and was missing actions/github-script, actions/deploy-pages, actions/upload-pages-artifact, both pyTooling artifact actions, the gh CLI and the MiKTeX image.

• Stale overview and landing page.

  • Templates.rst did not list CheckCodeQuality, CleanupArtifacts or VerifyDocs, presented the deprecated ArtifactCleanup as the current cleanup template, and still showed code linting (planned) although CheckCodeQuality implements it.
  • Instantiation.rst's Documentation Only example instantiated BuildTheDocs.yml, a template that no longer exists.
  • The landing page described an ExamplePipeline.yml that is not in this repository and told readers to set a name input on Parameters and a commands input on StaticTypeCheck — neither input exists.
  • doc/License.rst had no CODELICENSE label although the landing page links to it.

• 151 instantiation examples across 22 pages still referenced @r6, while the current release branch is @r7.

Documentation

Two defects found while cross-checking are fixed in #246, not here. This branch originally documented them as observed behaviour with .. attention:: notes; the last commit replaces those notes with the corrected behaviour, so the two pull-requests agree whichever order they land in:

• PrepareJob's has_submodules — the workflow tested for a file named .gitsubmodules (PrepareJob.yml:369), while Git's file is .gitmodules, so the output was always 'false'.
• CheckCodeQuality's artifact — the Bandit step was guarded by inputs.artifact != '', so an empty artifact name silently skipped the security scan while the job still reported success. The parameter keeps a .. note:: saying the template does not reference it, which remains true after Fix submodule detection, the CleanupArtifacts NameError and the skippable Bandit scan #246.

A third defect, the NameError in CleanupArtifacts' unknown-key branch, is also fixed in #246 and was never documented here.

Corrected in this branch after the fact: git_submodule_names and git_submodule_paths are colon separated (paste -sd ':'), not space separated as first written.

Unit Tests

There is no test suite for documentation, so the checks were scripted and run against the tree:

• Parameter coverage — every workflow_call input, output and secret of every job template is matched against the labels and summary-table rows on its page. Remaining reports are formatting conventions only (— — — — for "no default", :jsoncode: for inline JSON, the string (JSON) type annotation).
• Behavior order — the YAML step order of all 23 templates was dumped next to the documented list and compared step by step.
• Dependencies — the uses: statements of each workflow are compared against the :gh: entries of its Dependencies topic, and the union against doc/Dependency.rst.
• ReST validity — every page is parsed with docutils: 0 errors, once Sphinx-only roles and directives are filtered out. Grid tables are re-rendered with docutils' column_width, so the emoji cells in SystemList.rst keep their alignment.
• Cross-references — 0 dangling :ref: targets and 0 duplicate labels across the whole documentation. Both were non-zero before this pull-request.
• No tbd or "Needs documentation" placeholders remain on any job template page.

---

Related Issues and Pull-Requests

• Addresses finding A4 from the pyTooling/Actions backlog ("The documentation needs a rework — measured drift").
• Depends on nothing; it can be merged independently of v7.14.2 #244 (v7.14.2). Pairs with Fix submodule detection, the CleanupArtifacts NameError and the skippable Bandit scan #246, which fixes the three defects this cross-check found.

Note

ArtifactCleanUp.yml (deprecated) is documented on a page whose label is JOBTMPL/ArtifactCleanup — lower-case u. The inconsistency between the workflow file name and the label is left as is, since the template is deprecated and renaming the label would break external links.

[codacy-production]

Up to standards ✅

🟢 Issues 0 issues

Results:
0 new issues

View in Codacy

🟢 Coverage ∅ diff coverage · +0.00% coverage variation

Metric	Results
Coverage variation	✅ +0.00% coverage variation
Diff coverage	✅ ∅ diff coverage

View coverage diff in Codacy

Coverage variation details

	Coverable lines	Covered lines	Coverage
Common ancestor commit (08dd2c2)	45	41	91.11%
Head commit (15d504e)	45 (+0)	41 (+0)	91.11% (+0.00%)

Coverage variation is the difference between the coverage for the head and common ancestor commits of the pull request branch: <coverage of head commit> - <coverage of common ancestor commit>

Diff coverage details

	Coverable lines	Covered lines	Diff coverage
Pull request (#245)	0	0	∅ (not applicable)

Diff coverage is the percentage of lines that are covered by tests out of the coverable lines that the pull request added or modified: <covered lines added or modified>/<coverable lines added or modified> * 100%

_{NEW Get contextual insights on your PRs based on Codacy's metrics, along with PR and Jira context, without leaving GitHub. Enable AI reviewer
TIP This summary will be updated as you push new changes.}

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 82.22%. Comparing base (08dd2c2) to head (15d504e).
✅ All tests successful. No failed tests found.

Additional details and impacted files

@@           Coverage Diff           @@
##              dev     #245   +/-   ##
=======================================
  Coverage   82.22%   82.22%           
=======================================
  Files           1        1           
  Lines          45       45           
  Branches        9        9           
=======================================
  Hits           37       37           
  Misses          4        4           
  Partials        4        4           

Flag	Coverage Δ
unittests	82.22% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.