cuda_core: derive error enum explanations from bindings docstrings

[rwgk]

Closes #1712

This PR grows out of the validation work under #1805. That work showed that driver/runtime error enums expose usable per-member __doc__ text once a small amount of normalization is applied. The enum docstrings are usable starting with cuda-bindings >= 13.2.0 on the main branch, and cuda-bindings 12.9.6 on the 12.9.x backport branch. See the comment below for a summary of a manual review of the cleaned enum docstrings.

Summary

• use cleaned enum __doc__ strings for driver/runtime error explanations in cuda_core when 12.9.6 <= cuda-bindings < 13.0.0 or cuda-bindings >= 13.2.0
• keep the CTK 13.1.1 explanation tables frozen as fallback for bindings versions that do not expose usable enum-member __doc__
• centralize the version gate + cleanup logic in enum_explanations_helpers.py
• update cuda_utils coverage to share the same version predicate and verify representative enums expose __doc__ and that explanation text is attached to raised CUDAErrors
• remove the obsolete toolshed/reformat_cuda_enums_as_py.py

[copy-pr-bot]

Auto-sync is disabled for draft pull requests in this repository. Workflows must be run manually.

Contributors can view more details about this message here.

[rwgk]

/ok to test

[github-actions]

Doc Preview CI
🚀 View preview at https://nvidia.github.io/cuda-python/pr-preview/pr-1860/
https://nvidia.github.io/cuda-python/pr-preview/pr-1860/cuda-core/
https://nvidia.github.io/cuda-python/pr-preview/pr-1860/cuda-bindings/
https://nvidia.github.io/cuda-python/pr-preview/pr-1860/cuda-pathfinder/
Preview will be ready when the GitHub Pages deployment is complete.

[rwgk]

/ok to test

[rwgk]

I manually reviewed the cleaned driver/runtime enum-doc output for both cuda-bindings 13.2.0 and cuda-bindings 12.9.6 using this local helper script:

from __future__ import annotations

import cuda.bindings
from cuda.bindings import driver, runtime

from cuda.core._utils.enum_explanations_helpers import clean_enum_member_docstring


def dump_enum_docs(label, enum_type):
    print(f"=== {label} ===")
    for member in enum_type:
        cleaned = clean_enum_member_docstring(member.__doc__)
        print(f"{member.name} ({int(member)})")
        print(cleaned if cleaned is not None else "<None>")
        print()


def main():
    print(f"cuda.bindings.__version__ = {cuda.bindings.__version__}")
    print()
    dump_enum_docs("driver.CUresult", driver.CUresult)
    dump_enum_docs("runtime.cudaError_t", runtime.cudaError_t)


if __name__ == "__main__":
    main()

High-level result from the manual review:

• the cleaned output looks presentable in both versions
• I did not see leftover ~, ::, or Sphinx-role markup in the cleaned strings
• this gave me enough confidence to use the docstring-backed path for 12.9.6 <= cuda-bindings < 13.0.0 as well as cuda-bindings >= 13.2.0
• the only remaining oddities I noticed look upstream/generated rather than cleanup-related: cudaErrorIncompatibleDriverContext still says this the CUDA Runtime, and cudaErrorApiFailureBase has no docstring (which still falls back to cudaGetErrorString() in cuda_core)

[rwgk]

/ok to test