diff --git a/docs/source/conf.py b/docs/source/conf.py index af7f86b..88d63b8 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -41,6 +41,7 @@ exclude_patterns = [] intersphinx_mapping = { + "python": ("https://docs.python.org/3/", None), "array_api": ("https://data-apis.org/array-api/latest", None), } @@ -68,6 +69,10 @@ # -Dbreathe_projects.= breathe_default_project = "dlpack" +breathe_domain_by_extension = { + "h" : "c", +} + # -- Options for HTML output ------------------------------------------------- diff --git a/docs/source/python_spec.rst b/docs/source/python_spec.rst index 73941bf..ad20ed0 100644 --- a/docs/source/python_spec.rst +++ b/docs/source/python_spec.rst @@ -13,11 +13,11 @@ Syntax for data interchange with DLPack The array API will offer the following syntax for data interchange: -1. A ``from_dlpack(x, ...)`` function, which accepts any (array) object with +1. A :func:`~array_api.from_dlpack` function, which accepts any (array) object with the two DLPack methods implemented (see below) and uses them to construct - a new array containing the data from ``x``. -2. ``__dlpack__`` and ``__dlpack_device__`` methods on the - array object, which will be called from within ``from_dlpack``, to query + a new array containing the data from the input array. +2. :meth:`~array_api.array.__dlpack__` and :meth:`~array_api.array.__dlpack_device__` methods on the + array object, which will be called from within :func:`~array_api.from_dlpack`, to query what device the array is on (may be needed to pass in the correct stream, e.g. in the case of multiple GPUs) and to access the data. @@ -39,7 +39,7 @@ may flag this and make a copy of the data. In both cases: If an array that is accessed via the interchange protocol lives on a device that the requesting (consumer) library does not support, it is recommended to raise a -``BufferError``, unless an explicit copy is requested (see below) and the producer +:obj:`BufferError`, unless an explicit copy is requested (see below) and the producer can support the request. Stream handling through the ``stream`` keyword applies to CUDA and ROCm (perhaps @@ -51,9 +51,9 @@ unnecessary so asynchronous execution is enabled. Starting Python array API standard v2023, a copy can be explicitly requested (or disabled) through the new ``copy`` argument of ``from_dlpack()``. When a copy is -made, the producer must set the ``DLPACK_FLAG_BITMASK_IS_COPIED`` bit flag. +made, the producer must set the :c:macro:`DLPACK_FLAG_BITMASK_IS_COPIED` bit flag. It is also possible to request cross-device copies through the new ``device`` -argument, though the v2023 standard only mandates the support of ``kDLCPU``. +argument, though the v2023 standard only mandates the support of :c:enumerator:`kDLCPU`. Implementation ~~~~~~~~~~~~~~ @@ -72,24 +72,25 @@ types.* Starting Python array API standard v2023, a new ``max_version`` argument is added to ``__dlpack__`` for the consumer to signal the producer the -maximal supported DLPack version. Starting DLPack 1.0, the ``DLManagedTensorVersioned`` -struct should be used and the existing ``DLManagedTensor`` struct is considered +maximal supported DLPack version. Starting DLPack 1.0, the :c:struct:`DLManagedTensorVersioned` +struct should be used and the existing :c:struct:`DLManagedTensor` struct is considered deprecated, though a library should try to support both during the transition period if possible. -In the rest of this document, ``DLManagedTensorVersioned`` and ``DLManagedTensor`` -are treated as synonyms, assuming a proper handling of ``max_version`` has been -done to choose the right struct. As far as the capsule name is concerned, -when ``DLManagedTensorVersioned`` is in use the capsule names ``dltensor`` -and ``used_dltensor`` will need a ``_versioned`` suffix. +.. note:: + In the rest of this document, ``DLManagedTensorVersioned`` and ``DLManagedTensor`` + are treated as synonyms, assuming a proper handling of ``max_version`` has been + done to choose the right struct. As far as the capsule name is concerned, + when ``DLManagedTensorVersioned`` is in use the capsule names ``dltensor`` + and ``used_dltensor`` will need a ``_versioned`` suffix. -The ``__dlpack__`` method will produce a ``PyCapsule`` containing a +The ``__dlpack__`` method will produce a :c:type:`PyCapsule` containing a ``DLManagedTensor``, which will be consumed immediately within ``from_dlpack`` - therefore it is consumed exactly once, and it will not be visible to users of the Python API. The producer must set the ``PyCapsule`` name to ``"dltensor"`` so that -it can be inspected by name, and set ``PyCapsule_Destructor`` that calls +it can be inspected by name, and set :c:type:`PyCapsule_Destructor` that calls the ``deleter`` of the ``DLManagedTensor`` when the ``"dltensor"``-named capsule is no longer needed. @@ -128,7 +129,7 @@ statically allocated. The ``DLManagedTensor`` deleter must ensure that sharing beyond Python boundaries is possible, this means that the GIL must be acquired explicitly if it uses Python objects or API. -In Python, the deleter usually needs to ``Py_DECREF()`` the original owner +In Python, the deleter usually needs to :c:func:`Py_DECREF` the original owner and free the ``DLManagedTensor`` allocation. For example, NumPy uses the following code to ensure sharing with arbitrary non-Python code is safe: @@ -157,7 +158,7 @@ non-Python code is safe: PyGILState_Release(state); } -When the ``strides`` field in the ``DLTensor`` struct is ``NULL``, it indicates a +When the :c:member:`~DLTensor.strides` field in the :c:struct:`DLTensor` struct is ``NULL``, it indicates a row-major compact array. If the array is of size zero, the data pointer in ``DLTensor`` should be set to either ``NULL`` or ``0``. @@ -165,7 +166,7 @@ For further details on DLPack design and how to implement support for it, refer to `github.com/dmlc/dlpack `_. .. warning:: - DLPack contains a ``device_id``, which will be the device + DLPack contains a :c:member:`~DLDevice.device_id`, which will be the device ID (an integer, ``0, 1, ...``) which the producer library uses. In practice this will likely be the same numbering as that of the consumer, however that is not guaranteed. Depending on the hardware @@ -174,7 +175,7 @@ refer to `github.com/dmlc/dlpack `_. possible for example for CUDA device pointers. It is recommended that implementers of this array API consider and document - whether the ``.device`` attribute of the array returned from ``from_dlpack`` is + whether the :attr:`~array_api.array.device` attribute of the array returned from ``from_dlpack`` is guaranteed to be in a certain order or not.