From 89119ef5de110bcbca23b48c14234875b0fc19e7 Mon Sep 17 00:00:00 2001 From: Vladislav Perevezentsev Date: Wed, 26 Aug 2026 04:26:22 -0700 Subject: [PATCH 1/6] Align distribution docstrings with NumPy --- mkl_random/mklrand.pyx | 154 +++++++++++++++++++++++++---------------- 1 file changed, 94 insertions(+), 60 deletions(-) diff --git a/mkl_random/mklrand.pyx b/mkl_random/mklrand.pyx index edbcd400..023526aa 100644 --- a/mkl_random/mklrand.pyx +++ b/mkl_random/mklrand.pyx @@ -2458,10 +2458,10 @@ cdef class _MKLRandomState: Parameters ---------- - low : float, optional + low : float or array_like of floats, optional Lower boundary of the output interval. All values generated will be greater than or equal to low. The default value is 0. - high : float + high : float or array_like of floats Upper boundary of the output interval. All values generated will be less than high. The default value is 1.0. size : int or tuple of ints, optional @@ -2827,10 +2827,11 @@ cdef class _MKLRandomState: Parameters ---------- - loc : float + loc : float or array_like of floats Mean ("centre") of the distribution. - scale : float + scale : float or array_like of floats Standard deviation (spread or "width") of the distribution. + Must be non-negative. size : int or tuple of ints, optional Output shape. If the given shape is, e.g., ``(m, n, k)``, then ``m * n * k`` samples are drawn. Default is None, in which case a @@ -2839,6 +2840,11 @@ cdef class _MKLRandomState: Sampling method used by Intel MKL. Can also be specified using tokens mkl_random.ICDF, mkl_random.BOXMULLER, mkl_random.BOXMULLER2 + Returns + ------- + out : ndarray or scalar + Drawn samples from the parameterized normal distribution. + See Also -------- scipy.stats.distributions.norm : probability density function, @@ -2996,9 +3002,9 @@ cdef class _MKLRandomState: Parameters ---------- - a : float + a : float or array_like of floats Alpha, non-negative. - b : float + b : float or array_like of floats Beta, non-negative. size : int or tuple of ints, optional Output shape. If the given shape is, e.g., ``(m, n, k)``, then @@ -3066,13 +3072,19 @@ cdef class _MKLRandomState: Parameters ---------- - scale : float + scale : float or array_like of floats The scale parameter, :math:`\\beta = 1/\\lambda`. + Must be non-negative. size : int or tuple of ints, optional Output shape. If the given shape is, e.g., ``(m, n, k)``, then ``m * n * k`` samples are drawn. Default is None, in which case a single value is returned. + Returns + ------- + out : ndarray or scalar + Drawn samples from the parameterized exponential distribution. + References ---------- .. [1] Peyton Z. Peebles Jr., "Probability, Random Variables and @@ -3199,7 +3211,7 @@ cdef class _MKLRandomState: Parameters ---------- - shape : float + shape : float or array_like of floats Parameter, should be > 0. size : int or tuple of ints, optional Output shape. If the given shape is, e.g., ``(m, n, k)``, then @@ -3297,10 +3309,12 @@ cdef class _MKLRandomState: Parameters ---------- - shape : scalar > 0 + shape : float or array_like of floats The shape of the gamma distribution. - scale : scalar > 0, optional - The scale of the gamma distribution. Default is equal to 1. + Must be non-negative. + scale : float or array_like of floats, optional + The scale of the gamma distribution. Must be non-negative. + Default is equal to 1. size : int or tuple of ints, optional Output shape. If the given shape is, e.g., ``(m, n, k)``, then ``m * n * k`` samples are drawn. Default is None, in which case a @@ -3409,9 +3423,9 @@ cdef class _MKLRandomState: Parameters ---------- - dfnum : float + dfnum : float or array_like of floats Degrees of freedom in numerator. Should be greater than zero. - dfden : float + dfden : float or array_like of floats Degrees of freedom in denominator. Should be greater than zero. size : int or tuple of ints, optional Output shape. If the given shape is, e.g., ``(m, n, k)``, then @@ -3516,11 +3530,11 @@ cdef class _MKLRandomState: Parameters ---------- - dfnum : int + dfnum : float or array_like of floats Parameter, should be > 1. - dfden : int + dfden : float or array_like of floats Parameter, should be > 1. - nonc : float + nonc : float or array_like of floats Parameter, should be >= 0. size : int or tuple of ints, optional Output shape. If the given shape is, e.g., ``(m, n, k)``, then @@ -3636,8 +3650,8 @@ cdef class _MKLRandomState: Parameters ---------- - df : int - Number of degrees of freedom. + df : float or array_like of floats + Number of degrees of freedom, must be > 0. size : int or tuple of ints, optional Output shape. If the given shape is, e.g., ``(m, n, k)``, then ``m * n * k`` samples are drawn. Default is None, in which case a @@ -3719,16 +3733,22 @@ cdef class _MKLRandomState: Parameters ---------- - df : int + df : float or array_like of floats Degrees of freedom, should be > 0 as of Numpy 1.10, should be > 1 for earlier versions. - nonc : float + nonc : float or array_like of floats Non-centrality, should be non-negative. size : int or tuple of ints, optional Output shape. If the given shape is, e.g., ``(m, n, k)``, then ``m * n * k`` samples are drawn. Default is None, in which case a single value is returned. + Returns + ------- + out : ndarray or scalar + Drawn samples from the parameterized noncentral + chi-square distribution. + Notes ----- The probability density function for the noncentral Chi-square @@ -3903,7 +3923,7 @@ cdef class _MKLRandomState: Parameters ---------- - df : int + df : float or array_like of floats Degrees of freedom, should be > 0. size : int or tuple of ints, optional Output shape. If the given shape is, e.g., ``(m, n, k)``, then @@ -4017,9 +4037,9 @@ cdef class _MKLRandomState: Parameters ---------- - mu : float + mu : float or array_like of floats Mode ("center") of the distribution. - kappa : float + kappa : float or array_like of floats Dispersion of the distribution, has to be >=0. size : int or tuple of ints, optional Output shape. If the given shape is, e.g., ``(m, n, k)``, then @@ -4135,13 +4155,18 @@ cdef class _MKLRandomState: Parameters ---------- - shape : float, > 0. - Shape of the distribution. + a : float or array_like of floats + Shape of the distribution. Must be positive. size : int or tuple of ints, optional Output shape. If the given shape is, e.g., ``(m, n, k)``, then ``m * n * k`` samples are drawn. Default is None, in which case a single value is returned. + Returns + ------- + out : ndarray or scalar + Drawn samples from the parameterized Pareto distribution. + See Also -------- scipy.stats.distributions.lomax.pdf : probability density function, @@ -4236,8 +4261,8 @@ cdef class _MKLRandomState: Parameters ---------- - a : float - Shape of the distribution. + a : float or array_like of floats + Shape parameter of the distribution. Must be nonnegative. size : int or tuple of ints, optional Output shape. If the given shape is, e.g., ``(m, n, k)``, then ``m * n * k`` samples are drawn. Default is None, in which case a @@ -4342,7 +4367,7 @@ cdef class _MKLRandomState: Parameters ---------- - a : float + a : float or array_like of floats parameter, > 0 size : int or tuple of ints, optional Output shape. If the given shape is, e.g., ``(m, n, k)``, then @@ -4461,10 +4486,12 @@ cdef class _MKLRandomState: Parameters ---------- - loc : float, optional + loc : float or array_like of floats, optional The position, :math:`\\mu`, of the distribution peak. - scale : float, optional + Default is 0. + scale : float or array_like of floats, optional :math:`\\lambda`, the exponential decay. + Default is 1. Must be non-negative. size : int or tuple of ints, optional Output shape. If the given shape is, e.g., ``(m, n, k)``, then ``m * n * k`` samples are drawn. Default is None, in which case a @@ -4566,10 +4593,11 @@ cdef class _MKLRandomState: Parameters ---------- - loc : float - The location of the mode of the distribution. - scale : float - The scale parameter of the distribution. + loc : float or array_like of floats, optional + The location of the mode of the distribution. Default is 0. + scale : float or array_like of floats, optional + The scale parameter of the distribution. Default is 1. + Must be non-negative. size : int or tuple of ints, optional Output shape. If the given shape is, e.g., ``(m, n, k)``, then ``m * n * k`` samples are drawn. Default is None, in which case a @@ -4705,10 +4733,11 @@ cdef class _MKLRandomState: Parameters ---------- - loc : float - - scale : float > 0. - + loc : float or array_like of floats, optional + Parameter of the distribution. Default is 0. + scale : float or array_like of floats, optional + Parameter of the distribution. Must be non-negative. + Default is 1. size : int or tuple of ints, optional Output shape. If the given shape is, e.g., ``(m, n, k)``, then ``m * n * k`` samples are drawn. Default is None, in which case a @@ -4813,10 +4842,11 @@ cdef class _MKLRandomState: Parameters ---------- - mean : float - Mean value of the underlying normal distribution - sigma : float, > 0. - Standard deviation of the underlying normal distribution + mean : float or array_like of floats, optional + Mean value of the underlying normal distribution. Default is 0. + sigma : float or array_like of floats, optional + Standard deviation of the underlying normal distribution. + Must be non-negative. Default is 1. size : int or tuple of ints, optional Output shape. If the given shape is, e.g., ``(m, n, k)``, then ``m * n * k`` samples are drawn. Default is None, in which case a @@ -4981,13 +5011,18 @@ cdef class _MKLRandomState: Parameters ---------- - scale : scalar + scale : float or array_like of floats, optional Scale, also equals the mode. Should be >= 0. size : int or tuple of ints, optional Output shape. If the given shape is, e.g., ``(m, n, k)``, then ``m * n * k`` samples are drawn. Default is None, in which case a single value is returned. + Returns + ------- + out : ndarray or scalar + Drawn samples from the parameterized Rayleigh distribution. + Notes ----- The probability density function for the Rayleigh distribution is @@ -5066,9 +5101,9 @@ cdef class _MKLRandomState: Parameters ---------- - mean : scalar + mean : float or array_like of floats Distribution mean, should be > 0. - scale : scalar + scale : float or array_like of floats Scale parameter, should be >= 0. size : int or tuple of ints, optional Output shape. If the given shape is, e.g., ``(m, n, k)``, then @@ -5159,12 +5194,12 @@ cdef class _MKLRandomState: Parameters ---------- - left : scalar + left : float or array_like of floats Lower limit. - mode : scalar + mode : float or array_like of floats The value where the peak of the distribution occurs. The value should fulfill the condition ``left <= mode <= right``. - right : scalar + right : float or array_like of floats Upper limit, should be larger than `left`. size : int or tuple of ints, optional Output shape. If the given shape is, e.g., ``(m, n, k)``, then @@ -5276,9 +5311,9 @@ cdef class _MKLRandomState: Parameters ---------- - n : float (but truncated to an integer) + n : int or array_like of ints parameter, >= 0. - p : float + p : float or array_like of floats parameter, >= 0 and <=1. size : int or tuple of ints, optional Output shape. If the given shape is, e.g., ``(m, n, k)``, then @@ -5405,9 +5440,9 @@ cdef class _MKLRandomState: Parameters ---------- - n : int + n : float or array_like of floats Parameter, > 0. - p : float + p : float or array_like of floats Parameter, >= 0 and <=1. size : int or tuple of ints, optional Output shape. If the given shape is, e.g., ``(m, n, k)``, then @@ -5515,7 +5550,7 @@ cdef class _MKLRandomState: Parameters ---------- - lam : float or sequence of float + lam : float or array_like of floats Expectation of interval, should be >= 0. A sequence of expectation intervals must be broadcastable over the requested size. size : int or tuple of ints, optional @@ -5647,8 +5682,8 @@ cdef class _MKLRandomState: Parameters ---------- - a : float > 1 - Distribution parameter. + a : float or array_like of floats + Distribution parameter. Must be greater than 1. size : int or tuple of ints, optional Output shape. If the given shape is, e.g., ``(m, n, k)``, then ``m * n * k`` samples are drawn. Default is None, in which case a @@ -5745,7 +5780,7 @@ cdef class _MKLRandomState: Parameters ---------- - p : float + p : float or array_like of floats The probability of success of an individual trial. size : int or tuple of ints, optional Output shape. If the given shape is, e.g., ``(m, n, k)``, then @@ -5969,10 +6004,9 @@ cdef class _MKLRandomState: Parameters ---------- - loc : float - - scale : float > 0. - + p : float or array_like of floats + Shape parameter for the distribution. Must be in the range + (0, 1). size : int or tuple of ints, optional Output shape. If the given shape is, e.g., ``(m, n, k)``, then ``m * n * k`` samples are drawn. Default is None, in which case a From 835107151ac77fca7087b655edf629fa3fa01942 Mon Sep 17 00:00:00 2001 From: Vladislav Perevezentsev Date: Wed, 26 Aug 2026 05:13:17 -0700 Subject: [PATCH 2/6] Render distribution methods under MKLRandomState in API reference --- docs/source/reference/api.rst | 15 ++++++++++++--- 1 file changed, 12 insertions(+), 3 deletions(-) diff --git a/docs/source/reference/api.rst b/docs/source/reference/api.rst index cf2f0841..faf72625 100644 --- a/docs/source/reference/api.rst +++ b/docs/source/reference/api.rst @@ -1,7 +1,16 @@ .. _fullapi: -Class RandomState -================= +MKL-powered RandomState +======================= -.. autoclass:: mkl_random.RandomState +.. autoclass:: mkl_random.MKLRandomState :members: + :inherited-members: + +.. note:: + + ``mkl_random.RandomState`` is a deprecated alias of + :class:`mkl_random.MKLRandomState`, kept for backward compatibility with + legacy code. A NumPy-compatible drop-in replacement for + :class:`numpy.random.RandomState` is available in + :mod:`mkl_random.interfaces.numpy_random`. From 310392a0a59fd411e3ae663c09caf8af1b4a246d Mon Sep 17 00:00:00 2001 From: Vladislav Perevezentsev Date: Wed, 26 Aug 2026 07:09:25 -0700 Subject: [PATCH 3/6] Use numpydoc to render the API reference --- .github/workflows/build-docs.yml | 2 +- .gitignore | 3 + docs/source/_static/mkl_random-custom.css | 45 +++++++++++ docs/source/conf.py | 10 ++- docs/source/reference/api.rst | 98 ++++++++++++++++++++++- 5 files changed, 153 insertions(+), 5 deletions(-) create mode 100644 docs/source/_static/mkl_random-custom.css diff --git a/.github/workflows/build-docs.yml b/.github/workflows/build-docs.yml index a1e8e0c2..6598b955 100644 --- a/.github/workflows/build-docs.yml +++ b/.github/workflows/build-docs.yml @@ -44,7 +44,7 @@ jobs: if: ${{ !github.event.pull_request || github.event.action != 'closed' }} shell: bash -l {0} run: | - pip install meson-python ninja cython cmake numpy sphinx sphinx_rtd_theme furo pydot graphviz sphinxcontrib-programoutput sphinxcontrib-googleanalytics sphinx_design + pip install meson-python ninja cython cmake numpy sphinx sphinx_rtd_theme furo pydot graphviz sphinxcontrib-programoutput sphinxcontrib-googleanalytics sphinx_design numpydoc - name: Checkout repo uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 with: diff --git a/.gitignore b/.gitignore index d16f217a..ab5d4ebd 100644 --- a/.gitignore +++ b/.gitignore @@ -3,5 +3,8 @@ build/ .mesonpy-* mkl_random.egg-info/ +# Sphinx autosummary generated stub pages +docs/source/reference/generated/ + # Byte-compiled / optimized / DLL files __pycache__/ diff --git a/docs/source/_static/mkl_random-custom.css b/docs/source/_static/mkl_random-custom.css new file mode 100644 index 00000000..602578f8 --- /dev/null +++ b/docs/source/_static/mkl_random-custom.css @@ -0,0 +1,45 @@ +/* mkl_random docs: small Furo overrides for a NumPy-like API look. */ + +/* Keep autosummary tables left-aligned (Furo centres wide ones). */ +.longtable.docutils { + margin-left: 0; + margin-right: auto; +} + +/* Restore body font size in notes (Furo shrinks admonitions). */ +div.admonition { + font-size: inherit !important; +} + +/* Emphasise section headings (Furo renders them small/uppercase, unbold). */ +dd p.rubric, +dl.field-list > dt, +.admonition > .admonition-title { + text-transform: none !important; + font-size: inherit !important; + font-weight: 700 !important; + background-color: var(--color-background-secondary); + padding: 4px 8px; +} + +/* Bold the signature name and parameter names (Furo only colours them). */ +dt.sig.sig-object, +dt.sig.sig-object * { + font-weight: 400 !important; +} +dt.sig.sig-object .sig-name, +dt.sig.sig-object .sig-name *, +dt.sig.sig-object .sig-param > .n, +dt.sig.sig-object .sig-param > .n * { + font-weight: 700 !important; +} + +/* Full grid, roomier padding, zebra rows (Furo borders are faint). */ +body table.docutils td, +body table.docutils th { + border: 1px solid var(--color-foreground-border) !important; + padding: 8px 12px; +} +body table.docutils tbody tr.row-odd { + background-color: var(--color-background-secondary) !important; +} diff --git a/docs/source/conf.py b/docs/source/conf.py index ac55bf4e..0badc7de 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -21,7 +21,7 @@ "sphinx.ext.extlinks", "sphinx.ext.intersphinx", "sphinx.ext.githubpages", - "sphinx.ext.napoleon", + "numpydoc", "sphinx.ext.todo", "sphinx.ext.viewcode", "sphinxcontrib.programoutput", @@ -32,9 +32,17 @@ templates_path = ["_templates"] exclude_patterns = [] +# Generate per-method stub pages for autosummary ":toctree:" tables. +autosummary_generate = True + +# Let api.rst list class members via autosummary +# (avoid numpydoc duplicating them). +numpydoc_show_class_members = False + # -- Options for HTML output ------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output html_theme = "furo" html_static_path = ["_static"] +html_css_files = ["mkl_random-custom.css"] diff --git a/docs/source/reference/api.rst b/docs/source/reference/api.rst index faf72625..225e4cd5 100644 --- a/docs/source/reference/api.rst +++ b/docs/source/reference/api.rst @@ -3,9 +3,9 @@ MKL-powered RandomState ======================= -.. autoclass:: mkl_random.MKLRandomState - :members: - :inherited-members: +.. currentmodule:: mkl_random + +.. autoclass:: MKLRandomState .. note:: @@ -14,3 +14,95 @@ MKL-powered RandomState legacy code. A NumPy-compatible drop-in replacement for :class:`numpy.random.RandomState` is available in :mod:`mkl_random.interfaces.numpy_random`. + +Seeding and state +----------------- + +.. autosummary:: + :toctree: generated/ + :nosignatures: + + ~MKLRandomState.seed + ~MKLRandomState.get_state + ~MKLRandomState.set_state + +Simple random data +------------------ + +.. autosummary:: + :toctree: generated/ + :nosignatures: + + ~MKLRandomState.rand + ~MKLRandomState.randn + ~MKLRandomState.randint + ~MKLRandomState.random_integers + ~MKLRandomState.random_sample + ~MKLRandomState.tomaxint + ~MKLRandomState.choice + ~MKLRandomState.bytes + +Permutations +------------ + +.. autosummary:: + :toctree: generated/ + :nosignatures: + + ~MKLRandomState.shuffle + ~MKLRandomState.permutation + +Distributions +------------- + +.. autosummary:: + :toctree: generated/ + :nosignatures: + + ~MKLRandomState.beta + ~MKLRandomState.binomial + ~MKLRandomState.chisquare + ~MKLRandomState.dirichlet + ~MKLRandomState.exponential + ~MKLRandomState.f + ~MKLRandomState.gamma + ~MKLRandomState.geometric + ~MKLRandomState.gumbel + ~MKLRandomState.hypergeometric + ~MKLRandomState.laplace + ~MKLRandomState.logistic + ~MKLRandomState.lognormal + ~MKLRandomState.logseries + ~MKLRandomState.multinomial + ~MKLRandomState.multivariate_normal + ~MKLRandomState.negative_binomial + ~MKLRandomState.noncentral_chisquare + ~MKLRandomState.noncentral_f + ~MKLRandomState.normal + ~MKLRandomState.pareto + ~MKLRandomState.poisson + ~MKLRandomState.power + ~MKLRandomState.rayleigh + ~MKLRandomState.standard_cauchy + ~MKLRandomState.standard_exponential + ~MKLRandomState.standard_gamma + ~MKLRandomState.standard_normal + ~MKLRandomState.standard_t + ~MKLRandomState.triangular + ~MKLRandomState.uniform + ~MKLRandomState.vonmises + ~MKLRandomState.wald + ~MKLRandomState.weibull + ~MKLRandomState.zipf + +MKL-specific methods +-------------------- + +.. autosummary:: + :toctree: generated/ + :nosignatures: + + ~MKLRandomState.leapfrog + ~MKLRandomState.skipahead + ~MKLRandomState.randint_untyped + ~MKLRandomState.multinormal_cholesky From 2d65eb8c8c5899930297bc7ae660a26c328bd70e Mon Sep 17 00:00:00 2001 From: Vladislav Perevezentsev Date: Wed, 26 Aug 2026 07:54:24 -0700 Subject: [PATCH 4/6] Fix distribution docstring rendering under numpydoc --- docs/source/conf.py | 6 +++ mkl_random/mklrand.pyx | 96 +++++++++++++++++++++--------------------- 2 files changed, 53 insertions(+), 49 deletions(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index 0badc7de..7384ae1f 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -39,6 +39,12 @@ # (avoid numpydoc duplicating them). numpydoc_show_class_members = False +# Shared external link, referenced as `MKL Documentation`_ from docstrings. +rst_epilog = """ +.. _MKL Documentation: + https://www.intel.com/content/www/us/en/developer/tools/oneapi/onemkl.html +""" + # -- Options for HTML output ------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output diff --git a/mkl_random/mklrand.pyx b/mkl_random/mklrand.pyx index 023526aa..dde09ed1 100644 --- a/mkl_random/mklrand.pyx +++ b/mkl_random/mklrand.pyx @@ -1622,21 +1622,21 @@ cdef class _MKLRandomState: seed : int or array_like, optional Seed for `MKLRandomState`. Must be convertible to 32 bit unsigned integers. - brng : {'MT19937', 'SFMT19937', 'MT2203', 'R250', 'WH', 'MCG31', - 'MCG59', 'MRG32K3A', 'PHILOX4X32X10', 'NONDETERM', - 'ARS5', None}, optional - basic pseudo-random number generation algorithms, or - non-deterministic hardware-based generator, provided by Intel MKL. - Use `brng==None` to keep the `brng` specified during construction - of this class instance. + brng : str or None, optional + Name of the basic random number generation algorithm, or a + non-deterministic hardware-based generator, provided by Intel + MKL. One of 'MT19937', 'SFMT19937', 'MT2203', 'R250', 'WH', + 'MCG31', 'MCG59', 'MRG32K3A', 'PHILOX4X32X10', 'NONDETERM', + 'ARS5'. Use ``brng=None`` to keep the algorithm specified when + this instance was constructed. See Also -------- MKLRandomState References - -------- - MKL Documentation: https://www.intel.com/content/www/us/en/developer/tools/oneapi/onemkl.html # no-cython-lint + ---------- + `MKL Documentation`_ """ self._seed_impl(seed, brng) @@ -1656,13 +1656,13 @@ cdef class _MKLRandomState: Returns ------- - out : {tuple(str, bytes), dict} + out : tuple(str, bytes) or dict The returned tuple has the following items: - 1. a string specifying the basic psedo-random number generation + 1. a string specifying the basic pseudo-random number generation algorithm. - 2. a bytes object holding content of Intel MKL's stream for the - given BRNG. + 2. a bytes object holding the content of Intel MKL's stream for + the given BRNG. See Also -------- @@ -1675,8 +1675,8 @@ cdef class _MKLRandomState: altered, the user should know exactly what he/she is doing. References - ----- - MKL Documentation: https://www.intel.com/content/www/us/en/developer/tools/oneapi/onemkl.html # no-cython-lint + ---------- + `MKL Documentation`_ """ cdef int state_buffer_size @@ -1712,13 +1712,13 @@ cdef class _MKLRandomState: Parameters ---------- - state : {tuple(str, bytes), dict} - The `state` tuple has the following items: + state : tuple(str, bytes) or dict + The ``state`` tuple has the following items: - 1. a string specifying the basic psedo-random number generation + 1. a string specifying the basic pseudo-random number generation algorithm. - 2. a bytes object holding content of Intel MKL's stream for the - given BRNG. + 2. a bytes object holding the content of Intel MKL's stream for + the given BRNG. Returns ------- @@ -1742,7 +1742,7 @@ cdef class _MKLRandomState: References ---------- - MKL Documentation: https://www.intel.com/content/www/us/en/developer/tools/oneapi/onemkl.html # no-cython-lint + `MKL Documentation`_ """ cdef char *bytes_ptr @@ -2253,7 +2253,7 @@ cdef class _MKLRandomState: .. versionadded:: 1.7.0 Parameters - ----------- + ---------- a : 1-D array-like or int If an ndarray, a random sample is generated from its elements. If an int, the random sample is generated as if a was np.arange(n) @@ -2269,12 +2269,12 @@ cdef class _MKLRandomState: entries in a. Returns - -------- + ------- samples : 1-D ndarray, shape (size,) The generated random samples Raises - ------- + ------ ValueError If a is an int and less than zero, if a or p are not 1-dimensional, if a is an array-like of size 0, if p is not a vector of @@ -2283,11 +2283,11 @@ cdef class _MKLRandomState: size See Also - --------- + -------- randint, shuffle, permutation Examples - --------- + -------- Generate a uniform random sample from np.arange(5) of size 3: >>> mkl_random.choice(5, 3) @@ -2565,7 +2565,7 @@ cdef class _MKLRandomState: Parameters ---------- d0, d1, ..., dn : int, optional - The dimensions of the returned array, should all be positive. + The dimensions of the returned array, must be non-negative. If no argument is given a single Python float is returned. Returns @@ -2575,7 +2575,7 @@ cdef class _MKLRandomState: See Also -------- - random + random_sample Notes ----- @@ -2616,7 +2616,7 @@ cdef class _MKLRandomState: Parameters ---------- d0, d1, ..., dn : int, optional - The dimensions of the returned array, should be all positive. + The dimensions of the returned array, must be non-negative. If no argument is given a single Python float is returned. Returns @@ -2628,7 +2628,7 @@ cdef class _MKLRandomState: See Also -------- - random.standard_normal : Similar, but takes a tuple as its argument. + standard_normal : Similar, but takes a tuple as its argument. Notes ----- @@ -6131,10 +6131,9 @@ cdef class _MKLRandomState: ------- out : ndarray The drawn samples, of shape *size*, if that was provided. If not, - the shape is ``(N,)``. - - In other words, each entry ``out[i,j,...,:]`` is an N-dimensional - value drawn from the distribution. + the shape is ``(N,)``. In other words, each entry + ``out[i,j,...,:]`` is an N-dimensional value drawn from the + distribution. Notes ----- @@ -6298,10 +6297,9 @@ cdef class _MKLRandomState: ------- out : ndarray The drawn samples, of shape *size*, if that was provided. If not, - the shape is ``(N,)``. - - In other words, each entry ``out[i,j,...,:]`` is an N-dimensional - value drawn from the distribution. + the shape is ``(N,)``. In other words, each entry + ``out[i,j,...,:]`` is an N-dimensional value drawn from the + distribution. Examples -------- @@ -6732,11 +6730,12 @@ cdef class MKLRandomState(_MKLRandomState): If `seed` is ``None``, then `RandomState` will try to read data from ``/dev/urandom`` (or the Windows analogue) if available or seed from the clock otherwise. - brng : {'MT19937', 'SFMT19937', 'MT2203', 'R250', 'WH', 'MCG31', 'MCG59', - 'MRG32K3A', 'PHILOX4X32X10', 'NONDETERM', 'ARS5'}, optional - basic pseudo-random number generation algorithms, or non-deterministic - hardware-based generator, provided by Intel MKL. The default choice is - 'MT19937' - the Mersenne Twister generator. + brng : str, optional + Name of the basic random number generation algorithm, or a + non-deterministic hardware-based generator, provided by Intel MKL. + One of 'MT19937', 'SFMT19937', 'MT2203', 'R250', 'WH', 'MCG31', + 'MCG59', 'MRG32K3A', 'PHILOX4X32X10', 'NONDETERM', 'ARS5'. The + default is 'MT19937', the Mersenne Twister generator. Notes ----- @@ -6747,8 +6746,8 @@ cdef class MKLRandomState(_MKLRandomState): of probability distributions to choose from. References - ----- - MKL Documentation: https://www.intel.com/content/www/us/en/developer/tools/oneapi/onemkl.html # no-cython-lint + ---------- + `MKL Documentation`_ """ @@ -6937,10 +6936,9 @@ cdef class MKLRandomState(_MKLRandomState): ------- out : ndarray The drawn samples, of shape *size*, if that was provided. If not, - the shape is ``(N,)``. - - In other words, each entry ``out[i,j,...,:]`` is an N-dimensional - value drawn from the distribution. + the shape is ``(N,)``. In other words, each entry + ``out[i,j,...,:]`` is an N-dimensional value drawn from the + distribution. Notes ----- From 110bf7231e2878c9d07ac1354d353eaa8b3e1905 Mon Sep 17 00:00:00 2001 From: Vladislav Perevezentsev Date: Wed, 26 Aug 2026 11:17:51 -0700 Subject: [PATCH 5/6] Add gh-165 to changelog --- CHANGELOG.md | 1 + 1 file changed, 1 insertion(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index eff67b71..4b10d069 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,6 +9,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Added ### Changed +* Documented `MKLRandomState` and its methods in the API reference, aligning the docstrings with NumPy [gh-165](https://github.com/IntelPython/mkl_random/pull/165) ### Fixed From 52ea3c9918222cd3078bfa6366f42713520bac3d Mon Sep 17 00:00:00 2001 From: Vladislav Perevezentsev Date: Thu, 27 Aug 2026 02:27:12 -0700 Subject: [PATCH 6/6] Temporary publish rendered docs to this PR --- .github/workflows/build-docs.yml | 31 +++++++++++++++++++++++++++++++ 1 file changed, 31 insertions(+) diff --git a/.github/workflows/build-docs.yml b/.github/workflows/build-docs.yml index 6598b955..88fb313a 100644 --- a/.github/workflows/build-docs.yml +++ b/.github/workflows/build-docs.yml @@ -68,6 +68,37 @@ jobs: with: name: ${{ env.PACKAGE_NAME }} rendered documentation path: ~/rendered_docs + # TEMPORARY: publish this PR's docs to gh-pages and comment the link. + # Remove after review. + - name: Publish pull-request docs + if: ${{ github.event.pull_request && github.event.action != 'closed' }} + env: + PR_NUM: ${{ github.event.number }} + shell: bash -l {0} + run: | + git remote add tokened_docs https://IntelPython:${{ secrets.GITHUB_TOKEN }}@github.com/IntelPython/mkl_random.git + git fetch tokened_docs + git checkout --track tokened_docs/gh-pages + [ -d "pull/${PR_NUM}" ] && git rm -rf "pull/${PR_NUM}" + mkdir -p "pull/${PR_NUM}" + cd "pull/${PR_NUM}" + mv ~/rendered_docs/* . + git add . + git config --global user.name 'github-actions[doc-deploy-bot]' + git config --global user.email 'github-actions[doc-deploy-bot]@users.noreply.github.com' + git commit -m "Docs for pull request ${PR_NUM}" + git push tokened_docs gh-pages + - name: Comment with URL to published pull-request docs + if: ${{ github.event.pull_request && github.event.action != 'closed' }} + env: + PR_NUM: ${{ github.event.number }} + uses: mshick/add-pr-comment@ec328af66588ab8f77cdeb2c264f14aba45bbf59 # v2 + with: + message-id: url_to_docs + allow-repeats: false + message: | + View rendered docs @ https://intelpython.github.io/mkl_random/pull/${{ env.PR_NUM }}/index.html + repo-token: ${{ secrets.GITHUB_TOKEN }} - name: Configure git if: ${{ !github.event.pull_request && github.event.action != 'closed'}} run: |