tests: add test of examples in docs

Signed-off-by: Henry Schreiner <henryschreineriii@gmail.com>

unit_test/validate_schema_test.py

@@ -1,3 +1,6 @@
+from __future__ import annotations
+
+import re
 from pathlib import Path
 
 import pytest
@@ -54,3 +57,46 @@ def test_overrides_no_select():
     validator = validate_pyproject.api.Validator()
     with pytest.raises(validate_pyproject.error_reporting.ValidationError):
         validator(example)
+
+
+def test_docs_examples():
+    """
+    Parse out all the configuration examples, build valid TOML out of them, and
+    make sure they pass.
+    """
+
+    expr = re.compile(
+        r"""
+!!! tab examples "pyproject.toml"
+\s*
+\s*```toml
+([^`]*)
+\s*```""",
+        re.MULTILINE,
+    )
+
+    txt = DIR.parent.joinpath("docs/options.md").read_text()
+
+    blocks: list[str] = []
+    for match in expr.finditer(txt):
+        lines = (line.strip() for line in match.group(1).strip().splitlines() if line.strip())
+        block: list[str] = []
+        header = ""
+        for line in lines:
+            if line.startswith(("[tool.cibuildwheel", "[[tool.cibuildwheel")):
+                header = line
+            elif line.startswith("#"):
+                if block:
+                    blocks.append("\n".join([header, *block]))
+                    block = []
+            elif " = " in line and any(x.startswith(line.partition(" = ")[0]) for x in block):
+                blocks.append("\n".join([header, *block]))
+                block = [line]
+            else:
+                block.append(line)
+        blocks.append("\n".join([header, *block]))
+
+    for example_txt in blocks:
+        example = tomllib.loads(example_txt)
+        validator = validate_pyproject.api.Validator()
+        assert validator(example) is not None