updated README, this version is now ready to merge to main

Author: jmacey

README.md

@@ -79,7 +79,7 @@ uv run ruff check src/
 
 ## Documentation
 
-A full class listing and documentations can be found here :- 
+A full class listing and documentations can be found here :-
 
 - **Docs site:** <https://ncca.github.io/PyNGL/>
 - **Getting started / tutorials:** <https://ncca.github.io/PyNGL/tutorials/> (Getting Started and Tutorials sections)
@@ -89,7 +89,7 @@ The site covers the math API design rules, vectors/matrices/quaternions, transfo
 ### Knowledge wiki
 
 Alongside the API reference, [`wiki/`](wiki/index.md) is an agent-maintained
-knowledge base about *how PyNGL works* — architecture narratives, module
+knowledge base about _how PyNGL works_ — architecture narratives, module
 deep-dives, design decisions, and gotchas — written for both people and
 coding agents. Start at [`wiki/index.md`](wiki/index.md).
 
@@ -105,6 +105,14 @@ source files that changed. If you use Claude Code, `/wiki status`,
 `/wiki update`, and `/wiki build` maintain the wiki for you (see
 `.claude/skills/wiki/SKILL.md`).
 
+## AI Usage
+
+This project has use various AI tools ([Claude](https://claude.ai) and [Codex](https://openai.com/codex/) and [OpenCode](https://opencode.ai/)) to assist with development.
+
+The initial phases were for the full port of NGL to PyNGL (C++ to Python conversion) and additional testing. Most of the work is shown in the docs section of the repository, and I have also written about various things on my blog [her](https://nccastaff.bournemouth.ac.uk/jmacey/post/).
+
+There will be a full write-up of my setup and usage of AI on the Blog soon.
+
 ## License
 
 See [LICENSE.txt](LICENSE.txt) or just use the [Beerware License](https://scancode-licensedb.aboutcode.org/beerware.html)

run_coverage_nogpu.py

@@ -1,6 +1,5 @@
 #!/usr/bin/env -S uv run --script
-"""
-Run coverage tests without GPU dependencies.
+"""Run coverage tests without GPU dependencies.
 This script separates CPU-only tests from GPU/Qt-dependent tests.
 """
 
@@ -32,7 +31,6 @@ def run_command(cmd: str, description: str) -> bool:
 
 def main():
     """Main function to run coverage without GPU."""
-
     # CPU-only tests (no OpenGL context, no Qt)
     cpu_only_tests = [
         "tests/test_vec2.py",

tests/test_perspective_widget.py

@@ -159,7 +159,9 @@ def test_show_mode_true_shows_combobox(qt_app, qtbot):
 
 def test_mode_switch_changes_matrix(qt_app, qtbot):
     """Test that changing mode produces a different matrix (WebGPU vs OpenGL)."""
-    widget = PerspectiveWidget(show_mode=True, fov=50.0, aspect=1.5, near=0.5, far=200.0)
+    widget = PerspectiveWidget(
+        show_mode=True, fov=50.0, aspect=1.5, near=0.5, far=200.0
+    )
     qtbot.addWidget(widget)
 
     opengl_matrix = widget.matrix()
@@ -172,7 +174,9 @@ def test_mode_switch_changes_matrix(qt_app, qtbot):
 
 def test_set_mode_programmatically_without_show_mode(qt_app, qtbot):
     """Test that mode can still be set programmatically when show_mode=False."""
-    widget = PerspectiveWidget(show_mode=False, fov=50.0, aspect=1.5, near=0.5, far=200.0)
+    widget = PerspectiveWidget(
+        show_mode=False, fov=50.0, aspect=1.5, near=0.5, far=200.0
+    )
     qtbot.addWidget(widget)
 
     widget.set_mode(PerspMode.Vulkan)

tests/test_qml_mat3_model.py

@@ -1,5 +1,3 @@
-import pytest
-
 from ncca.ngl import Mat3
 
 

tests/test_qml_mat_grid_models.py

@@ -1,7 +1,6 @@
 import pytest
 
 from ncca.ngl import Mat2, Mat3, Mat4
-from ncca.ngl.mat_base import MatrixError
 
 WIDGET_CASES = [
     ("ncca.ngl.qml.mat2_model", "Mat2Model", Mat2, 2),
@@ -34,7 +33,9 @@ def test_get_and_set_cell_round_trip(qt_app, module_name, class_name, mat_cls, s
 
 
 @pytest.mark.parametrize("module_name,class_name,mat_cls,size", WIDGET_CASES)
-def test_set_cell_emits_value_changed(qt_app, qtbot, module_name, class_name, mat_cls, size):
+def test_set_cell_emits_value_changed(
+    qt_app, qtbot, module_name, class_name, mat_cls, size
+):
     model = _load_model_cls(module_name, class_name)()
 
     with qtbot.waitSignal(model.valueChanged, timeout=1000):
@@ -53,7 +54,9 @@ def test_zero_then_identity_round_trip(qt_app, module_name, class_name, mat_cls,
 
 
 @pytest.mark.parametrize("module_name,class_name,mat_cls,size", WIDGET_CASES)
-def test_transpose_reflects_current_value(qt_app, module_name, class_name, mat_cls, size):
+def test_transpose_reflects_current_value(
+    qt_app, module_name, class_name, mat_cls, size
+):
     model = _load_model_cls(module_name, class_name)()
     model.set_cell(0, 1, 7.0)
 

tests/test_wiki_check_sync.py

@@ -8,7 +8,9 @@
 
 import pytest
 
-_MODULE_PATH = Path(__file__).resolve().parent.parent / "wiki" / "tools" / "check_sync.py"
+_MODULE_PATH = (
+    Path(__file__).resolve().parent.parent / "wiki" / "tools" / "check_sync.py"
+)
 _spec = importlib.util.spec_from_file_location("check_sync", _MODULE_PATH)
 check_sync = importlib.util.module_from_spec(_spec)
 sys.modules["check_sync"] = check_sync
@@ -55,7 +57,11 @@ class TestGlobToRegex:
         [
             ("src/ncca/ngl/vec*.py", "src/ncca/ngl/vec3.py", True),
             ("src/ncca/ngl/vec*.py", "src/ncca/ngl/vec3_array.py", True),
-            ("src/ncca/ngl/vec*.py", "src/ncca/ngl/opengl/vec3.py", False),  # * stays in one dir
+            (
+                "src/ncca/ngl/vec*.py",
+                "src/ncca/ngl/opengl/vec3.py",
+                False,
+            ),  # * stays in one dir
             ("src/ncca/ngl/webgpu/**", "src/ncca/ngl/webgpu/line_pipeline.py", True),
             ("**/conftest.py", "tests/conftest.py", True),
             ("**/conftest.py", "conftest.py", True),  # **/ also matches zero dirs
@@ -99,27 +105,35 @@ def wiki_repo(tmp_path):
 
 class TestCheckPage:
     def test_fresh_when_sources_unchanged(self, wiki_repo):
-        status = check_sync.check_page(wiki_repo, wiki_repo / "wiki" / "modules" / "math.md")
+        status = check_sync.check_page(
+            wiki_repo, wiki_repo / "wiki" / "modules" / "math.md"
+        )
         assert status.state == "fresh"
         assert status.changed == []
 
     def test_stale_when_source_changes_after_sync(self, wiki_repo):
         (wiki_repo / "src" / "ncca" / "ngl" / "vec3.py").write_text("x = 2\n")
         _git(wiki_repo, "commit", "-am", "change vec3")
-        status = check_sync.check_page(wiki_repo, wiki_repo / "wiki" / "modules" / "math.md")
+        status = check_sync.check_page(
+            wiki_repo, wiki_repo / "wiki" / "modules" / "math.md"
+        )
         assert status.state == "stale"
         assert status.changed == ["src/ncca/ngl/vec3.py"]
 
     def test_fresh_when_unrelated_file_changes(self, wiki_repo):
         (wiki_repo / "README.md").write_text("hello\n")
         _git(wiki_repo, "add", ".")
         _git(wiki_repo, "commit", "-m", "add readme")
-        status = check_sync.check_page(wiki_repo, wiki_repo / "wiki" / "modules" / "math.md")
+        status = check_sync.check_page(
+            wiki_repo, wiki_repo / "wiki" / "modules" / "math.md"
+        )
         assert status.state == "fresh"
 
     def test_error_on_unknown_synced_commit(self, wiki_repo):
         page = wiki_repo / "wiki" / "modules" / "math.md"
-        page.write_text("---\nsources:\n  - src/ncca/ngl/vec*.py\nsynced: " + "0" * 40 + "\n---\n")
+        page.write_text(
+            "---\nsources:\n  - src/ncca/ngl/vec*.py\nsynced: " + "0" * 40 + "\n---\n"
+        )
         status = check_sync.check_page(wiki_repo, page)
         assert status.state == "error"
         assert "commit" in status.message

wiki/tools/check_sync.py

@@ -56,7 +56,9 @@ def parse_frontmatter(text: str) -> Frontmatter:
     if not lines or lines[0].strip() != "---":
         raise FrontmatterError("page does not start with a '---' frontmatter block")
     try:
-        end = next(i for i, line in enumerate(lines[1:], start=1) if line.strip() == "---")
+        end = next(
+            i for i, line in enumerate(lines[1:], start=1) if line.strip() == "---"
+        )
     except StopIteration:
         raise FrontmatterError("frontmatter block is never closed with '---'") from None
 
@@ -197,7 +199,9 @@ def check_page(repo_root: Path, page: Path) -> PageStatus:
             message=f"synced commit {fm.synced} not found in repository",
             frontmatter=fm,
         )
-    out = _git(repo_root, "diff", "--name-only", f"{fm.synced}..HEAD", "--", *fm.sources)
+    out = _git(
+        repo_root, "diff", "--name-only", f"{fm.synced}..HEAD", "--", *fm.sources
+    )
     changed = [line for line in out.splitlines() if line]
     state = "stale" if changed else "fresh"
     return PageStatus(path=page, state=state, changed=changed, frontmatter=fm)
@@ -241,7 +245,9 @@ def main(argv: list[str] | None = None) -> int:
         0 when every page is fresh, 1 when any page is stale or in error.
     """
     parser = argparse.ArgumentParser(description=__doc__)
-    parser.add_argument("--wiki-dir", type=Path, default=Path(__file__).resolve().parent.parent)
+    parser.add_argument(
+        "--wiki-dir", type=Path, default=Path(__file__).resolve().parent.parent
+    )
     parser.add_argument("--repo-root", type=Path, default=None)
     parser.add_argument("--json", action="store_true", dest="as_json")
     args = parser.parse_args(argv)
@@ -278,7 +284,9 @@ def main(argv: list[str] | None = None) -> int:
             if s.state == "fresh":
                 print(f"FRESH {rel}")
             elif s.state == "stale":
-                print(f"STALE {rel} — {len(s.changed)} changed since {s.frontmatter.synced[:7]}:")
+                print(
+                    f"STALE {rel} — {len(s.changed)} changed since {s.frontmatter.synced[:7]}:"
+                )
                 for f in s.changed:
                     print(f"    {f}")
             else: