cuda-python
cuda-python copied to clipboard
[doc-only] Add developer guide for cuda.core
Summary
This PR adds a developer guide for Python and Cython code in cuda/core. The guide establishes conventions and best practices to maintain code quality and consistency across the codebase.
What's Included
The guide covers 10 major areas:
-
File Structure - Ordering of elements (SPDX headers, imports,
__all__, classes, functions) -
Package Layout - Organization of
.pyx,.pxd, and.pyfiles - Import Statements - Five-group organization with alphabetical sorting
- Class and Function Definitions - Ordering within classes (dunder methods, methods, properties)
-
Naming Conventions - Project-specific patterns (Cython
c_prefix, type suffixes) - Type Annotations and Declarations - Modern PEP 604 union syntax, Cython declarations
- Docstrings - NumPy docstring style with Sphinx cross-references
- Errors and Warnings - Custom CUDA exceptions, error handling patterns
- CUDA-Specific Patterns - GIL management for CUDA driver API calls
- Development Lifecycle - Two-phase development (Python first, then Cython optimization)
Key Principles
- PEP 8 and PEP 257 Base: References these as normative standards, documenting only project-specific extensions
- Guidelines, Not Rules: Emphasizes readability and maintainability over rigid enforcement
- Codebase-Aligned: Examples reflect actual patterns from the codebase
File Added
-
cuda_core/docs/source/developer-guide.rst