.github/workflows/docker.yml: Add documentation

Author: Matthias Koeppe

.github/workflows/docker.yml

@@ -229,6 +229,15 @@ jobs:
           df -h
         if: inputs.free_disk_space
       - name: Configure and build Sage distribution within a Docker container
+        # The first command below is a self-destruct sequence,
+        # which preempts the GitHub Actions 6-hour job cancellation.
+        #
+        # Using "docker exec", we enter the temporary containers used by
+        # "docker build" and kill the "make" processes of the Sage distribution.
+        #
+        # The arcane "find" command is a replacement for "pkill make",
+        # which we use because pkill is not installed in the "minimal" package
+        # configuration on many platforms.
         run: |
           (sleep ${{ inputs.timeout }}; for id in $(docker ps -q); do docker exec $id find /proc -maxdepth 2 -name cmdline -exec bash -c "grep -l [m][a][k][e] {} | cut -d/ -f3 | xargs --no-run-if-empty kill" \;; done) &
           set -o pipefail; EXTRA_DOCKER_BUILD_ARGS="--build-arg NUMPROC=4 --build-arg USE_MAKEFLAGS=\"-k V=0 SAGE_NUM_THREADS=3\"" tox -e $TOX_ENV -- $TARGETS 2>&1 | sed "/^configure: notice:/s|^|::warning file=artifacts/$LOGS_ARTIFACT_NAME/config.log::|;/^configure: warning:/s|^|::warning file=artifacts/$LOGS_ARTIFACT_NAME/config.log::|;/^configure: error:/s|^|::error file=artifacts/$LOGS_ARTIFACT_NAME/config.log::|;"