Archive examples during Sphinx build.

Makefile

@@ -275,6 +275,19 @@ Sphinx-%: $(VENV) $(DEFAULT_TARGET) Makefile
 	$(ACTIVATE_VENV) && \
 	$(SPHINXBUILD) -M $(patsubst Sphinx-%,%,$@) "sphinx-docs/$(SOURCEDIR)" "sphinx-docs/$(BUILDDIR)" $(SPHINXOPTS)
 
+Sphinx-clean: $(VENV) $(DEFAULT_TARGET) Makefile
+	$(ACTIVATE_VENV) && \
+	$(SPHINXBUILD) -M clean "sphinx-docs/$(SOURCEDIR)" "sphinx-docs/$(BUILDDIR)" $(SPHINXOPTS)
+# remove example zip archives that are created alongside Sphinx
+# that aren't tracked by Sphinx.
+	find examples/ \
+		-mindepth 1 \
+		-maxdepth 2 \
+		-type f \
+		-regex '.*/\([^/]*\)/\1.zip' \
+		-prune \
+		-exec rm {} +
+
 Sphinx-autobuild: $(VENV) $(DEFAULT_TARGET) Makefile
 	$(ACTIVATE_VENV) && \
 	sphinx-autobuild "sphinx-docs/$(SOURCEDIR)" "sphinx-docs/$(BUILDDIR)/html"

sphinx-docs/source/conf.py

@@ -6,8 +6,10 @@
 # -- Project information -----------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
 
+import os
 import sys
-from os import environ
+import zipfile
+from pathlib import Path
 from typing import Any
 from unittest.mock import Mock
 
@@ -60,7 +62,7 @@
 copybutton_prompt_is_regexp = True
 copybutton_only_copy_prompt_lines = True
 
-github_ref = environ.get("GITHUB_REF") or "main"
+github_ref = os.environ.get("GITHUB_REF") or "main"
 
 extlinks = {
     "example": (
@@ -104,6 +106,30 @@ def skip_member(
     return skip
 
 
+def create_zips_for_examples(app: Sphinx, exception: Exception | None):
+    if exception is not None:
+        return
+
+    examples_dir = Path("examples").resolve()
+    example_paths = examples_dir.glob("*")
+
+    for example_path in example_paths:
+        # store the zip file in the example directory with the name
+        # of the example (which is the directory name), e.g. examples/web-api/web-api.zip
+        with zipfile.ZipFile(
+            Path(example_path, f"{example_path.name}.zip"), "w", zipfile.ZIP_DEFLATED
+        ) as zip_file:
+            for root, _, files in os.walk(examples_dir):
+                for file in files:
+                    # don't include the new archive in itself
+                    if Path(file).name == f"{Path(root).name}.zip":
+                        continue
+
+                    file_path = Path(root, file)
+                    arcname = Path.relative_to(file_path, examples_dir)
+                    zip_file.write(file_path, arcname)
+
+
 def setup(app: Sphinx) -> None:
     """
     Connects the `skip_member` function to the `autodoc-skip-member` event.
@@ -117,3 +143,4 @@ def setup(app: Sphinx) -> None:
     # WARNING: Failed guarded type import with ModuleNotFoundError("No module named '_typeshed'")
     sys.modules["_typeshed"] = Mock()
     _ = app.connect("autodoc-skip-member", skip_member)
+    _ = app.connect("build-finished", create_zips_for_examples)