Document MKLRandomState in the API reference and align docstrings with NumPy

.github/workflows/build-docs.yml

@@ -45,7 +45,7 @@
         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:
@@ -69,6 +69,37 @@
         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: |

.gitignore

@@ -6,6 +6,9 @@ mkl_random.egg-info/
 # Cython-generated sources
 mkl_random/mklrand.cpp
 
+# Sphinx autosummary generated stub pages
+docs/source/reference/generated/
+
 # Byte-compiled / optimized / DLL files
 __pycache__/
 

CHANGELOG.md

@@ -28,6 +28,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 * Updated the `randint_untyped` implementation, which now supports `array_like` (broadcastable) `low`/`high` bounds [gh-176](https://github.com/IntelPython/mkl_random/pull/176)
 * Sped up `randint` with `array_like` bounds by generating words in cache-sized chunks and by picking the Lemire rejection test by range width [gh-173](https://github.com/IntelPython/mkl_random/pull/173)
 * Reduced the memory use and sped up integer generation with `WH`, `MCG31`, `R250` and `MRG32K3A`, which lack `viRngUniformBits` support [gh-178](https://github.com/IntelPython/mkl_random/pull/178)
+* 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
 * Fixed `multinormal_cholesky` and the other functions taking `method` routing integer-like ids such as `np.int64(0)`, `np.int64(2)` or `False` to `BoxMuller`; NumPy integers now select the method they name [gh-189](https://github.com/IntelPython/mkl_random/pull/189)

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;
+}

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,29 @@
 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
+
+# Resolve `numpy`/`scipy` cross-references in docstrings and guides.
+intersphinx_mapping = {
+    "numpy": ("https://numpy.org/doc/stable/", None),
+    "scipy": ("https://docs.scipy.org/doc/scipy/", None),
+}
+
+# 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
 
 html_theme = "furo"
 html_static_path = ["_static"]
+html_css_files = ["mkl_random-custom.css"]

docs/source/reference/api.rst

@@ -1,7 +1,108 @@
 .. _fullapi:
 
-Class RandomState
-=================
+MKL-powered RandomState
+=======================
 
-.. autoclass:: mkl_random.RandomState
-    :members:
+.. currentmodule:: mkl_random
+
+.. autoclass:: MKLRandomState
+
+.. note::
+
+   ``mkl_random.RandomState`` is a deprecated subclass 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`.
+
+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

docs/source/tutorials.rst

@@ -39,7 +39,7 @@ The :mod:`mkl_random` is also distributed as part of `Intel® Distribution for P
 First steps
 -----------
 
-The :mod:`mkl_random` package has followed the design of :class:`numpy.random` package to
+The :mod:`mkl_random` package has followed the design of :mod:`numpy.random` package to
 make :mod:`mkl_random` easy to use for those already familiar with the :mod:`numpy.random` module.
 
 .. note::