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,7 +81,8 @@ 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,
 available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html

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:: shell
+
+   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).
diff --git a/cuda_bindings/docs/source/motivation.md → cuda_bindings/docs/source/motivation.rst b/cuda_bindings/docs/source/motivation.md → cuda_bindings/docs/source/motivation.rst
@@ -1,32 +1,38 @@
-# Motivation
-## What is CUDA Python?
+.. SPDX-FileCopyrightText: Copyright (c) 2025 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+.. SPDX-License-Identifier: LicenseRef-NVIDIA-SOFTWARE-LICENSE
 
-NVIDIA’s CUDA Python provides [Cython](https://cython.org/) bindings and Python
+Motivation
+==========
+What is CUDA Python?
+--------------------
+
+NVIDIA’s CUDA Python provides `Cython <https://cython.org/>`_ bindings and Python
 wrappers for the driver and runtime API for existing toolkits and libraries to
 simplify GPU-based accelerated processing. Python is one of the most popular
 programming languages for science, engineering, data analytics, and deep 
 learning applications.  The goal of CUDA Python is to unify
 the Python ecosystem with a single set of interfaces that provide full coverage
 of and access to the CUDA host APIs from Python.
 
-## Why CUDA Python?
+Why CUDA Python?
+----------------
 
 CUDA Python provides uniform APIs and bindings for inclusion into existing
 toolkits and libraries to simplify GPU-based parallel processing for HPC, data
 science, and AI.
 
-[Numba](https://numba.pydata.org/), a Python compiler from
-[Anaconda](https://www.anaconda.com/) that can compile Python code for execution
+`Numba <https://numba.pydata.org/>`_, a Python compiler from
+`Anaconda <https://www.anaconda.com/>`_ that can compile Python code for execution
 on CUDA-capable GPUs, provides Python developers with an easy entry into
 GPU-accelerated computing and a path for using increasingly sophisticated CUDA
 code with a minimum of new syntax and jargon. Numba has its own CUDA driver API 
 bindings that can now be replaced with CUDA Python. With CUDA Python and Numba, 
 you get the best of both worlds: rapid iterative development with Python and the
 speed of a compiled language targeting both CPUs and NVIDIA GPUs.
 
-[CuPy](https://cupy.dev/) is a
-[NumPy](https://numpy.org/)/[SciPy](https://www.scipy.org/) compatible Array
-library, from [Preferred Networks](https://www.preferred.jp/en/), for
+`CuPy <https://cupy.dev/>`_ is a
+`NumPy <https://numpy.org/>`_/`SciPy <https://www.scipy.org/>`_ compatible Array
+library, from `Preferred Networks <https://www.preferred.jp/en/>`_, for
 GPU-accelerated computing with Python. CUDA Python simplifies the CuPy build 
 and allows for a faster and smaller memory footprint when importing the CuPy 
 Python module. In the future, when more CUDA Toolkit libraries are supported,