NVIDIA
[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
This pull request requires additional validation before any workflows can run on NVIDIA's runners.
Pull request vetters can view their responsibilities here.
Contributors can view more details about this message here.
![copy-pr-bot[bot] avatar](https://avatars.githubusercontent.com/in/354886?v=4 "Published by a pub.dev verified publisher"){kind=small}
I'm interested in feedback on this idea. With a comprehensive style guide, aside from the other benefits listed in the description, we can use LLMs to help refactor, clean, and document the code. If the team is comfortable with this approach, I can begin to apply rules conservatively to the code base.
Will look more closely asap.
Drive-by comment: I was surprised to see the new file under cuda_core/cuda/core/. I'd expect it to be under cuda_core/, like other meta-kind-of files, e.g. LICENSE, README.md, etc.
Will look more closely asap.
Drive-by comment: I was surprised to see the new file under
cuda_core/cuda/core/. I'd expect it to be undercuda_core/, like other meta-kind-of files, e.g.LICENSE,README.md, etc.
I thought about that, too. I agree it belongs at the root.
Will look more closely asap. Drive-by comment: I was surprised to see the new file under
cuda_core/cuda/core/. I'd expect it to be undercuda_core/, like other meta-kind-of files, e.g.LICENSE,README.md, etc.I thought about that, too. I agree it belongs at the root.
Do we want this in the root? I'd expect it within a docs folder. That shouldn't impact an LLMs ability to discover and utilize it.
Merging my offline comment to here. My 2c:
- If possible I’d like to make part (or all) of this PR rendered as Sphinx docs, for both internal and external contributors to use as developer guide
- I’d also like all LLM to be able to read it when working on the codebase, including but not limited to: Cursor, CodeRabbit, Copilot, …
Doc Preview CI :---: |
:rocket: View preview athttps://nvidia.github.io/cuda-python/pr-preview/pr-1316/
|
https://nvidia.github.io/cuda-python/pr-preview/pr-1316/cuda-core/
|
https://nvidia.github.io/cuda-python/pr-preview/pr-1316/cuda-bindings/
|
https://nvidia.github.io/cuda-python/pr-preview/pr-1316/cuda-pathfinder/
|
Preview will be ready when the GitHub Pages deployment is complete.
![github-actions[bot] avatar](https://avatars.githubusercontent.com/in/15368?v=4 "Published by a pub.dev verified publisher"){kind=small}
The doc is now included with the Sphinx docs. Link above but also here . Click through CUDA Core Developer Guide.