diff --git a/Makefile b/Makefile index e3ec6bc3..8f137f6e 100644 --- a/Makefile +++ b/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" diff --git a/sphinx-docs/source/conf.py b/sphinx-docs/source/conf.py index e08229b9..7d2353bf 100644 --- a/sphinx-docs/source/conf.py +++ b/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)