tests: fix and enable doctests (#2546)

* fix doctest

* Update cibuildwheel/oci_container.py

Co-authored-by: Joe Rickerby <joerick@mac.com>

* Update cibuildwheel/oci_container.py

Co-authored-by: Joe Rickerby <joerick@mac.com>

* Update cibuildwheel/oci_container.py

Co-authored-by: Joe Rickerby <joerick@mac.com>

* Add xdoctest to CI

* Add doctests to run tests

* Replace test map with new native method

* Forgot key for arm64

* Allow doctests to be filtered on circleci

---------

Co-authored-by: Joe Rickerby <joerick@mac.com>

cibuildwheel/oci_container.py

@@ -36,6 +36,28 @@ class OCIPlatform(Enum):
     RISCV64 = "linux/riscv64"
     S390X = "linux/s390x"
 
+    @classmethod
+    def native(cls) -> "OCIPlatform":
+        """Return the current OCI platform, or raise ValueError if unknown."""
+        arch = platform.machine().lower()
+        mapping = {
+            "i386": cls.i386,
+            "i686": cls.i386,
+            "x86_64": cls.AMD64,
+            "amd64": cls.AMD64,
+            "armv7l": cls.ARMV7,
+            "aarch64": cls.ARM64,
+            "arm64": cls.ARM64,
+            "ppc64le": cls.PPC64LE,
+            "riscv64": cls.RISCV64,
+            "s390x": cls.S390X,
+        }
+        try:
+            return mapping[arch]
+        except KeyError as ex:
+            msg = f"Unsupported platform architecture: {arch}"
+            raise OSError(msg) from ex
+
 
 @dataclasses.dataclass(frozen=True)
 class OCIContainerEngineConfig:
@@ -152,11 +174,19 @@ class OCIContainer:
     back to cibuildwheel.
 
     Example:
+        >>> # xdoctest: +REQUIRES(LINUX)
         >>> from cibuildwheel.oci_container import *  # NOQA
         >>> from cibuildwheel.options import _get_pinned_container_images
+        >>> import pytest
+        >>> try:
+        ...     oci_platform = OCIPlatform.native()
+        ... except OSError as ex:
+        ...     pytest.skip(str(ex))
+        >>> if oci_platform != OCIPlatform.AMD64:
+        ...     pytest.skip('only runs on amd64')
         >>> image = _get_pinned_container_images()['x86_64']['manylinux2014']
         >>> # Test the default container
-        >>> with OCIContainer(image=image) as self:
+        >>> with OCIContainer(image=image, oci_platform=oci_platform) as self:
         ...     self.call(["echo", "hello world"])
         ...     self.call(["cat", "/proc/1/cgroup"])
         ...     print(self.get_environment())

cibuildwheel/options.py

@@ -391,6 +391,7 @@ class OptionsReader:
     by the platform.
 
     Example:
+      >>> # xdoctest: +SKIP
       >>> options_reader = OptionsReader(config_file, platform='macos')
       >>> options_reader.get('cool-color')
 

cibuildwheel/util/helpers.py

@@ -20,8 +20,8 @@ def format_safe(template: str, **kwargs: str | os.PathLike[str]) -> str:
     >>> format_safe('{a} {b[4]:3f}', a='123')
     '123 {b[4]:3f}'
 
-    To avoid variable expansion, precede with a single backslash e.g.
-    >>> format_safe('\\{a} {b}', a='123')
+    To avoid variable expansion, precede with a single hash e.g.
+    >>> format_safe('#{a} {b}', a='123')
     '{a} {b}'
     """