NVIDIA · leofang · Aug 25, 2025 · Aug 23, 2025 · Aug 23, 2025 · Aug 23, 2025
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -30,6 +30,14 @@ repos:
         language: python
         additional_dependencies:
           - https://files.pythonhosted.org/packages/cc/20/ff623b09d963f88bfde16306a54e12ee5ea43e9b597108672ff3a408aad6/pathspec-0.12.1-py3-none-any.whl
+
+      - id: no-markdown-in-docs-source
+        name: Prevent markdown files in docs/source directories
+        entry: bash -c
+        args: ['if find . -path "*/docs/source/*.md" -not -path "./docs/README.md" | grep -q .; then echo "ERROR: Markdown files found in docs/source/ directories. Use reStructuredText (.rst) instead."; exit 1; fi']
+        language: system
+        pass_filenames: false
+        always_run: true
 
   - repo: https://github.com/PyCQA/bandit
     rev: 2d0b675b04c80ae42277e10500db06a0a37bae17  # frozen: 1.8.6

diff --git a/cuda_core/docs/source/conduct.md → cuda_bindings/docs/source/conduct.rst b/cuda_core/docs/source/conduct.md → cuda_bindings/docs/source/conduct.rst
@@ -1,10 +1,16 @@
-# Code of Conduct
+.. SPDX-FileCopyrightText: Copyright (c) 2025 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+.. SPDX-License-Identifier: LicenseRef-NVIDIA-SOFTWARE-LICENSE
 
-## Overview
+Code of Conduct
+===============
 
-Define the code of conduct followed and enforced for the `cuda.core` project.
+Overview
+--------
 
-## Our Pledge
+Define the code of conduct followed and enforced for the ``cuda.bindings`` project.
+
+Our Pledge
+----------
 
 In the interest of fostering an open and welcoming environment, we as
 contributors and maintainers pledge to making participation in our project and
@@ -13,7 +19,8 @@ size, disability, ethnicity, sex characteristics, gender identity and expression
 level of experience, education, socio-economic status, nationality, personal
 appearance, race, religion, or sexual identity and orientation.
 
-## Our Standards
+Our Standards
+-------------
 
 Examples of behavior that contributes to creating a positive environment
 include:
@@ -35,7 +42,8 @@ Examples of unacceptable behavior by participants include:
 * Other conduct which could reasonably be considered inappropriate in a
   professional setting
 
-## Our Responsibilities
+Our Responsibilities
+--------------------
 
 Project maintainers are responsible for clarifying the standards of acceptable
 behavior and are expected to take appropriate and fair corrective action in
@@ -47,7 +55,8 @@ that are not aligned to this Code of Conduct, or to ban temporarily or
 permanently any contributor for other behaviors that they deem inappropriate,
 threatening, offensive, or harmful.
 
-## Scope
+Scope
+-----
 
 This Code of Conduct applies both within project spaces and in public spaces
 when an individual is representing the project or its community. Examples of
@@ -56,11 +65,12 @@ address, posting via an official social media account, or acting as an appointed
 representative at an online or offline event. Representation of a project may be
 further defined and clarified by project maintainers.
 
-## Enforcement
+Enforcement
+-----------
 
 Instances of abusive, harassing, or otherwise unacceptable behavior may be
 reported by contacting the project team at
-[cuda-python-conduct@nvidia.com](mailto:cuda-python-conduct@nvidia.com) All
+`cuda-python-conduct@nvidia.com <mailto:cuda-python-conduct@nvidia.com>`_ All
 complaints will be reviewed and investigated and will result in a response that
 is deemed necessary and appropriate to the circumstances. The project team is
 obligated to maintain confidentiality with regard to the reporter of an
@@ -71,12 +81,11 @@ Project maintainers who do not follow or enforce the Code of Conduct in good
 faith may face temporary or permanent repercussions as determined by other
 members of the project's leadership.
 
-## Attribution
+Attribution
+-----------
 
-This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
+This Code of Conduct is adapted from the `Contributor Covenant <https://www.contributor-covenant.org>`_, version 1.4,
 available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html
 
-[homepage]: https://www.contributor-covenant.org
-
 For answers to common questions about this code of conduct, see
 https://www.contributor-covenant.org/faq
diff --git a/cuda_bindings/docs/source/contribute.md → cuda_bindings/docs/source/contribute.rst b/cuda_bindings/docs/source/contribute.md → cuda_bindings/docs/source/contribute.rst
@@ -1,9 +1,13 @@
-# Contributing
+.. SPDX-FileCopyrightText: Copyright (c) 2025 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+.. SPDX-License-Identifier: LicenseRef-NVIDIA-SOFTWARE-LICENSE
 
-Thank you for your interest in contributing to `cuda-bindings`! Based on the type of contribution, it will fall into two categories:
+Contributing
+============
+
+Thank you for your interest in contributing to ``cuda-bindings``! Based on the type of contribution, it will fall into two categories:
 
 1. You want to report a bug, feature request, or documentation issue
-    - File an [issue](https://github.com/NVIDIA/cuda-python/issues/new/choose)
+    - File an `issue <https://github.com/NVIDIA/cuda-python/issues/new/choose>`_
     describing what you encountered or what you want to see changed.
     - The NVIDIA team will evaluate the issues and triage them, scheduling
     them for a release. If you believe the issue needs priority attention

diff --git a/cuda_bindings/docs/source/environment_variables.md b/cuda_bindings/docs/source/environment_variables.md
diff --git a/cuda_bindings/docs/source/environment_variables.rst b/cuda_bindings/docs/source/environment_variables.rst
@@ -0,0 +1,19 @@
+.. SPDX-FileCopyrightText: Copyright (c) 2025 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+.. SPDX-License-Identifier: LicenseRef-NVIDIA-SOFTWARE-LICENSE
+
+Environment Variables
+=====================
+
+Build-Time Environment Variables
+--------------------------------
+
+- ``CUDA_HOME`` or ``CUDA_PATH``: Specifies the location of the CUDA Toolkit.
+
+- ``CUDA_PYTHON_PARSER_CACHING`` : bool, toggles the caching of parsed header files during the cuda-bindings build process. If caching is enabled (``CUDA_PYTHON_PARSER_CACHING`` is True), the cache path is set to ./cache_<library_name>, where <library_name> is derived from the cuda toolkit libraries used to build cuda-bindings.
+
+- ``CUDA_PYTHON_PARALLEL_LEVEL`` (previously ``PARALLEL_LEVEL``) : int, sets the number of threads used in the compilation of extension modules. Not setting it or setting it to 0 would disable parallel builds.
+
+Runtime Environment Variables
+-----------------------------
+
+- ``CUDA_PYTHON_CUDA_PER_THREAD_DEFAULT_STREAM`` : When set to 1, the default stream is the per-thread default stream. When set to 0, the default stream is the legacy default stream. This defaults to 0, for the legacy default stream. See `Stream Synchronization Behavior <https://docs.nvidia.com/cuda/cuda-runtime-api/stream-sync-behavior.html>`_ for an explanation of the legacy and per-thread default streams.
diff --git a/cuda_bindings/docs/source/index.rst b/cuda_bindings/docs/source/index.rst
@@ -9,15 +9,15 @@
    :caption: Contents:
 
    release
-   install.md
-   overview.md
-   motivation.md
-   environment_variables.md
+   install
+   overview
+   motivation
+   environment_variables
    api
    tips_and_tricks
    support
-   contribute.md
-   conduct.md
+   contribute
+   conduct
    license
 
 

diff --git a/cuda_bindings/docs/source/install.md b/cuda_bindings/docs/source/install.md
diff --git a/cuda_bindings/docs/source/install.rst b/cuda_bindings/docs/source/install.rst
@@ -0,0 +1,94 @@
+.. SPDX-FileCopyrightText: Copyright (c) 2025 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+.. SPDX-License-Identifier: LicenseRef-NVIDIA-SOFTWARE-LICENSE
+
+Installation
+============
+
+Runtime Requirements
+--------------------
+
+``cuda.bindings`` supports the same platforms as CUDA. Runtime dependencies are:
+
+* Linux (x86-64, arm64) and Windows (x86-64)
+* Python 3.9 - 3.13
+* Driver: Linux (580.65.06 or later) Windows (580.88 or later)
+* Optionally, NVRTC, nvJitLink, NVVM, and cuFile from CUDA Toolkit 13.x
+
+.. note::
+
+   The optional CUDA Toolkit components are now installed via the ``cuda-toolkit`` metapackage from PyPI for improved dependency resolution. Components can also be installed via Conda, OS-specific package managers, 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
+--------------------
+
+.. code-block:: console
+
+   $ pip install -U cuda-python
+
+Install all optional dependencies with:
+.. code-block:: console
+
+   pip install -U cuda-python[all]
+
+Where the optional dependencies include:
+
+* ``nvidia-cuda-nvrtc`` (NVRTC runtime compilation library)  
+* ``nvidia-nvjitlink`` (nvJitLink library)
+* ``nvidia-nvvm`` (NVVM library)
+* ``nvidia-cufile`` (cuFile library, Linux only)
+
+These are now installed through the ``cuda-toolkit`` metapackage for improved dependency resolution.
+
+Installing from Conda
+---------------------
+
+.. code-block:: console
+
+   $ conda install -c conda-forge cuda-python
+
+.. note::
+
+   When using conda, the ``cuda-version`` metapackage can be used to control the versions of CUDA Toolkit components that are installed to the conda environment.
+
+For example:
+.. code-block:: console
+
+   $ conda install -c conda-forge cuda-python cuda-version=13
+
+Installing from Source
+----------------------
+
+Requirements
+^^^^^^^^^^^^
+
+* CUDA Toolkit headers[^1]
+* CUDA Runtime static library[^2]
+
+[^1]: User projects that ``cimport`` CUDA symbols in Cython must also use CUDA Toolkit (CTK) types as provided by the ``cuda.bindings`` major.minor version. This results in CTK headers becoming a transitive dependency of downstream projects through CUDA Python.
+
+[^2]: The CUDA Runtime static library (``libcudart_static.a`` on Linux, ``cudart_static.lib`` on Windows) is part of the CUDA Toolkit. If using conda packages, it is contained in the ``cuda-cudart-static`` package.
+
+Source builds require that the provided CUDA headers are of the same major.minor version as the ``cuda.bindings`` you're trying to build. Despite this requirement, note that the minor version compatibility is still maintained. Use the ``CUDA_HOME`` (or ``CUDA_PATH``) environment variable to specify the location of your headers. For example, if your headers are located in ``/usr/local/cuda/include``, then you should set ``CUDA_HOME`` with:
+
+.. code-block:: console
+
+   $ export CUDA_HOME=/usr/local/cuda
+
+See `Environment Variables <environment_variables.rst>`_ for a description of other build-time environment variables.
+
+.. note::
+
+   Only ``cydriver``, ``cyruntime`` and ``cynvrtc`` are impacted by the header requirement.
+
+Editable Install
+^^^^^^^^^^^^^^^^
+
+You can use
+
+.. code-block:: console
+
+   $ pip install -v -e .
+
+to install the module as editable in your current Python environment (e.g. for testing of porting other libraries to use the binding).