Skip to content

Add documentation for patching utilities and interfaces - #107

Open
ndgrigorian wants to merge 18 commits into
masterfrom
document-numpy-interface
Open

ndgrigorian wants to merge 18 commits into
masterfrom
document-numpy-interface

Conversation

@ndgrigorian

@ndgrigorian ndgrigorian commented Mar 19, 2026 •

Copy link
Copy Markdown
Collaborator

This PR adds documentation for patching and for the interfaces submodule

@ndgrigorian
ndgrigorian force-pushed the document-numpy-interface branch 2 times, most recently from d26d763 to fe7b7a2 Compare March 20, 2026 01:44
@ndgrigorian
ndgrigorian marked this pull request as ready for review March 20, 2026 02:14
@ndgrigorian

Copy link
Copy Markdown
Collaborator Author

@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

Copy link
Copy Markdown
Collaborator

Downloading the documentation artifact

Alternatively, it can be downloaded through GH action

Comment thread docs/source/reference/api.rst
Comment thread docs/source/reference/interfaces.rst
Comment thread docs/source/reference/interfaces.rst Outdated
Comment thread docs/source/reference/interfaces.rst Outdated
Comment thread docs/source/reference/interfaces.rst
Comment thread docs/source/reference/interfaces.rst Outdated
Comment thread docs/source/reference/interfaces.rst Outdated
Comment thread docs/source/reference/patching.rst Outdated
Comment thread docs/source/reference/interfaces.rst
Comment thread docs/source/index.rst Outdated
@ndgrigorian
ndgrigorian force-pushed the document-numpy-interface branch 4 times, most recently from 297cb4b to 9422ee0 Compare April 6, 2026 22:57
@ndgrigorian
ndgrigorian requested a review from antonwolfy April 6, 2026 23:10
@ndgrigorian

Copy link
Copy Markdown
Collaborator Author

@antonwolfy
ready for another review

@antonwolfy antonwolfy added this to the 1.4.0 release milestone Apr 10, 2026
Comment thread docs/source/tutorials.rst Outdated
Comment thread docs/source/reference/patching.rst
Comment thread mkl_random/interfaces/_numpy_random.py Outdated
Comment thread mkl_random/interfaces/_numpy_random.py
@ndgrigorian
ndgrigorian force-pushed the document-numpy-interface branch from 19ef65c to d12cacb Compare April 11, 2026 01:26
@ndgrigorian
ndgrigorian force-pushed the document-numpy-interface branch from d12cacb to 42f9b70 Compare April 11, 2026 01:48
@ndgrigorian
ndgrigorian force-pushed the document-numpy-interface branch from 9d5ae7a to 0c4d814 Compare April 11, 2026 02:24
@ndgrigorian
ndgrigorian requested a review from antonwolfy April 11, 2026 02:24
@ndgrigorian

Copy link
Copy Markdown
Collaborator Author

@antonwolfy ping

@jharlow-intel jharlow-intel left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for writing these up! The interfaces and patching pages are a really useful addition, and I checked that every function in the autodoc lists is actually exported by numpy_random. It has fallen pretty far behind master, though, so it needs a rebase before it can merge; details inline.

  • This one needs a rebase before it can merge: it's 171 commits behind master and conflicts in how_to.rst, where master has since added a thread-safety section. The red 3.14t Jenkins builds look like a side effect of the old base too, since it predates the free-threading support from #159, so a rebase should clear those.

Comment thread docs/source/conf.py

# remove linter flags from rendered docstrings


Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

#165 also reworks api.rst (autosummary tables plus numpydoc) and removes the # no-cython-lint markers that this hook strips, and both PRs touch the same mklrand.pyx docstrings. Would it make sense to land #165 first and rebase this on top, keeping the new interfaces and patching pages and dropping the overlapping api.rst/conf.py changes?

.. autofunction:: mkl_random.is_patched


Context manager

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Could we also cover the command-line patching here? On master, python -m mkl_random --patch install|uninstall|status manages a persistent patch, and python -m mkl_random --with-numpy-patch <command> runs a single command with the patch applied; neither is mentioned yet. A short section, or a follow-up issue, would round this out.

different streams of randomness, also known as basic random number generators.

The basic random number generator is chosen by specifying :code:`brng` keyword argument to the constructor of :code:`mkl.RandomState` class.
The basic random number generator is chosen by specifying :code:`brng` keyword argument to the constructor of :code:`mkl.MKLRandomState` class.

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nit: mkl.MKLRandomState here should be mkl_random.MKLRandomState (the old mkl.RandomState typo carried over in the rename).

Suggested change
The basic random number generator is chosen by specifying :code:`brng` keyword argument to the constructor of :code:`mkl.MKLRandomState` class.
The basic random number generator is chosen by specifying :code:`brng` keyword argument to the constructor of :code:`mkl_random.MKLRandomState` class.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants