[FEA]: Introduce `.pyi` files for signatures and docstrings

[Andy-Jost]

Area

cuda.core

Is your feature request related to a problem? Please describe.

See comment https://github.com/NVIDIA/cuda-python/pull/1316/changes#r2598892097

Describe the solution you'd like

Explore using .pyi files for type signatures and docstrings. Use .pyx only for implementation. If a good solution is found, update docs/developer-guide.md.

[Andy-Jost]

It appears that .pyi files would introduce a significant maintenance burden. Both docstrings and type annotations would need to be repeated in .pyx and .pyi files. It seems to me that if we want to use .pyi files, we need a way to auto-generate them. Any comment @mdboom?

Benefits

1. IDE Support: Modern IDEs (VS Code, PyCharm) don't import Cython modules for autocomplete. Without .pyi stubs, users get no autocomplete, type hints, or go-to-definition for .pyx modules. Stubs enable full IDE functionality.
2. Static Type Checking: Tools like mypy can validate user code against the library's type signatures, catching errors before runtime.
3. Documentation Generation: Sphinx and other doc tools can more reliably extract signatures from .pyi files than from compiled Cython modules.

Costs

1. Significant Duplication: Both type annotations and docstrings must remain in .pyx files for runtime functionality (help(), doc, Cython type enforcement). Adding .pyi files means maintaining this information in two places.
2. Maintenance Burden: Stubs must be kept in sync with implementation. Any signature or docstring change requires updating both files, creating high risk of drift.
3. No Runtime Effect: .pyi files are purely for static analysis. They don't replace anything in .pyx files; they only duplicate it for tooling visibility.
4. Tooling Gaps: Auto-generation tools like stubgen produce incomplete stubs for Cython code, requiring manual refinement and ongoing maintenance.