DOC, MAINT: Improve GPU docs, remove references to dpctl arrays #2721

david-cortes-intel · 2025-10-10T12:38:43Z

Description

This PR:

Removes references and recommendations to use the soon-to-be-removed arrays from dpctl, replacing the suggestions for dpnp arrays instead.
Adds documentation pages for the config contexts in sklearnex.
Rewords lots of docs related to GPU support to be more clear and reflect the current behaviors of the library.

Checklist:

Completeness and readability

I have updated the documentation to reflect the changes or created a separate PR with updates and provided its number in the description, if necessary.
Git commit message contains an appropriate signed-off-by string (see CONTRIBUTING.md for details).
I have resolved any merge conflicts that might occur with the base branch.

Testing

I have run it locally and tested the changes extensively.
All CI jobs are green or I have provided justification why they aren't.

codecov · 2025-10-10T13:39:03Z

Codecov Report

✅ All modified and coverable lines are covered by tests.

Flag	Coverage Δ
azure	`80.49% <100.00%> (?)`
github	`82.09% <100.00%> (+9.07%)`	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines	Coverage Δ
sklearnex/_config.py	`100.00% <100.00%> (ø)`

... and 75 files with indirect coverage changes

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

david-cortes-intel · 2025-10-13T06:23:40Z

Failing doc CI job appears to be a rate limiting issue with medium.com.

icfaust · 2025-10-14T15:01:38Z

doc/sources/input-types.rst

+    will be converted to CSR, which implies more than just data copying.
  - Heterogeneous NumPy array
-  - If SYCL queue is provided for device without ``float64`` support but data are ``float64``, data are copied with reduced precision.
+  - If SyCL queue is provided for device without ``float64`` support but data are ``float64``, data are copied with reduced precision.


Its SYCL in all cases not in code.

icfaust · 2025-10-14T15:02:16Z

sklearnex/_config.py

 from daal4py.sklearn._utils import sklearn_check_version
 from onedal._config import _get_config as onedal_get_config

+__all__ = ["get_config", "set_config", "config_context"]


why add __all__?

It defines more objects than these 3. Adding __all__ would avoid making them exportable for asterisk imports.

icfaust · 2025-10-14T15:02:25Z

sklearnex/_config.py


+__all__ = ["get_config", "set_config", "config_context"]
+
+tab = "    " if (sys.version_info.major == 3 and sys.version_info.minor < 13) else ""


Whats up with the tabs?

Python 3.13 changed how it deals with leading whitespace in docstrings.

Does that mean we need to do it throughout the repo?

This same workaround is already used in other places throughout the repository.

Copilot

Pull Request Overview

This PR improves GPU-related documentation and modernizes array handling recommendations by removing references to soon-to-be-deprecated dpctl arrays and replacing them with dpnp arrays. Key changes include:

Adds comprehensive documentation for sklearnex configuration contexts (config_context, set_config, get_config)
Restructures and clarifies GPU support documentation with better organization and examples
Updates code examples across documentation to use dpnp and torch tensors instead of dpctl arrays

Reviewed Changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
sklearnex/_config.py	Adds shared docstring for configuration options, updates function docstrings to reference it
doc/sources/substitutions.rst	Adds substitution for dpnp_array reference link
doc/sources/oneapi-gpu.rst	Major rewrite of GPU docs with clearer sections, updated examples, and removal of dpctl array references
doc/sources/input-types.rst	Removes dpctl.tensor references, updates to mention only dpnp.ndarray
doc/sources/index.rst	Updates examples to use torch tensors instead of dpnp, fixes syntax error in code block
doc/sources/distributed-mode.rst	Updates text to reference dpnp_array instead of dpctl arrays
doc/sources/config-contexts.rst	New documentation page for configuration contexts
doc/sources/array_api.rst	Updates SyCL/SYCL spelling, removes dpctl references, adds torch tensor examples
doc/sources/algorithms.rst	Minor formatting fix to verbose mode reference

Comments suppressed due to low confidence (1)

sklearnex/_config.py:1

Corrected spelling of 'accelered' to 'accelerated'.

# ==============================================================================

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2025-11-06T05:46:00Z

sklearnex/_config.py


+__all__ = ["get_config", "set_config", "config_context"]
+
+tab = "    " if (sys.version_info.major == 3 and sys.version_info.minor < 13) else ""


The magic number 13 in the Python version check lacks explanation. Consider adding a comment explaining why Python 3.13+ requires different tab handling for docstrings, or define this as a named constant like PYTHON_VERSION_WITH_DOCSTRING_CHANGE = (3, 13).

Suggested change

tab = " " if (sys.version_info.major == 3 and sys.version_info.minor < 13) else ""

# Python 3.13+ changes tab handling in docstrings, so we adjust indentation accordingly.

PYTHON_VERSION_WITH_DOCSTRING_CHANGE = (3, 13)

tab = " " if (sys.version_info.major == 3 and sys.version_info.minor < PYTHON_VERSION_WITH_DOCSTRING_CHANGE[1]) else ""

sklearnex/_config.py

doc/sources/oneapi-gpu.rst

ethanglaser · 2025-11-06T05:29:26Z

doc/sources/index.rst

               os.environ["SCIPY_ARRAY_API"] = "1"
               import numpy as np
-               import dpnp
+               import torch


Why not keep dpnp here?

It's currently lacking important capabilities like serialization, and more likely to segfault instead of producing errors when doing something wrong with it. I think it's more likely that a user playing with this example would run into issues with dpnp than with torch, and then conclude that sklearnex can't do something before reading the docs.

ethanglaser · 2025-11-06T05:55:50Z

doc/sources/config-contexts.rst

+Overview
+========
+
+Just like |sklearn|, the |sklearnex| offers configurable options which can be managed


Minor naming conventions nitpick - I'd say it makes more sense to refer to "|sklearnex|" compared to "the |sklearnex|". The name of the project is Extension for scikit-learn. This could apply to line 24, 29, 32, 36, 48, etc.

This is a macro that expands to "Extension for Scikit-learn*":

scikit-learn-intelex/doc/sources/conf.py

Line 132 in 186b741

.. |sklearnex| replace:: Extension for Scikit-learn*

Yes but I mean to remove "the" in "the |sklearnex|" and just refer to it as |sklearnex|

So in this case "Just like |sklearn|, the Extension for Scikit-learn offers configurable options which can be managed" would be "Just like |sklearn|, Extension for Scikit-learn offers configurable options which can be managed"

I'd say

The extension for scikit-learn offers ...

.. sounds more correct to me than

Extension for scikit-learn offers ...

.. if put within a larger paragraph.

doc/sources/config-contexts.rst

doc/sources/oneapi-gpu.rst

Co-authored-by: Copilot <[email protected]>

Co-authored-by: ethanglaser <[email protected]>

clarify details on gpu support, remove references to dpctl arrays

74804ba

david-cortes-intel requested review from Alexsandruss, Vika-F, ethanglaser, icfaust, maria-Petrova, syakov-intel and yuejiaointel as code owners October 10, 2025 12:38

david-cortes-intel added documentation gpu_interfaces Array API labels Oct 10, 2025

formatting

5db1c51

david-cortes-intel added 3 commits October 13, 2025 11:09

more links

947b872

more hints

f21f741

add torch examples

dbbc3e0

david-cortes-intel mentioned this pull request Oct 14, 2025

DOC: Document serialization of objects #2729

Open

5 tasks

icfaust reviewed Oct 14, 2025

View reviewed changes

david-cortes-intel added 3 commits October 14, 2025 17:07

standardize references to sycl

b7b0c67

prefer links to parent pages

d71a1cf

more links

931d886

ethanglaser requested a review from Copilot November 6, 2025 05:45

Copilot AI reviewed Nov 6, 2025

View reviewed changes

ethanglaser reviewed Nov 6, 2025

View reviewed changes

david-cortes-intel and others added 3 commits November 6, 2025 08:03

Update sklearnex/_config.py

d4f32eb

Co-authored-by: Copilot <[email protected]>

Update doc/sources/oneapi-gpu.rst

57e45c1

Co-authored-by: Copilot <[email protected]>

Update doc/sources/oneapi-gpu.rst

aae3d17

Co-authored-by: ethanglaser <[email protected]>

david-cortes-intel and others added 2 commits November 6, 2025 08:04

Update doc/sources/config-contexts.rst

be5582d

Co-authored-by: ethanglaser <[email protected]>

Update doc/sources/oneapi-gpu.rst

6473702

Co-authored-by: ethanglaser <[email protected]>

ethanglaser mentioned this pull request Nov 6, 2025

Initial dpctl tensor removal #2764

Closed

10 tasks

ethanglaser approved these changes Nov 7, 2025

View reviewed changes

david-cortes-intel merged commit 8bb05f0 into uxlfoundation:main Nov 17, 2025
30 checks passed


		__all__ = ["get_config", "set_config", "config_context"]

		tab = " " if (sys.version_info.major == 3 and sys.version_info.minor < 13) else ""

-tab = "    " if (sys.version_info.major == 3 and sys.version_info.minor < 13) else ""
+# Python 3.13+ changes tab handling in docstrings, so we adjust indentation accordingly.
+PYTHON_VERSION_WITH_DOCSTRING_CHANGE = (3, 13)
+tab = "    " if (sys.version_info.major == 3 and sys.version_info.minor < PYTHON_VERSION_WITH_DOCSTRING_CHANGE[1]) else ""

DOC, MAINT: Improve GPU docs, remove references to dpctl arrays #2721

DOC, MAINT: Improve GPU docs, remove references to dpctl arrays #2721

Uh oh!

Conversation

david-cortes-intel commented Oct 10, 2025

Description

Uh oh!

codecov bot commented Oct 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

david-cortes-intel commented Oct 13, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Copilot AI Nov 6, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

codecov bot commented Oct 10, 2025 •

edited

Loading