Tar build output before upload to avoid NTFS filename restrictions

DocC archives contain colons in filenames (e.g. when(configuration:).json)
which upload-artifact rejects. Package as a tarball instead.

Also add explanatory comment on the git clean step.

Author: heckj

.github/workflows/build_documentation.yml

@@ -32,10 +32,10 @@ jobs:
       - name: Build documentation
         run: python3 scripts/build_docs.py --output-dir "$GITHUB_WORKSPACE/build-output"
 
-      - name: List build output
-        run: ls -la "$GITHUB_WORKSPACE/build-output"
+      - name: Package build output
+        run: tar -czf "$GITHUB_WORKSPACE/combined-documentation.tar.gz" -C "$GITHUB_WORKSPACE/build-output" .
 
       - uses: actions/upload-artifact@v4
         with:
           name: combined-documentation
-          path: build-output/
+          path: combined-documentation.tar.gz

scripts/build_docs.py

@@ -195,6 +195,9 @@ def clone_or_update(source, workspace, ref):
             ],
             check=True,
         )
+        # Remove untracked files left by previous builds (e.g. swift-book's
+        # generated SummaryOfTheGrammar.md) so preflight scripts don't fail
+        # when they detect stale output from a cached workspace.
         subprocess.run(
             ["git", "-C", str(source_dir), "clean", "--quiet", "-fdx"],
             check=True,