Add documentation for patching utilities and `interfaces` by ndgrigorian · Pull Request #107 · IntelPython/mkl_random

ndgrigorian · 2026-03-19T21:41:35Z

This PR adds documentation for patching and for the interfaces submodule

ndgrigorian · 2026-03-20T02:15:54Z

@antonwolfy @jharlow-intel
Downloading the documentation artifact and opening with python -m http.server --directory /dir/with/unzipped/docs, the changes seem to be working, and there are docs pages for mkl_random.interfaces, the patching, and new APIs

PR is ready for review

antonwolfy · 2026-03-20T12:01:25Z

Downloading the documentation artifact

Alternatively, it can be downloaded through GH action

antonwolfy · 2026-03-20T12:05:35Z

docs/source/reference/api.rst

+Class MKLRandomState
+====================
+
+.. autoclass:: mkl_random.MKLRandomState


The rendered page has # no-cython-lint. Is there a way to suppress the linter warning without being shown on the generated page?

antonwolfy · 2026-03-20T12:07:08Z

docs/source/reference/interfaces.rst

+
+.. autoclass:: mkl_random.interfaces.numpy_random.RandomState
+    :members:
+    :undoc-members:


The same here: # noqa: E501,W505

antonwolfy · 2026-03-20T12:07:58Z

docs/source/reference/interfaces.rst

+-------------------------------------------------------------
+
+:mod:`mkl_random.interfaces.numpy_random` is a drop-in replacement for the legacy portion of
+:mod:`numpy.random`.


Should it be a ref on numpy.random page?

antonwolfy · 2026-03-20T12:09:10Z

docs/source/reference/interfaces.rst

+.. note::
+    While the API is the same, :mod:`mkl_random.interfaces.numpy_random` is **not** seed-compatible
+    with :mod:`numpy.random`. Given the same seed, the two modules will produce different sequences.
+    The output of `get_state` and accepted input to `set_state` may also differ. It is not


Should here be a ref on functions?

Suggested change

The output of `get_state` and accepted input to `set_state` may also differ. It is not

The output of :func:`get_state` and accepted input to :func:`set_state` may also differ. It is not

antonwolfy · 2026-03-20T12:10:28Z

docs/source/reference/interfaces.rst

+
+.. autoclass:: mkl_random.interfaces.numpy_random.RandomState
+    :members:
+    :undoc-members:


The link on numpy.random.RandomState is not clicable:

For full documentation refer to numpy.random.RandomState.

antonwolfy · 2026-03-20T12:15:03Z

docs/source/reference/interfaces.rst

+
+.. autosummary::
+
+    mkl_random.interfaces.numpy_random.rand


The link on page with numpy corresponding functions are not working.

antonwolfy · 2026-03-20T12:16:29Z

docs/source/reference/interfaces.rst

+
+    mkl_random.interfaces.numpy_random.seed
+    mkl_random.interfaces.numpy_random.get_state
+    mkl_random.interfaces.numpy_random.set_state


Should it be clickable to go from the table to the function description?

antonwolfy · 2026-03-20T12:17:10Z

docs/source/reference/patching.rst

+============================
+
+:mod:`mkl_random` can temporarily replace functions and classes in :mod:`numpy.random` with
+:mod:`mkl_random`implementations from the :ref:`numpy interface <numpy_random_interface>`.


Suggested change

:mod:`mkl_random`implementations from the :ref:`numpy interface <numpy_random_interface>`.

:mod:`mkl_random` implementations from the :ref:`numpy interface <numpy_random_interface>`.

antonwolfy · 2026-03-20T12:20:51Z

docs/source/reference/interfaces.rst

+modules using :mod:`mkl_random` implementations. Currently, only a NumPy interface is provided,
+but more may be added in the future.
+
+


Should we updat examples in brngs description with MKLRandomState? (I mean pages, like: rendered%20documentation/reference/mt19937.html)

The same is about example on How-to guide (documentation/how_to.html)

And Beginner's guide (documentation/tutorials.html)

antonwolfy · 2026-03-20T12:25:41Z

docs/source/index.rst


-        The reference guide contains a detailed description of class :class:`mkl_random.RandomState` and its methods.
+        The reference guide contains a detailed description of class :class:`mkl_random.MKLRandomState`,
+        the :ref:`interfaces <interfaces>` submodule, and :ref:`NumPy patching <patching>` utilities.


All links here are referred on documentation/reference/index.html page, but I guess, it should be on specific section with detailed description.

ndgrigorian force-pushed the document-numpy-interface branch from 8b56414 to d26d763 Compare March 19, 2026 21:46

ndgrigorian added 3 commits March 19, 2026 18:36

add documentation for patching utilities and interfaces

0df625b

show inherited members in MKLRandomState and RandomState

b56e5f5

add sections to index.rst about interfaces and patching

fe7b7a2

ndgrigorian force-pushed the document-numpy-interface branch from d26d763 to fe7b7a2 Compare March 20, 2026 01:44

ndgrigorian marked this pull request as ready for review March 20, 2026 02:14

ndgrigorian requested review from antonwolfy, jharlow-intel and xaleryb as code owners March 20, 2026 02:14

antonwolfy reviewed Mar 20, 2026

View reviewed changes

	The output of `get_state` and accepted input to `set_state` may also differ. It is not
	The output of :func:`get_state` and accepted input to :func:`set_state` may also differ. It is not

	:mod:`mkl_random`implementations from the :ref:`numpy interface <numpy_random_interface>`.
	:mod:`mkl_random` implementations from the :ref:`numpy interface <numpy_random_interface>`.

		modules using :mod:`mkl_random` implementations. Currently, only a NumPy interface is provided,
		but more may be added in the future.

Conversation

ndgrigorian commented Mar 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ndgrigorian commented Mar 20, 2026

Uh oh!

antonwolfy commented Mar 20, 2026

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!

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!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

ndgrigorian commented Mar 19, 2026 •

edited

Loading