[API-535] test Docs py code blocks for correct API signatures

.github/workflows/test_docs_sanity.yml

@@ -0,0 +1,35 @@
+name: Documentation sanity check
+
+on:
+  push:
+    branches:
+      - 'main'
+  pull_request:
+    branches:
+      - 'main'
+
+jobs:
+  run-docs-tests:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Install build dependencies (pyproject.toml)
+        run: |
+          python -m pip install --upgrade pip
+          pip install setuptools
+
+      - name: Install project and runtime dependencies
+        run: |
+          if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
+          pip install pytest
+
+      - name: Run pytest
+        run: pytest tests/test_docs.py --maxfail=1 --disable-warnings

Dockerfile

@@ -14,5 +14,5 @@ EXPOSE 8080
 
 CMD ["mkdocs", "serve", "--dev-addr=0.0.0.0:8080"]
 
-# docker build -t cwapi3d-py .   
+# docker build -t cwapi3d-py .
 # docker run --rm -p 8080:8080 cwapi3d-py

tests/__internal/__init__.py

@@ -0,0 +1 @@
+from .cw_python_analyser import CwPythonAnalyser

tests/test_docs.py

@@ -0,0 +1,34 @@
+import pytest
+import pathlib
+from __internal.cw_python_analyser import CwPythonAnalyser
+
+EXAMPLES_DIR = pathlib.Path(__file__).parent.parent / "docs" / "examples"
+STUBS_ROOT = pathlib.Path(__file__).parent.parent / "src"
+
+def get_all_md_files():
+    return list(EXAMPLES_DIR.glob("*.md"))
+
+@pytest.mark.parametrize("md_file", get_all_md_files(), ids=lambda f: f.name)
+def test_pyAPI_signatures_blocks(md_file):
+    content = md_file.read_text(encoding="utf-8")
+    raw_blocks = CwPythonAnalyser.extract_markdown_py_code_blocks(content)
+    py_code_blocks = [block["code"] for block in raw_blocks if block["language"] == "python"]
+
+    for py_block in py_code_blocks:
+        extracted_symbols = CwPythonAnalyser.extract_py_dotted_symbols_from_code(py_block)
+        matched_signatures, uncertain_signatures = CwPythonAnalyser.match_symbols_to_api_signatures(
+            api_calls=extracted_symbols,
+            stubs_root=STUBS_ROOT
+        )
+        # Only fail if possible signatures are present for any uncertain signature
+        filtered = [
+            (symbol, possible)
+            for symbol, possible in uncertain_signatures
+            if possible  # Only include if possible signatures are found
+        ]
+        if filtered:
+            formatted = "\n".join(
+                f"Symbol: {symbol}\nPossible signatures: {', '.join(possible)}"
+                for symbol, possible in filtered
+            )
+            pytest.fail(f"In file {md_file.name}:\nUncertain signatures found:\n{formatted}")