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

.github/workflows/IntermediateCleanUp.yml

@@ -45,6 +45,33 @@ jobs:
     name: 🗑️ Intermediate Artifact Cleanup
     runs-on: "ubuntu-${{ inputs.ubuntu_image_version }}"
     steps:
+      - name: ⚠️ Deprecation warning
+        shell: bash
+        run: |
+          printf "::warning title=Deprecated workflow::%s\n" \
+            "'IntermediateCleanUp.yml' is deprecated and will be removed in r8. Use 'CleanupArtifacts.yml' instead."
+          printf "\n"
+          printf "%s\n" "'IntermediateCleanUp.yml' is deprecated and will be removed in r8."
+          printf "%s\n" "Use 'CleanupArtifacts.yml' instead, which resolves artifact names from the"
+          printf "%s\n" "'artifact_names' JSON dictionary produced by 'Parameters.yml', so the caller"
+          printf "%s\n" "no longer assembles artifact names itself."
+          printf "\n"
+          printf "%s\n" "Migration:"
+          printf "%s\n" "  * Pass the whole 'artifact_names' dictionary of 'Parameters.yml' as 'json',"
+          printf "%s\n" "    instead of assembling a prefix per artifact kind."
+          printf "%s\n" "  * Both prefix parameters become entries of 'artifact-json-ids' using the"
+          printf "%s\n" "    postfix form, which is what matches the per-matrix-job variants:"
+          printf "\n"
+          printf "%s\n" "      artifact-json-ids: >-"
+          printf "%s\n" "        codecoverage_sqlite:-*"
+          printf "%s\n" "        unittesting_xml:-*"
+          printf "\n"
+          printf "%s\n" "  * Give the job an 'if' containing a status check function, e.g. '!cancelled()',"
+          printf "%s\n" "    so a skipped upstream job doesn't skip the cleanup."
+          printf "\n"
+          printf "%s\n" "See 'CompletePipeline.yml' for a worked example - it instantiates"
+          printf "%s\n" "'CleanupArtifacts.yml' for the intermediate as well as the final cleanup."
+
       - name: 🗑️ Delete SQLite coverage artifacts from matrix jobs
         uses: geekyeggo/delete-artifact@v6
         if: inputs.sqlite_coverage_artifacts_prefix != ''

.github/workflows/_Checking_AvailableRunners.yml

@@ -1,4 +1,5 @@
 name: Testing available GitHub Action Images
+run-name: ${{ github.ref_type == 'tag' && github.ref_name || '' }}
 
 on:
   push:

.github/workflows/_Checking_CleanupArtifacts.yml

@@ -1,4 +1,5 @@
 name: Verification Pipeline for ArtifactCleanup
+run-name: ${{ github.ref_type == 'tag' && github.ref_name || '' }}
 
 on:
 #  push:

.github/workflows/_Checking_JobTemplates.yml

@@ -1,4 +1,5 @@
 name: Verification of Job Templates
+run-name: ${{ github.ref_type == 'tag' && github.ref_name || '' }}
 
 on:
   push:

.github/workflows/_Checking_NamespacePackage_Pipeline.yml

@@ -1,4 +1,5 @@
 name: Verification of Pipeline Templates (Namespace Package)
+run-name: ${{ github.ref_type == 'tag' && github.ref_name || '' }}
 
 on:
   push:

.github/workflows/_Checking_Nightly.yml

@@ -1,4 +1,5 @@
 name: Verification of Nightly Releases
+run-name: ${{ github.ref_type == 'tag' && github.ref_name || '' }}
 
 on:
 #  push:

.github/workflows/_Checking_Parameters.yml

@@ -1,4 +1,5 @@
 name: Verification Pipeline for Parameters
+run-name: ${{ github.ref_type == 'tag' && github.ref_name || '' }}
 
 on:
   push:

.github/workflows/_Checking_SimplePackage_Pipeline.yml

@@ -1,4 +1,5 @@
 name: Verification of Pipeline Templates (Simple Package)
+run-name: ${{ github.ref_type == 'tag' && github.ref_name || '' }}
 
 on:
   push:

doc/Dependency.rst

@@ -6,14 +6,15 @@ This is a summary of dependencies used by the provided job templates. For more d
 * Actions provided by GitHub
 
   * :gh:`actions/checkout`
-  * :gh:`actions/upload-artifact`
-  * :gh:`actions/download-artifact`
-  * :gh:`actions/create-release` (unmaintained)
   * :gh:`actions/setup-python`
+  * :gh:`actions/github-script`
+  * :gh:`actions/upload-pages-artifact`
+  * :gh:`actions/deploy-pages`
 
-* BuildTheDocs
+* Actions provided by pyTooling
 
-  * :gh:`buildthedocs/btd`
+  * :term:`upload-artifact` (:gh:`pyTooling/upload-artifact`)
+  * :term:`download-artifact` (:gh:`pyTooling/download-artifact`)
 
 * Code Quality Services
 
@@ -28,3 +29,42 @@ This is a summary of dependencies used by the provided job templates. For more d
 
   * :gh:`msys2/setup-msys2`
   * :gh:`geekyeggo/delete-artifact`
+  * :term:`gh` - preinstalled on GitHub runners.
+  * :term:`pyTooling/MiKTeX` (:dockerhub:`Docker image <pytooling/miktex>`)
+
+* System packages installed through ``apt``
+
+  * `graphviz <https://graphviz.org/>`__
+  * `zstd <https://facebook.github.io/zstd/>`__
+
+* System packages installed through the caller's parameters
+
+  These are **not** installed by the job templates. The templates only pass the package lists on, so the caller
+  decides which system packages a test needs:
+
+  * ``apt`` - Debian/Ubuntu packages.
+  * ``brew`` - Homebrew packages on macOS.
+  * ``pacboy`` - MSYS2 packages, given in ``pacboy`` syntax.
+
+* Python packages installed through :term:`pip`
+
+  * :term:`bandit` (:pypi:`PyPI package <bandit>`)
+  * :term:`build` (:pypi:`PyPI package <build>`)
+  * :term:`Coverage.py` (:pypi:`PyPI package <coverage>`)
+  * :term:`docstr_coverage` (:pypi:`PyPI package <docstr_coverage>`)
+  * :term:`interrogate` (:pypi:`PyPI package <interrogate>`)
+  * :term:`pyEDAA.Reports` (:pypi:`PyPI package <pyEDAA.Reports>`)
+  * :term:`pylint` (:pypi:`PyPI package <pylint>`)
+  * :term:`radon` (:pypi:`PyPI package <radon>`)
+  * :term:`twine` (:pypi:`PyPI package <twine>`)
+  * :term:`wheel` (:pypi:`PyPI package <wheel>`)
+
+* Python packages installed through the caller's requirements file
+
+  These are **not** installed by the job templates. The templates only run the tools, so the caller decides the
+  version:
+
+  * :term:`mypy` (:pypi:`PyPI package <mypy>`)
+  * :term:`pytest` (:pypi:`PyPI package <pytest>`)
+  * :term:`Coverage.py` (:pypi:`PyPI package <coverage>`)
+  * :term:`Sphinx` (:pypi:`PyPI package <Sphinx>`), its theme and its extensions

doc/Deveopment.rst

@@ -93,8 +93,8 @@ Which function to choose:
   dependency suppresses the job. This is the default for optional jobs (:ref:`JOBTMPL/PublishToGitHubPages`,
   :ref:`JOBTMPL/LaTeXDocumentation`) as well as for release jobs, which must not run if any check failed.
 * ``!cancelled()`` - the job runs regardless of the outcome of its dependencies. Use it for jobs collecting or
-  cleaning up results (:ref:`JOBTMPL/PublishTestResults`, ``CleanupArtifacts``), because artifacts of a failed run
-  still need to be published or deleted.
+  cleaning up results (:ref:`JOBTMPL/PublishTestResults`, :ref:`JOBTMPL/CleanupArtifacts`), because artifacts of a
+  failed run still need to be published or deleted.
 * ``always()`` - avoid it. It also runs the job when the workflow was cancelled, which delays the cancellation.
 
 .. hint::

doc/Glossary.rst

@@ -41,6 +41,14 @@ Glossary
      :Marketplace:   `github.com/marketplace/actions/delete-artifact/ <https://github.com/marketplace/actions/delete-artifact/>`__
      :README:        `github.com/GeekyEggo/delete-artifact → README.md <https://github.com/GeekyEggo/delete-artifact/blob/main/README.md>`__
 
+   download-artifact
+     GitHub Action downloading artifacts within a workflow run. :gh:`pyTooling/download-artifact` wraps
+     :gh:`actions/download-artifact` and unpacks the tarball created by :term:`upload-artifact`, so file modes and
+     symbolic links are restored.
+
+     :Source Code:   `github.com/pyTooling/download-artifact/ <https://github.com/pyTooling/download-artifact/>`__
+     :Marketplace:   `github.com/marketplace/actions/pytooling-download-artifact/ <https://github.com/marketplace/actions/pytooling-download-artifact/>`__
+
    docstr_coverage
      Docstring coverage analysis and rating for Python.
 
@@ -73,6 +81,14 @@ Glossary
      :Source Code:   `github.com/MiKTeX/miktex/ <https://github.com/MiKTeX/miktex/>`__
      :Documentation: `miktex.org/ <https://miktex.org/>`__
 
+   pyTooling/MiKTeX
+     Docker images shipping a :term:`MikTeX` installation with ``latexmk`` and a set of preinstalled LaTeX packages,
+     so a LaTeX document can be translated to PDF without downloading packages at build time. The ``sphinx`` tag adds
+     the packages :term:`Sphinx` emits into its LaTeX output.
+
+     :Source Code:   `github.com/pyTooling/MiKTeX/ <https://github.com/pyTooling/MiKTeX/>`__
+     :Docker Image:  :dockerhub:`pytooling/miktex <pytooling/miktex>`
+
    mypy
      Optional static typing for Python.
 
@@ -94,6 +110,15 @@ Glossary
      :Package:       `pypi.org/project/pip/ <https://pypi.org/project/pip/>`__
      :Documentation: `pip.pypa.io/ <https://pip.pypa.io/>`__
 
+   pylint
+     Static code analyzer for Python. It checks a code base without running it and reports errors, violations of
+     coding conventions, code smells and refactoring suggestions. Each finding has a category and an identifier
+     (e.g. ``C0116``), so individual checks can be enabled, disabled or configured per project.
+
+     :Source Code:   `github.com/pylint-dev/pylint/ <https://github.com/pylint-dev/pylint/>`__
+     :Package:       `pypi.org/project/pylint/ <https://pypi.org/project/pylint/>`__
+     :Documentation: `pylint.readthedocs.io/ <https://pylint.readthedocs.io/>`__
+
    PyPI
      Find, install and publish Python packages with the Python Package Index.
 
@@ -106,6 +131,20 @@ Glossary
      :Package:       `pypi.org/project/pytest/ <https://pypi.org/project/pytest/>`__
      :Documentation: `pytest.org/ <https://pytest.org/>`__
 
+   radon
+     Computes code metrics for Python code:
+
+     * **Raw metrics** - lines of code, logical lines, comment lines, blank lines.
+     * **Cyclomatic complexity** - the number of linearly independent paths through a function, graded from *A* to
+       *F*.
+     * **Halstead metrics** - vocabulary, length, volume, difficulty, effort and the estimated number of bugs,
+       derived from the operators and operands in the code.
+     * **Maintainability index** - a single score combining cyclomatic complexity, lines of code and comment ratio.
+
+     :Source Code:   `github.com/rubik/radon/ <https://github.com/rubik/radon/>`__
+     :Package:       `pypi.org/project/radon/ <https://pypi.org/project/radon/>`__
+     :Documentation: `radon.readthedocs.io/ <https://radon.readthedocs.io/>`__
+
    Sphinx
      The Sphinx documentation generator.
 
@@ -120,9 +159,25 @@ Glossary
      :Marketplace:   `github.com/marketplace/actions/test-reporter/ <https://github.com/marketplace/actions/test-reporter/>`__
      :README:        `github.com/dorny/test-reporter → README.md <https://github.com/dorny/test-reporter/blob/main/README.md>`__
 
+   upload-artifact
+     GitHub Action uploading artifacts within a workflow run. :gh:`pyTooling/upload-artifact` wraps
+     :gh:`actions/upload-artifact` and packs the uploaded files into a tarball first, because the original action
+     does not preserve file modes and symbolic links.
+
+     :Source Code:   `github.com/pyTooling/upload-artifact/ <https://github.com/pyTooling/upload-artifact/>`__
+     :Marketplace:   `github.com/marketplace/actions/pytooling-upload-artifact/ <https://github.com/marketplace/actions/pytooling-upload-artifact/>`__
+
    twine
      Utilities for interacting with PyPI.
 
      :Source Code:   `github.com/pypa/twine/ <https://github.com/pypa/twine/>`__
      :Package:       `pypi.org/project/twine/ <https://pypi.org/project/twine/>`__
      :Documentation: `twine.readthedocs.io/ <https://twine.readthedocs.io/>`__
+
+   wheel
+     Reference implementation of the Python wheel packaging standard. It is installed alongside :term:`pip` by most
+     job templates, because a source distribution that has to be built during installation needs it.
+
+     :Source Code:   `github.com/pypa/wheel/ <https://github.com/pypa/wheel/>`__
+     :Package:       `pypi.org/project/wheel/ <https://pypi.org/project/wheel/>`__
+     :Documentation: `wheel.readthedocs.io/ <https://wheel.readthedocs.io/>`__

doc/Instantiation.rst

@@ -42,7 +42,7 @@ to handover input parameters to the template.
 
    jobs:
      <InstanceName>:
-       uses: <GitHubOrganization>/<Repository>/.github/workflows/<Template>.yml@r6
+       uses: <GitHubOrganization>/<Repository>/.github/workflows/<Template>.yml@r7
        with:
          <Param1>: <Value>
 
@@ -65,30 +65,26 @@ Documentation Only (Sphinx)
        - cron: '0 22 * * 5'
 
    jobs:
-     BuildTheDocs:
-       uses: pyTooling/Actions/.github/workflows/BuildTheDocs.yml@r6
+     Documentation:
+       uses: pyTooling/Actions/.github/workflows/SphinxDocumentation.yml@r7
        with:
-         artifact: Documentation
+         html_artifact: Documentation
 
      PublishToGitHubPages:
-       uses: pyTooling/Actions/.github/workflows/PublishToGitHubPages.yml@r6
+       uses: pyTooling/Actions/.github/workflows/PublishToGitHubPages.yml@r7
        needs:
-         - BuildTheDocs
+         - Documentation
        with:
          doc: Documentation
 
      ArtifactCleanUp:
-       name: 🗑️ Artifact Cleanup
+       uses: pyTooling/Actions/.github/workflows/CleanupArtifacts.yml@r7
        needs:
-         - BuildTheDocs
+         - Documentation
          - PublishToGitHubPages
-       runs-on: ubuntu-24.04
-
-       steps:
-         - name: 🗑️ Delete artifacts
-           uses: geekyeggo/delete-artifact@v6
-           with:
-             name: Documentation
+       if: ${{ !cancelled() }}
+       with:
+         others: Documentation
 
 
 Simple Package