Merge pull request #366 from vzhurba01/12-next-docs

leofang · web-flow · commit c04025db0888 · 2025-01-24T15:09:36.000-05:00
Doc updates for 12.8
diff --git a/cuda_bindings/docs/source/index.rst b/cuda_bindings/docs/source/index.rst
@@ -5,13 +5,14 @@
    :maxdepth: 2
    :caption: Contents:
 
+   release
    install.md
    overview.md
    motivation.md
-   release.md
    environment_variables.md
-   api.rst
-   tips_and_tricks.rst
+   api
+   tips_and_tricks
+   support
 
 
 Indices and tables
diff --git a/cuda_bindings/docs/source/install.md b/cuda_bindings/docs/source/install.md
@@ -11,18 +11,33 @@
 Only the NVRTC and nvJitLink redistributable components are required from the CUDA Toolkit, which can be obtained via PyPI, Conda, or local installers (as described in the CUDA Toolkit [Windows](https://docs.nvidia.com/cuda/cuda-installation-guide-microsoft-windows/index.html) and [Linux](https://docs.nvidia.com/cuda/cuda-installation-guide-linux/index.html) Installation Guides).
 ```
 
+Starting from v12.8.0, `cuda-python` becomes a meta package which currently depends only on `cuda-bindings`; in the future more sub-packages will be added to `cuda-python`. In the instructions below, we still use `cuda-python` as example to serve existing users, but everything is applicable to `cuda-bindings` as well.
+
+
 ## Installing from PyPI
 
 ```console
-$ pip install cuda-python
+$ pip install -U cuda-python
 ```
 
+Install all optional dependencies with:
+```{code-block} shell
+pip install -U cuda-python[all]
+```
+
+Where the optional dependencies are:
+
+* nvidia-cuda-nvrtc-cu12 (Provides NVRTC shared library)
+* nvidia-nvjitlink-cu12>=12.3 (Provides nvJitLink shared library)
+
+
 ## Installing from Conda
 
 ```console
 $ conda install -c conda-forge cuda-python
 ```
 
+
 ## Installing from Source
 
 ### Requirements
@@ -43,6 +58,7 @@ See [Environment Variables](environment_variables.md) for a description of other
 Only `cydriver`, `cyruntime` and `cynvrtc` are impacted by the header requirement.
 ```
 
+
 ### Editable Install
 
 You can use
diff --git a/cuda_bindings/docs/source/release.md b/cuda_bindings/docs/source/release.md
diff --git a/cuda_bindings/docs/source/release.rst b/cuda_bindings/docs/source/release.rst
@@ -0,0 +1,30 @@
+Release Notes
+=============
+
+.. toctree::
+   :maxdepth: 3
+
+   12.8.0 <release/12.8.0-notes.md>
+   12.6.2 <release/12.6.2-notes.md>
+   12.6.1 <release/12.6.1-notes.md>
+   12.6.0 <release/12.6.0-notes.md>
+   12.5.0 <release/12.5.0-notes.md>
+   12.4.0 <release/12.4.0-notes.md>
+   12.3.0 <release/12.3.0-notes.md>
+   12.2.1 <release/12.2.1-notes.md>
+   12.2.0 <release/12.2.0-notes.md>
+   12.1.0 <release/12.1.0-notes.md>
+   12.0.0 <release/12.0.0-notes.md>
+   11.8.6 <release/11.8.6-notes.md>
+   11.8.5 <release/11.8.5-notes.md>
+   11.8.4 <release/11.8.4-notes.md>
+   11.8.3 <release/11.8.3-notes.md>
+   11.8.2 <release/11.8.2-notes.md>
+   11.8.1 <release/11.8.1-notes.md>
+   11.8.0 <release/11.8.0-notes.md>
+   11.7.1 <release/11.7.1-notes.md>
+   11.7.0 <release/11.7.0-notes.md>
+   11.6.1 <release/11.6.1-notes.md>
+   11.6.0 <release/11.6.0-notes.md>
+   11.5.0 <release/11.5.0-notes.md>
+   11.4.0 <release/11.4.0-notes.md>
diff --git a/cuda_bindings/docs/source/release/11.8.6-notes.md b/cuda_bindings/docs/source/release/11.8.6-notes.md
@@ -0,0 +1,28 @@
+# `cuda-bindings` 11.8.6 Release notes
+
+Released on January 24, 2025.
+
+
+## Highlights
+
+- Add an optional dependency on the CUDA NVRTC wheel
+- Enable discovery and loading of shared libraries from CUDA wheels
+- `cuda-python` is now a meta package, currently depending only on `cuda-bindings` ([see RFC](https://github.com/NVIDIA/cuda-python/issues/105))
+
+
+## Wheels support for optional dependencies
+
+Optional dependencies are added for packages:
+
+- nvidia-cuda-nvrtc-cu12
+
+Installing these dependencies with `cuda-python` can be done using:
+```{code-block} shell
+pip install cuda-python[all]
+```
+Same applies to `cuda-bindings`.
+
+
+## Discovery and loading of shared library dependencies from wheels
+
+Shared library search paths for wheel builds are now extended to check site-packages. This allows `cuda-python`/`cuda-bindings` to seamlessly use the aforementioned CUDA Toolkit wheels installed in the user's Python environment.
diff --git a/cuda_bindings/docs/source/release/12.8.0-notes.md b/cuda_bindings/docs/source/release/12.8.0-notes.md
@@ -0,0 +1,30 @@
+# `cuda-bindings` 12.8.0 Release notes
+
+Released on January 24, 2025.
+
+
+## Highlights
+
+- Add bindings for nvJitLink (requires nvJitLink from CUDA 12.3 or above)
+- Add optional dependencies on CUDA NVRTC and nvJitLink wheels
+- Enable discovery and loading of shared libraries from CUDA wheels
+- `cuda-python` is now a meta package, currently depending only on `cuda-bindings` ([see RFC](https://github.com/NVIDIA/cuda-python/issues/105))
+
+
+## Wheels support for optional dependencies
+
+Optional dependencies are added for packages:
+
+- nvidia-cuda-nvrtc-cu12
+- nvidia-nvjitlink-cu12
+
+Installing these dependencies with `cuda-python` can be done using:
+```{code-block} shell
+pip install cuda-python[all]
+```
+Same applies to `cuda-bindings`.
+
+
+## Discovery and loading of shared library dependencies from wheels
+
+Shared library search paths for wheel builds are now extended to check site-packages. This allows `cuda-python`/`cuda-bindings` to seamlessly use the aforementioned CUDA Toolkit wheels installed in the user's Python environment.
diff --git a/cuda_bindings/docs/source/release/12.x.y-notes.md b/cuda_bindings/docs/source/release/12.x.y-notes.md
diff --git a/cuda_bindings/docs/source/support.rst b/cuda_bindings/docs/source/support.rst
@@ -0,0 +1,28 @@
+``cuda.bindings`` Support Policy
+================================
+
+The ``cuda.bindings`` module has the following support policy:
+
+1. The module shares the same ``major.minor`` version with the CUDA Toolkit. The patch version (the
+   third number in the version string), however, is reserved to reflect Python-only changes and
+   is out of sync with the Toolkit patch version.
+2. The module is actively maintained to support the latest CUDA major version and its prior major
+   version. For example, as of writing the bindings for CUDA 11 & 12 are maintained. Any fix in the
+   latest bindings would be backported to the prior major version.
+3. The module supports `CUDA minor version compatibility`_, meaning that ``cuda.bindings`` 12.x
+   supports any Toolkit 12.y. (Whether or not a binding API would actually correctly function
+   depends on the underlying driver and the Toolkit versions, as described in the compatibility
+   documentation.)
+4. The module supports all Python versions following the `CPython EOL schedule`_. As of writing
+   Python 3.9 - 3.13 are supported.
+5. The module exposes a Cython layer from which types and functions could be ``cimport``'d. While
+   we strive to keep this layer stable, due to Cython limitations a new *minor* release of this
+   module could require Cython layer users to rebuild their projects and update their pinning to
+   this module.
+
+The NVIDIA CUDA Python team reserves rights to amend the above support policy. Any major changes,
+however, will be announced to the users in advance.
+
+
+.. _CUDA minor version compatibility: https://docs.nvidia.com/deploy/cuda-compatibility/#minor-version-compatibility
+.. _CPython EOL schedule: https://devguide.python.org/versions/
diff --git a/cuda_bindings/docs/source/tips_and_tricks.rst b/cuda_bindings/docs/source/tips_and_tricks.rst
@@ -9,6 +9,12 @@ All CUDA C types are exposed to Python as Python classes. For example, the :clas
 There is an important distinction between the ``getPtr()`` method and the behaviour of ``__int__()``. If you need to get the pointer address *of* the underlying ``CUstream`` C object wrapped in the Python class, you can do so by calling ``int(instance_of_CUstream)``, which returns the address as a Python `int`, while calling ``instance_of_CUstream.getPtr()`` returns the pointer *to* the ``CUstream`` C object (that is, ``&CUstream``) as a Python `int`.
 
 
+Lifetime management of the CUDA objects
+=======================================
+
+All of the Python classes do not manage the lifetime of the underlying CUDA C objects. It is the user's responsibility to use the appropriate APIs to explicitly destruct the objects following the CUDA Programming Guide.
+
+
 Getting and setting attributes of extension types
 =================================================
 
@@ -30,4 +36,3 @@ An example of this is the :class:`~cuda.bindings.driver.CULaunchConfig` type.
 
     # This does not work. We are only modifying the returned attribute in place
     drv_cfg.attrs.append(attr)
-
diff --git a/cuda_bindings/docs/versions.json b/cuda_bindings/docs/versions.json
@@ -1,5 +1,6 @@
 {
     "latest"  : "latest",
-    "12.6.1"  : "12.6.1",
-    "12.6.2"  : "12.6.2"
+    "12.8.0"  : "12.8.0",
+    "12.6.2"  : "12.6.2",
+    "12.6.1"  : "12.6.1"
 }
diff --git a/cuda_python/docs/source/release.md b/cuda_python/docs/source/release.md
@@ -5,6 +5,8 @@
 maxdepth: 3
 ---
 
+    12.8.0 <release/12.8.0-notes>
     12.6.2 <release/12.6.2-notes>
     12.6.1 <release/12.6.1-notes>
+    11.8.6 <release/11.8.6-notes>
 ```
diff --git a/cuda_python/docs/source/release/11.8.6-notes.md b/cuda_python/docs/source/release/11.8.6-notes.md
@@ -0,0 +1,14 @@
+# CUDA Python 11.8.6 Release notes
+
+Released on January 24, 2025.
+
+## Included components
+
+- [`cuda.bindings` 11.8.6](https://nvidia.github.io/cuda-python/cuda-bindings/11.8.6/release/11.8.6-notes.html)
+
+
+## Highlights
+
+- Add optional dependencies on the CUDA NVRTC wheel
+- Enable discovery and loading of shared libraries from CUDA wheels
+- `cuda-python` is now a meta package, currently depending only on `cuda-bindings` ([see RFC](https://github.com/NVIDIA/cuda-python/issues/105))
diff --git a/cuda_python/docs/source/release/12.8.0-notes.md b/cuda_python/docs/source/release/12.8.0-notes.md
@@ -0,0 +1,15 @@
+# CUDA Python 12.8.0 Release notes
+
+Released on January 24, 2025.
+
+## Included components
+
+- [`cuda.bindings` 12.8.0](https://nvidia.github.io/cuda-python/cuda-bindings/12.8.0/release/12.8.0-notes.html)
+
+
+## Highlights
+
+- Add bindings for nvJitLink (requires nvJitLink from CUDA 12.3 or above)
+- Add optional dependencies on CUDA NVRTC and nvJitLink wheels
+- Enable discovery and loading of shared libraries from CUDA wheels
+- `cuda-python` is now a meta package, currently depending only on `cuda-bindings` ([see RFC](https://github.com/NVIDIA/cuda-python/issues/105))
diff --git a/cuda_python/docs/versions.json b/cuda_python/docs/versions.json
@@ -1,5 +1,6 @@
 {
     "latest"  : "latest",
-    "12.6.1"  : "12.6.1",
-    "12.6.2"  : "12.6.2"
+    "12.8.0"  : "12.8.0",
+    "12.6.2"  : "12.6.2",
+    "12.6.1"  : "12.6.1"
 }

Original file line number	Diff line number	Diff line change
`@@ -1,5 +1,6 @@`
`1`	`1`	`{`
`2`	`2`	`"latest" : "latest",`
`3`		`- "12.6.1" : "12.6.1",`
`4`		`- "12.6.2" : "12.6.2"`
	`3`	`+ "12.8.0" : "12.8.0",`
	`4`	`+ "12.6.2" : "12.6.2",`
	`5`	`+ "12.6.1" : "12.6.1"`
`5`	`6`	`}`