Convert all markdown files to ReST format and add pre-commit hook

Co-authored-by: leofang <5534781+leofang@users.noreply.github.com>

Author: Copilot

.pre-commit-config.yaml

@@ -30,6 +30,12 @@ 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
+        name: Prevent Markdown files in cuda_*/docs/ directories
+        entry: bash -c 'if git diff --cached --name-only --diff-filter=A | grep -E "^cuda_.*/docs/.*\.md$"; then echo "Error: Markdown files are not allowed in cuda_*/docs/ directories. Please use .rst format instead."; exit 1; fi'
+        language: system
+        pass_filenames: false
+        always_run: true
 
   - repo: https://github.com/PyCQA/bandit
     rev: 2d0b675b04c80ae42277e10500db06a0a37bae17  # frozen: 1.8.6

cuda_bindings/docs/README.rst

@@ -0,0 +1,11 @@
+Build the documentation
+=======================
+
+1. Install the ``cuda-bindings`` package of the version that we need to document.
+2. Ensure the version is included in the ```versions.json`` <./versions.json>`__.
+3. Build the docs with ``./build_docs.sh``.
+4. The html artifacts should be available under both ``./build/html/latest`` and ``./build/html/<version>``.
+
+Alternatively, we can build all the docs at once by running ```cuda_python/docs/build_all_docs.sh`` <../../cuda_python/docs/build_all_docs.sh>`__.
+
+To publish the docs with the built version, it is important to note that the html files of older versions should be kept intact, in order for the version selection (through ``versions.json``) to work.

cuda_bindings/docs/source/conduct.rst

@@ -0,0 +1,57 @@
+Code of Conduct
+===============
+
+Overview
+--------
+
+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 our community a harassment-free experience for everyone, regardless of age, body 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
+-------------
+
+Examples of behavior that contributes to creating a positive environment include:
+
+-  Using welcoming and inclusive language
+-  Being respectful of differing viewpoints and experiences
+-  Gracefully accepting constructive criticism
+-  Focusing on what is best for the community
+-  Showing empathy towards other community members
+
+Examples of unacceptable behavior by participants include:
+
+-  The use of sexualized language or imagery and unwelcome sexual attention or advances
+-  Trolling, insulting/derogatory comments, and personal or political attacks
+-  Public or private harassment
+-  Publishing others’ private information, such as a physical or electronic address, without explicit permission
+-  Other conduct which could reasonably be considered inappropriate in a professional setting
+
+Our Responsibilities
+--------------------
+
+Project maintainers are responsible for clarifying the standards of acceptable behavior and are expected to take appropriate and fair corrective action in response to any instances of unacceptable behavior.
+
+Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions 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
+-----
+
+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 representing a project or community include using an official project e-mail 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
+-----------
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project team at 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 incident. Further details of specific enforcement policies may be posted separately.
+
+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
+-----------
+
+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
+
+For answers to common questions about this code of conduct, see https://www.contributor-covenant.org/faq

cuda_bindings/docs/source/contribute.rst

@@ -0,0 +1,13 @@
+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>`__ 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 comment on the issue to notify the team.
+
+2. You want to implement a feature, improvement, or bug fix:
+
+   -  At this time we do not accept code contributions.

cuda_bindings/docs/source/environment_variables.rst

@@ -0,0 +1,16 @@
+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\_, where 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.

cuda_bindings/docs/source/index.rst

@@ -9,15 +9,15 @@
    :caption: Contents:
 
    release
-   install.md
-   overview.md
-   motivation.md
-   environment_variables.md
+   install.rst
+   overview.rst
+   motivation.rst
+   environment_variables.rst
    api
    tips_and_tricks
    support
-   contribute.md
-   conduct.md
+   contribute.rst
+   conduct.rst
    license
 
 

cuda_bindings/docs/source/install.rst

@@ -0,0 +1,95 @@
+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:: 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:: 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:: console
+
+   $ conda install -c conda-forge cuda-python cuda-version=13
+
+Installing from Source
+----------------------
+
+Requirements
+~~~~~~~~~~~~
+
+-  CUDA Toolkit headers [1]_
+-  CUDA Runtime static library [2]_
+
+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:: 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:: 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).
+
+.. [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.

cuda_bindings/docs/source/motivation.rst

@@ -0,0 +1,18 @@
+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?
+----------------
+
+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 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 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, CuPy will have a lighter maintenance overhead and have fewer wheels to release. Users benefit from a faster CUDA runtime!
+
+Our goal is to help unify the Python CUDA ecosystem with a single standard set of interfaces, providing full coverage of, and access to, the CUDA host APIs from Python. We want to provide a foundation for the ecosystem to build on top of in unison to allow composing different accelerated libraries together to solve the problems at hand. We also want to lower the barrier to entry for Python developers to utilize NVIDIA GPUs.