From b4d3f8dac5ea7f0bc98555462a700ba5d339775f Mon Sep 17 00:00:00 2001 From: Nikita Grigorian Date: Thu, 27 Feb 2025 14:59:28 -0800 Subject: [PATCH 1/7] Add generated documentation for enumerated types in dpctl --- docs/doc_sources/api_reference/dpctl/index.rst | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/docs/doc_sources/api_reference/dpctl/index.rst b/docs/doc_sources/api_reference/dpctl/index.rst index 2547bbdf32..52c616cdaf 100644 --- a/docs/doc_sources/api_reference/dpctl/index.rst +++ b/docs/doc_sources/api_reference/dpctl/index.rst @@ -62,6 +62,17 @@ has_cpu_devices has_accelerator_devices +.. rubric:: Enums + +.. autosummary:: + :toctree: generated + :nosignatures: + + device_type + backend_type + event_status_type + global_mem_cache_type + .. rubric:: Exceptions .. autosummary:: From 3a459eed23385870e3a782bd0f2e7bd56cd4b2d9 Mon Sep 17 00:00:00 2001 From: Nikita Grigorian Date: Fri, 14 Mar 2025 14:37:42 -0700 Subject: [PATCH 2/7] Document enum values for dpctl enums directly in docstring Better and more accurate formatting --- dpctl/enum_types.py | 32 ++++++++++++++++++++++++++++---- 1 file changed, 28 insertions(+), 4 deletions(-) diff --git a/dpctl/enum_types.py b/dpctl/enum_types.py index 56168ff788..229562a5e7 100644 --- a/dpctl/enum_types.py +++ b/dpctl/enum_types.py @@ -27,7 +27,16 @@ class device_type(Enum): """ - An enumeration of supported SYCL device types. + An :class:`enum.Enum` of supported SYCL device types. + + Accepted enum values are + + ``all``: + ``accelerator`` + ``automatic`` + ``cpu`` + ``custom`` + ``gpu`` :Example: .. code-block:: python @@ -54,7 +63,15 @@ class device_type(Enum): class backend_type(Enum): """ - An enumeration of supported SYCL backends. + An :class:`enum.Enum` of supported SYCL backends. + + Accepted enum values are + + ``all``: + ``cuda`` + ``hip`` + ``level_zero`` + ``opencl`` :Example: .. code-block:: python @@ -76,7 +93,7 @@ class backend_type(Enum): class event_status_type(Enum): """ - An enumeration of SYCL event states. + An :class:`enum.Enum` of SYCL event states. :Example: .. code-block:: python @@ -95,7 +112,14 @@ class event_status_type(Enum): class global_mem_cache_type(Enum): """ - An enumeration of global memory cache types for a device. + An :class:`enum.Enum` of global memory cache types for a device. + + Accepted enum values are + + ``indeterminate``: + ``none`` + ``read_only`` + ``read_write`` :Example: .. code-block:: python From aa7a0b0cf64749f60a9d60ed5088db31045bbf82 Mon Sep 17 00:00:00 2001 From: Nikita Grigorian Date: Fri, 14 Mar 2025 22:19:49 -0700 Subject: [PATCH 3/7] Add `constants.rst` for documenting dpctl constants Also adds custom formatting for Enums into `index.rst` --- .../api_reference/dpctl/constants.rst | 16 ++++++++ .../doc_sources/api_reference/dpctl/index.rst | 17 ++++---- dpctl/enum_types.py | 41 +++++++++---------- 3 files changed, 46 insertions(+), 28 deletions(-) create mode 100644 docs/doc_sources/api_reference/dpctl/constants.rst diff --git a/docs/doc_sources/api_reference/dpctl/constants.rst b/docs/doc_sources/api_reference/dpctl/constants.rst new file mode 100644 index 0000000000..d82194c942 --- /dev/null +++ b/docs/doc_sources/api_reference/dpctl/constants.rst @@ -0,0 +1,16 @@ +.. _dpctl_constants: + +Constants +======================== + +The following constants are defined in :py:mod:`dpctl`: + +.. currentmodule:: dpctl + +.. autodata:: backend_type + +.. autodata:: device_type + +.. autodata:: event_status_type + +.. autodata:: global_mem_cache_type diff --git a/docs/doc_sources/api_reference/dpctl/index.rst b/docs/doc_sources/api_reference/dpctl/index.rst index 52c616cdaf..eba6afff41 100644 --- a/docs/doc_sources/api_reference/dpctl/index.rst +++ b/docs/doc_sources/api_reference/dpctl/index.rst @@ -64,14 +64,17 @@ .. rubric:: Enums -.. autosummary:: - :toctree: generated - :nosignatures: +.. list-table:: + :widths: 10 50 - device_type - backend_type - event_status_type - global_mem_cache_type + * - :py:class:`dpctl.device_type` + - An :class:`enum.Enum` of supported SYCL device types. + * - :py:class:`dpctl.backend_type` + - An :class:`enum.Enum` of supported SYCL backends. + * - :py:class:`dpctl.event_status_type` + - An :class:`enum.Enum` of SYCL event states. + * - :py:class:`dpctl.global_mem_cache_type` + - An :class:`enum.Enum` of global memory cache types for a device. .. rubric:: Exceptions diff --git a/dpctl/enum_types.py b/dpctl/enum_types.py index 229562a5e7..10265a9832 100644 --- a/dpctl/enum_types.py +++ b/dpctl/enum_types.py @@ -29,14 +29,12 @@ class device_type(Enum): """ An :class:`enum.Enum` of supported SYCL device types. - Accepted enum values are - - ``all``: - ``accelerator`` - ``automatic`` - ``cpu`` - ``custom`` - ``gpu`` + | ``all`` + | ``accelerator`` + | ``automatic`` + | ``cpu`` + | ``custom`` + | ``gpu`` :Example: .. code-block:: python @@ -65,13 +63,11 @@ class backend_type(Enum): """ An :class:`enum.Enum` of supported SYCL backends. - Accepted enum values are - - ``all``: - ``cuda`` - ``hip`` - ``level_zero`` - ``opencl`` + | ``all`` + | ``cuda`` + | ``hip`` + | ``level_zero`` + | ``opencl`` :Example: .. code-block:: python @@ -95,6 +91,11 @@ class event_status_type(Enum): """ An :class:`enum.Enum` of SYCL event states. + | ``unknown_status`` + | ``submitted`` + | ``running`` + | ``complete`` + :Example: .. code-block:: python @@ -114,12 +115,10 @@ class global_mem_cache_type(Enum): """ An :class:`enum.Enum` of global memory cache types for a device. - Accepted enum values are - - ``indeterminate``: - ``none`` - ``read_only`` - ``read_write`` + | ``indeterminate`` + | ``none`` + | ``read_only`` + | ``read_write`` :Example: .. code-block:: python From 687927591ca4cac7631e1b4851967b5dd4e0f7f9 Mon Sep 17 00:00:00 2001 From: Nikita Grigorian Date: Fri, 14 Mar 2025 23:18:03 -0700 Subject: [PATCH 4/7] Reorder constants page This way it matches the order on the index page for `dpctl` module --- docs/doc_sources/api_reference/dpctl/constants.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/doc_sources/api_reference/dpctl/constants.rst b/docs/doc_sources/api_reference/dpctl/constants.rst index d82194c942..8e9ebdbf39 100644 --- a/docs/doc_sources/api_reference/dpctl/constants.rst +++ b/docs/doc_sources/api_reference/dpctl/constants.rst @@ -7,10 +7,10 @@ The following constants are defined in :py:mod:`dpctl`: .. currentmodule:: dpctl -.. autodata:: backend_type - .. autodata:: device_type +.. autodata:: backend_type + .. autodata:: event_status_type .. autodata:: global_mem_cache_type From 73649323491e1b64f53df9b5502e81886f8409d7 Mon Sep 17 00:00:00 2001 From: Nikita Grigorian Date: Mon, 17 Mar 2025 10:30:34 -0700 Subject: [PATCH 5/7] Tweaks to examples in dpctl enum docstrings Remove unnecessary `print()` of the enums --- dpctl/enum_types.py | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/dpctl/enum_types.py b/dpctl/enum_types.py index 10265a9832..824723b011 100644 --- a/dpctl/enum_types.py +++ b/dpctl/enum_types.py @@ -76,7 +76,7 @@ class backend_type(Enum): # create a SYCL device with OpenCL backend using filter selector d = dpctl.SyclDevice("opencl") - print(d.backend) + d.backend # Possible output: """ @@ -101,7 +101,7 @@ class event_status_type(Enum): import dpctl ev = dpctl.SyclEvent() - print(ev.execution_status ) + ev.execution_status # Possible output: """ @@ -125,7 +125,7 @@ class global_mem_cache_type(Enum): import dpctl dev = dpctl.SyclDevice() - print(dev.global_mem_cache_type) + dev.global_mem_cache_type # Possible output: """ From 69dbd2a81ac2dd596ffc7cf484a99b7678e05a25 Mon Sep 17 00:00:00 2001 From: Nikita Grigorian Date: Tue, 18 Mar 2025 10:50:17 -0700 Subject: [PATCH 6/7] Small tweaks to dpctl and dpctl.tensor constants pages --- docs/doc_sources/api_reference/dpctl/constants.rst | 2 +- docs/doc_sources/api_reference/dpctl/tensor.constants.rst | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/doc_sources/api_reference/dpctl/constants.rst b/docs/doc_sources/api_reference/dpctl/constants.rst index 8e9ebdbf39..a7a44a69d1 100644 --- a/docs/doc_sources/api_reference/dpctl/constants.rst +++ b/docs/doc_sources/api_reference/dpctl/constants.rst @@ -1,7 +1,7 @@ .. _dpctl_constants: Constants -======================== +========= The following constants are defined in :py:mod:`dpctl`: diff --git a/docs/doc_sources/api_reference/dpctl/tensor.constants.rst b/docs/doc_sources/api_reference/dpctl/tensor.constants.rst index 2cb9f770d2..6c166a3fa6 100644 --- a/docs/doc_sources/api_reference/dpctl/tensor.constants.rst +++ b/docs/doc_sources/api_reference/dpctl/tensor.constants.rst @@ -1,7 +1,7 @@ .. _dpctl_tensor_constants: Constants -======================== +========= The following constants are defined in :py:mod:`dpctl.tensor`: From 09846201facc5d1f33b706241da1def0bce7156e Mon Sep 17 00:00:00 2001 From: Nikita Grigorian Date: Tue, 18 Mar 2025 13:09:00 -0700 Subject: [PATCH 7/7] Fix extra space in docstring for global_mem_cache_type enums --- docs/doc_sources/api_reference/dpctl/index.rst | 2 +- dpctl/enum_types.py | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/doc_sources/api_reference/dpctl/index.rst b/docs/doc_sources/api_reference/dpctl/index.rst index eba6afff41..11f86ecb21 100644 --- a/docs/doc_sources/api_reference/dpctl/index.rst +++ b/docs/doc_sources/api_reference/dpctl/index.rst @@ -74,7 +74,7 @@ * - :py:class:`dpctl.event_status_type` - An :class:`enum.Enum` of SYCL event states. * - :py:class:`dpctl.global_mem_cache_type` - - An :class:`enum.Enum` of global memory cache types for a device. + - An :class:`enum.Enum` of global memory cache types for a device. .. rubric:: Exceptions diff --git a/dpctl/enum_types.py b/dpctl/enum_types.py index 824723b011..627ba31ac7 100644 --- a/dpctl/enum_types.py +++ b/dpctl/enum_types.py @@ -113,7 +113,7 @@ class event_status_type(Enum): class global_mem_cache_type(Enum): """ - An :class:`enum.Enum` of global memory cache types for a device. + An :class:`enum.Enum` of global memory cache types for a device. | ``indeterminate`` | ``none``