From 7e256885bfe2b622c8dce79c96ddcda8b891ea1b Mon Sep 17 00:00:00 2001 From: Leo Fang Date: Wed, 6 Nov 2024 04:26:55 +0000 Subject: [PATCH] populate API references; clean up & polish docs --- cuda_core/cuda/core/experimental/_launcher.py | 10 +++---- cuda_core/cuda/core/experimental/_module.py | 4 +-- cuda_core/cuda/core/experimental/_program.py | 7 +++-- .../source/_templates/autosummary/class.rst | 26 +++++++++++++++++ .../_templates/autosummary/dataclass.rst | 10 +++++++ .../_templates/autosummary/namedtuple.rst | 8 ++++++ cuda_core/docs/source/api.rst | 13 +++++++++ cuda_core/docs/source/api_private.rst | 28 +++++++++++++++++++ cuda_core/docs/source/conf.py | 6 +++- cuda_core/docs/source/install.md | 20 +++++-------- cuda_core/docs/source/release/0.1.0-notes.md | 16 ++++++----- cuda_python/docs/environment-docs.yml | 1 + 12 files changed, 117 insertions(+), 32 deletions(-) create mode 100644 cuda_core/docs/source/_templates/autosummary/class.rst create mode 100644 cuda_core/docs/source/_templates/autosummary/dataclass.rst create mode 100644 cuda_core/docs/source/_templates/autosummary/namedtuple.rst create mode 100644 cuda_core/docs/source/api_private.rst diff --git a/cuda_core/cuda/core/experimental/_launcher.py b/cuda_core/cuda/core/experimental/_launcher.py index 2787a718..9991638f 100644 --- a/cuda_core/cuda/core/experimental/_launcher.py +++ b/cuda_core/cuda/core/experimental/_launcher.py @@ -103,16 +103,14 @@ def _cast_to_3_tuple(self, cfg): def launch(kernel, config, *kernel_args): - """Launches a :obj:`Kernel` object with launch-time configuration. - - Invokes a :obj:`Kernel` object with specified launch-time - configurations. + """Launches a :obj:`~cuda.core.experimental._module.Kernel` + object with launch-time configuration. Parameters ---------- - kernel : :obj:`Kernel` + kernel : :obj:`~cuda.core.experimental._module.Kernel` Kernel to launch. - config : Any + config : :obj:`LaunchConfig` Launch configurations inline with options provided by :obj:`LaunchConfig` dataclass. *kernel_args : Any diff --git a/cuda_core/cuda/core/experimental/_module.py b/cuda_core/cuda/core/experimental/_module.py index b587d813..8b0ff9a7 100644 --- a/cuda_core/cuda/core/experimental/_module.py +++ b/cuda_core/cuda/core/experimental/_module.py @@ -48,8 +48,8 @@ def _lazy_init(): class Kernel: """Represent a compiled kernel that had been loaded onto the device. - Kernel instances can execution when passed directly into a - launch function. + Kernel instances can execution when passed directly into the + :func:`~cuda.core.experimental.launch` function. Directly creating a :obj:`Kernel` is not supported, and they should instead be created through a :obj:`ObjectCode` object. diff --git a/cuda_core/cuda/core/experimental/_program.py b/cuda_core/cuda/core/experimental/_program.py index a59324f8..5439c74a 100644 --- a/cuda_core/cuda/core/experimental/_program.py +++ b/cuda_core/cuda/core/experimental/_program.py @@ -8,7 +8,8 @@ class Program: - """Represent a compilation machinery to process programs into :obj:`ObjectCode`. + """Represent a compilation machinery to process programs into + :obj:`~cuda.core.experimental._module.ObjectCode`. This object provides a unified interface to multiple underlying compiler libraries. Compilation support is enabled for a wide @@ -19,7 +20,7 @@ class Program: code : Any String of the CUDA Runtime Compilation program. code_type : Any - String of the code type. Only "c++" is currently supported. + String of the code type. Currently only ``"c++"`` is supported. """ @@ -74,7 +75,7 @@ def compile(self, target_type, options=(), name_expressions=(), logs=None): Returns ------- - :obj:`ObjectCode` + :obj:`~cuda.core.experimental._module.ObjectCode` Newly created code object. """ diff --git a/cuda_core/docs/source/_templates/autosummary/class.rst b/cuda_core/docs/source/_templates/autosummary/class.rst new file mode 100644 index 00000000..b45a3fd5 --- /dev/null +++ b/cuda_core/docs/source/_templates/autosummary/class.rst @@ -0,0 +1,26 @@ +{{ fullname | escape | underline}} + +.. currentmodule:: {{ module }} + +.. autoclass:: {{ objname }} + + {% block methods %} + {% if methods %} + .. rubric:: {{ _('Methods') }} + + {% for item in methods %} + .. automethod:: {{ item }} + {%- endfor %} + + {% endif %} + {% endblock %} + + {% block attributes %} + {% if attributes %} + .. rubric:: {{ _('Attributes') }} + + {% for item in attributes %} + .. autoattribute:: {{ item }} + {%- endfor %} + {% endif %} + {% endblock %} diff --git a/cuda_core/docs/source/_templates/autosummary/dataclass.rst b/cuda_core/docs/source/_templates/autosummary/dataclass.rst new file mode 100644 index 00000000..b8c35324 --- /dev/null +++ b/cuda_core/docs/source/_templates/autosummary/dataclass.rst @@ -0,0 +1,10 @@ +{{ fullname | escape | underline}} + +.. currentmodule:: {{ module }} + +.. autoclass:: {{ objname }} + + {% block methods %} + .. automethod:: __init__ + {% endblock %} + diff --git a/cuda_core/docs/source/_templates/autosummary/namedtuple.rst b/cuda_core/docs/source/_templates/autosummary/namedtuple.rst new file mode 100644 index 00000000..d3ad7d24 --- /dev/null +++ b/cuda_core/docs/source/_templates/autosummary/namedtuple.rst @@ -0,0 +1,8 @@ +{{ fullname | escape | underline}} + +.. currentmodule:: {{ module }} + +.. autoclass:: {{ objname }} + :members: __new__ + :special-members: __new__ + :exclude-members: count, index, __reduce__, __reduce_ex__, __repr__, __hash__, __str__, __getnewargs__ \ No newline at end of file diff --git a/cuda_core/docs/source/api.rst b/cuda_core/docs/source/api.rst index 756ed776..1cb9811b 100644 --- a/cuda_core/docs/source/api.rst +++ b/cuda_core/docs/source/api.rst @@ -3,6 +3,11 @@ ``cuda.core.experimental`` API Reference ======================================== +All of the APIs listed (or cross-referenced from) below are considered *experimental* +and subject to future changes without deprecation notice. Once stablized they will be +moved out of the ``experimental`` namespace. + + CUDA runtime ------------ @@ -10,6 +15,14 @@ CUDA runtime :toctree: generated/ Device + launch + + :template: dataclass.rst + + EventOptions + StreamOptions + LaunchConfig + CUDA compilation toolchain -------------------------- diff --git a/cuda_core/docs/source/api_private.rst b/cuda_core/docs/source/api_private.rst new file mode 100644 index 00000000..f100eb7c --- /dev/null +++ b/cuda_core/docs/source/api_private.rst @@ -0,0 +1,28 @@ +:orphan: + +.. This page is to generate documentation for private classes exposed to users, + i.e., users cannot instantiate it by themselves but may use it's properties + or methods via returned values from public APIs. These classes must be referred + in public APIs returning their instances. + +.. currentmodule:: cuda.core.experimental + +CUDA runtime +------------ + +.. autosummary:: + :toctree: generated/ + + _memory.Buffer + _stream.Stream + _event.Event + + +CUDA compilation toolchain +-------------------------- + +.. autosummary:: + :toctree: generated/ + + _module.Kernel + _module.ObjectCode diff --git a/cuda_core/docs/source/conf.py b/cuda_core/docs/source/conf.py index 4be77656..5b28d331 100644 --- a/cuda_core/docs/source/conf.py +++ b/cuda_core/docs/source/conf.py @@ -34,7 +34,8 @@ 'sphinx.ext.autosummary', 'sphinx.ext.napoleon', 'myst_nb', - 'enum_tools.autoenum' + 'enum_tools.autoenum', + 'sphinx_copybutton', ] # Add any paths that contain templates here, relative to this directory. @@ -77,3 +78,6 @@ # relative to this directory. They are copied after the builtin static files, # so a file named "default.css" will overwrite the builtin "default.css". html_static_path = ['_static'] + +# skip cmdline prompts +copybutton_exclude = '.linenos, .gp' diff --git a/cuda_core/docs/source/install.md b/cuda_core/docs/source/install.md index 593f7225..e13f37df 100644 --- a/cuda_core/docs/source/install.md +++ b/cuda_core/docs/source/install.md @@ -5,25 +5,19 @@ `cuda.core` is supported on all platforms that CUDA is supported. Specific dependencies are as follows: -* Driver: Linux (450.80.02 or later) Windows (456.38 or later) -* CUDA Toolkit 12.0 to 12.6 +| | CUDA 11 | CUDA 12 | +|------------------ | ------------ | ----------- | +| CUDA Toolkit [^1] | 11.2 - 11.8 | 12.0 - 12.6 | +| Driver | 450.80.02+ (Linux), 452.39+ (Windows) | 525.60.13+ (Linux), 527.41+ (Windows) | - -## Installing from PyPI - -Coming soon! - - -## Installing from Conda - -Coming soon! +[^1]: Including `cuda-python`. ## Installing from Source -```shell +```console $ git clone https://github.com/NVIDIA/cuda-python $ cd cuda-python/cuda_core $ pip install . ``` -For now `cuda-python` (`cuda-bindings` later) is a required dependency. +For now `cuda-python` (`cuda-bindings` later) 11.x or 12.x is a required dependency. diff --git a/cuda_core/docs/source/release/0.1.0-notes.md b/cuda_core/docs/source/release/0.1.0-notes.md index 2247e0cb..1ebb41f9 100644 --- a/cuda_core/docs/source/release/0.1.0-notes.md +++ b/cuda_core/docs/source/release/0.1.0-notes.md @@ -1,15 +1,17 @@ -# ``cuda.core`` Release notes +# `cuda.core` Release notes -Released on Oct XX, 2024 +Released on Nov XX, 2024 ## Hightlights -- Initial beta 1 release +- Initial EA1 (early access) release - Supports all platforms that CUDA is supported -- Supports all CUDA 12.x drivers -- Supports all CUDA 12.x Toolkits +- Supports all CUDA 11.x/12.x drivers +- Supports all CUDA 11.x/12.x Toolkits - Pythonic CUDA runtime and other core functionalities ## Limitations -- Source code release only; Python packages coming in a future release -- Support for CUDA 11.x coming in the next release +- All APIs are currently *experimental* and subject to change without deprecation notice. + Please kindly share your feedbacks with us so that we can make `cuda.core` better! +- Source code release only; `pip`/`conda` support is coming in a future release +- Windows TCC mode is [not yet supported](https://github.com/NVIDIA/cuda-python/issues/206) diff --git a/cuda_python/docs/environment-docs.yml b/cuda_python/docs/environment-docs.yml index 2a3a8ad3..bc9588fd 100644 --- a/cuda_python/docs/environment-docs.yml +++ b/cuda_python/docs/environment-docs.yml @@ -11,6 +11,7 @@ dependencies: - pytest - scipy - sphinx + - sphinx-copybutton - pip: - furo - myst-nb