docs for instance checking

docs/design.md

@@ -17,6 +17,7 @@ relatively low. Its `Dtype[ArrayClass, "{shape_expression}"]` syntax is not well
 suited for modeling arrays intended to be general across implementations, and 
 makes it challenging to adapt to pydantic's schema generation system.
 
+(design_challenges)=
 ## Challenges
 
 The Python type annotation system is weird and not like the rest of Python! 

docs/index.md

@@ -57,6 +57,25 @@ model = MyModel(array=('data.zarr', '/nested/dataset'))
 model = MyModel(array="data.mp4")
 ```
 
+And use the `NDArray` type annotation like a regular type outside
+of pydantic -- eg. to validate an array anywhere, use `isinstance`:
+
+```python
+array_type = NDArray[Shape["1, 2, 3"], int]
+isinstance(np.zeros((1,2,3), dtype=int), array_type)
+# True
+isinstance(zarr.zeros((1,2,3), dtype=int), array_type)
+# True
+isinstance(np.zeros((4,5,6), dtype=int), array_type)
+# False
+isinstance(np.zeros((1,2,3), dtype=float), array_type)
+# False
+```
+
+```{note}
+`NDArray` can't do validation with static type checkers yet, see 
+{ref}`design_challenges` and {ref}`type_checkers`
+```
 
 ## Features:
 - **Types** - Annotations (based on [npytyping](https://github.com/ramonhagenaars/nptyping))

docs/todo.md

@@ -10,6 +10,21 @@ type system and is no longer actively maintained. We will be reimplementing a sy
 that extends its array specification syntax to include things like ranges and extensible
 dtypes with varying precision (and is much less finnicky to deal with).
 
+(type_checkers)=
+## Type Checker Integration
+
+The `.pyi` stubfile generation ({mod}`numpydantic.meta`) works for 
+keeping type checkers from complaining about various array formats
+not literally being `NDArray` objects, but it doesn't do the kind of 
+validation we would want to be able to use `NDArray` objects as full-fledged
+python types, including validation propagation through scopes and 
+IDE type checking for invalid literals.
+
+We want to hook into the type checking process to satisfy these type checkers:
+- mypy - has hooks, can be done with an extension
+- pyright - unclear if has hooks, might nee to monkeypatch
+- pycharm - unlikely this is possible, extensions need to be in Java and installed separately
+
 
 ## Validation