docs: Add section to explain Guppy type checker errors and fixes

sphinx/faqs.md

@@ -55,3 +55,91 @@ This Guppy function doesn't currently have compilation to HUGR. Please find/rais
 ## Why am I getting "no lowering found" errors?
 
 Though Guppy can compile your operation to HUGR, the lowering to LLVM executable code for the Selene simulator doesn't yet work. Please find a workaround or raise an issue on the [HUGR repository](https://github.com/quantinuum/hugr/).
+
+## Why is my type checker raising errors with Guppy?
+
+When using a Python type checker (such as [mypy](https://www.mypy-lang.org/)) with Guppy you may encounter errors that arise from a fundamental difference between Python and Guppy syntax.
+
+For example, using `@ owned` annotations in function signatures, 
+
+```{code-cell} ipython3
+from guppylang.std.builtins import owned
+
+@guppy
+def foo(q: qubit @ owned) -> None: ...
+```
+
+is not valid Python syntax and `mypy` will raise the following error:
+
+```
+error: Invalid type comment or annotation  [valid-type]
+```
+
+As this is a fundamental difference between Python and Guppy, it is not possible to resolve these errors. Instead, these errors must be suppressed in order for the type checker to run without error. There are two methods to suppress errors raised by `mypy`, although this may differ if another checker is used.
+
+To suppress individual errors, the `type: ignore[...]` comment can be used on the line that causes the error. In this example, we can suppress the `valid-type` error with:
+
+```{code-cell} ipython3
+@guppy
+def foo(q: qubit @ owned) -> None: ...  # type: ignore[valid-type]
+```
+
+In the case where multiple errors are raised in the same function, it may be more convenient to suppress all errors using `@no_type_check`:
+
+```{code-cell} ipython3
+from typing import no_type_check
+
+@guppy
+@no_type_check
+def foo(q: qubit @ owned) -> None: ...
+```
+
+Below are a few common examples in which Guppy will cause an error with `mypy` that will need to be suppressed.
+
+### Generic Guppy variables
+
+Using generic Guppy variables in function signatures can cause `mypy` to raise errors. For example, the following use of a generic type variable will raise the `valid-type` error:
+
+```{code-cell} ipython3
+T = guppy.type_var("T")
+
+@guppy
+def foo(x: T) -> T: ...
+```
+
+Using generic natural variables can cause `mypy` to raise `call-overload` errors when used as arguments to other functions within a generic function definition. For example, using `range` with a generic will raise a `call-overload` error:
+
+```{code-cell} ipython3
+from guppylang.std.builtins import array
+
+N = guppy.nat_var("N")
+
+@guppy
+def foo(arr: array[qubit, N]) -> None:
+    for _ in range(N): ...
+```
+
+### Guppy structs
+
+Guppy structs can be a significant source of type check errors, especially when they are defined using generic variables. Consider the following example that defines a Guppy struct that has a generic size for the array:
+
+
+```{code-cell} ipython3
+from typing import Generic
+
+@guppy.struct
+class Foo(Generic[N]):
+    arr: array[qubit, N]
+```
+
+This will raise two type check errors from `mypy`:
+1. `Unsupported dynamic base class "Generic"  [misc]`
+2. `Variable "N" is not valid as a type  [valid-type]`
+
+Unfortunately, `@no_type_check` cannot be used to suppress errors in Guppy structs, so instead individual errors must be suppressed with `type: ignore`. In the example above, this would look like:
+
+```{code-cell} ipython3
+@guppy.struct
+class Foo(Generic[N]):  # type: ignore[misc]
+    arr: array[qubit, N]  # type: ignore[valid-type]
+```