cuda-python icon indicating copy to clipboard operation
cuda-python copied to clipboard

[doc-only] Add developer guide for cuda.core

Open Andy-Jost opened this issue 1 month ago • 18 comments

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:

  1. File Structure - Ordering of elements (SPDX headers, imports, __all__, classes, functions)
  2. Package Layout - Organization of .pyx, .pxd, and .py files
  3. Import Statements - Five-group organization with alphabetical sorting
  4. Class and Function Definitions - Ordering within classes (dunder methods, methods, properties)
  5. Naming Conventions - Project-specific patterns (Cython c_ prefix, type suffixes)
  6. Type Annotations and Declarations - Modern PEP 604 union syntax, Cython declarations
  7. Docstrings - NumPy docstring style with Sphinx cross-references
  8. Errors and Warnings - Custom CUDA exceptions, error handling patterns
  9. CUDA-Specific Patterns - GIL management for CUDA driver API calls
  10. 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

Andy-Jost avatar Dec 04 '25 20:12 Andy-Jost