Skip to content

Commit 5e2fd3b

Browse files
oleksandr-pavlykoleksandr-pavlyk
authored
Merge pull request #35 from IntelPython/add-docs
Add docs
2 parents 0ac1d09 + ce22247 commit 5e2fd3b

22 files changed

+881
-0
lines changed

‎.github/workflows/build-docs.yml‎

Lines changed: 93 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,93 @@
1+
name: Build mkl_random documentation
2+
on:
3+
pull_request:
4+
push:
5+
branches: [master]
6+
7+
permissions: read-all
8+
9+
jobs:
10+
build-and-deploy:
11+
name: Build and Deploy Documentation
12+
runs-on: ubuntu-latest
13+
permissions:
14+
contents: write
15+
pull-requests: write
16+
steps:
17+
- name: Cancel Previous Runs
18+
uses: styfle/[email protected]
19+
with:
20+
access_token: ${{ github.token }}
21+
- name: Add Intel repository
22+
if: ${{ !github.event.pull_request || github.event.action != 'closed' }}
23+
run: |
24+
wget https://apt.repos.intel.com/intel-gpg-keys/GPG-PUB-KEY-INTEL-SW-PRODUCTS-2023.PUB
25+
sudo apt-key add GPG-PUB-KEY-INTEL-SW-PRODUCTS-2023.PUB
26+
rm GPG-PUB-KEY-INTEL-SW-PRODUCTS-2023.PUB
27+
sudo add-apt-repository "deb https://apt.repos.intel.com/oneapi all main"
28+
sudo apt-get update
29+
- name: Install Intel OneAPI
30+
if: ${{ !github.event.pull_request || github.event.action != 'closed' }}
31+
run: |
32+
sudo apt-get install intel-oneapi-compiler-dpcpp-cpp intel-oneapi-mkl-devel
33+
- name: Setup Python
34+
if: ${{ !github.event.pull_request || github.event.action != 'closed' }}
35+
uses: actions/setup-python@v5
36+
with:
37+
python-version: '3.11'
38+
architecture: x64
39+
- name: Install sphinx dependencies
40+
if: ${{ !github.event.pull_request || github.event.action != 'closed' }}
41+
shell: bash -l {0}
42+
run: |
43+
pip install numpy cython setuptools scikit-build cmake sphinx sphinx_rtd_theme furo pydot graphviz sphinxcontrib-programoutput sphinxcontrib-googleanalytics sphinx_design
44+
- name: Checkout repo
45+
uses: actions/[email protected]
46+
with:
47+
fetch-depth: 0
48+
persist-credentials: false
49+
- name: Build mkl_random+docs
50+
if: ${{ !github.event.pull_request || github.event.action != 'closed' }}
51+
shell: bash -l {0}
52+
run: |
53+
# Ensure that SYCL libraries are on LD_LIBRARY_PATH
54+
source /opt/intel/oneapi/setvars.sh
55+
python setup.py develop
56+
python -c "import mkl_random; print(mkl_random.__version__)" || exit 1
57+
sphinx-build -M html docs/source docs/build
58+
mkdir -p ~/rendered_docs
59+
cp -r docs/build/html/* ~/rendered_docs/
60+
git clean -dfx
61+
- name: Save built docs as an artifact
62+
if: ${{ github.event.pull_request && github.event.action != 'closed'}}
63+
uses: actions/upload-artifact@v4
64+
with:
65+
name: ${{ env.PACKAGE_NAME }} rendered documentation
66+
path: ~/rendered_docs
67+
- name: Configure git
68+
if: ${{ !github.event.pull_request && github.event.action != 'closed'}}
69+
run: |
70+
git config --local user.email "[email protected]"
71+
git config --local user.name "mkl_random-doc-bot"
72+
timeout-minutes: 5
73+
- name: Checkout gh-pages
74+
if: ${{ !github.event.pull_request && github.event.action != 'closed'}}
75+
run: |
76+
git fetch --all
77+
git checkout gh-pages
78+
- name: 'Copy build to root'
79+
if: ${{ !github.event.pull_request && github.event.action != 'closed'}}
80+
run: |
81+
cp -R ~/rendered_docs/* .
82+
timeout-minutes: 10
83+
- name: 'Commit changes'
84+
if: ${{ !github.event.pull_request && github.event.action != 'closed'}}
85+
run: |
86+
git add . && git commit -m "Deploy: ${{ github.sha }}"
87+
continue-on-error: true
88+
timeout-minutes: 10
89+
- name: Publish changes
90+
if: ${{ success() && !github.event.pull_request && github.event.action != 'closed'}}
91+
run: |
92+
git push origin gh-pages
93+
timeout-minutes: 10

‎.gitignore‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
*~
2+
build/
3+
mkl_random/__pycache__/
4+
mkl_random/tests/__pycache__/
5+
mkl_random/mklrand.cpp
6+
mkl_random/mklrand.cpython*.so
7+
mkl_random.egg-info/

‎docs/Makefile‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
# Minimal makefile for Sphinx documentation
2+
#
3+
4+
# You can set these variables from the command line, and also
5+
# from the environment for the first two.
6+
SPHINXOPTS ?=
7+
SPHINXBUILD ?= sphinx-build
8+
SOURCEDIR = source
9+
BUILDDIR = build
10+
11+
# Put it first so that "make" without argument is like "make help".
12+
help:
13+
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
14+
15+
.PHONY: help Makefile
16+
17+
# Catch-all target: route all unknown targets to Sphinx using the new
18+
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
19+
%: Makefile
20+
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

‎docs/make.bat‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
@ECHO OFF
2+
3+
pushd %~dp0
4+
5+
REM Command file for Sphinx documentation
6+
7+
if "%SPHINXBUILD%" == "" (
8+
set SPHINXBUILD=sphinx-build
9+
)
10+
set SOURCEDIR=source
11+
set BUILDDIR=build
12+
13+
%SPHINXBUILD% >NUL 2>NUL
14+
if errorlevel 9009 (
15+
echo.
16+
echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
17+
echo.installed, then set the SPHINXBUILD environment variable to point
18+
echo.to the full path of the 'sphinx-build' executable. Alternatively you
19+
echo.may add the Sphinx directory to PATH.
20+
echo.
21+
echo.If you don't have Sphinx installed, grab it from
22+
echo.https://www.sphinx-doc.org/
23+
exit /b 1
24+
)
25+
26+
if "%1" == "" goto help
27+
28+
%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
29+
goto end
30+
31+
:help
32+
%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
33+
34+
:end
35+
popd

‎docs/source/conf.py‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
# Configuration file for the Sphinx documentation builder.
2+
#
3+
# For the full list of built-in configuration values, see the documentation:
4+
# https://www.sphinx-doc.org/en/master/usage/configuration.html
5+
6+
# -- Project information -----------------------------------------------------
7+
# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
8+
9+
project = 'mkl_random'
10+
copyright = '2017-2024, Intel Corp.'
11+
author = 'Intel Corp.'
12+
release = '1.2.5'
13+
14+
# -- General configuration ---------------------------------------------------
15+
# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
16+
17+
extensions = [
18+
"sphinx.ext.autodoc",
19+
"sphinx.ext.autosummary",
20+
"sphinx.ext.coverage",
21+
"sphinx.ext.extlinks",
22+
"sphinx.ext.intersphinx",
23+
"sphinx.ext.githubpages",
24+
"sphinx.ext.napoleon",
25+
"sphinx.ext.todo",
26+
"sphinx.ext.viewcode",
27+
"sphinxcontrib.programoutput",
28+
# "sphinxcontrib.googleanalytics",
29+
'sphinx_design',
30+
]
31+
32+
templates_path = ['_templates']
33+
exclude_patterns = []
34+
35+
36+
37+
# -- Options for HTML output -------------------------------------------------
38+
# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
39+
40+
html_theme = 'furo'
41+
html_static_path = ['_static']

‎docs/source/how_to.rst‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
How-to Guides
2+
=============
3+
4+
To be written.

‎docs/source/index.rst‎

Lines changed: 73 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,73 @@
1+
Random sampling powered by Intel(R) Math Kernel Library
2+
=======================================================
3+
4+
:mod:`mkl_random` is Python package exposing pseudo-random and non-deterministic random
5+
number generators with continuous and discrete distribution available in
6+
Intel(R) Math Kernel Library (MKL).
7+
8+
.. grid:: 2
9+
:gutter: 3
10+
11+
.. grid-item-card:: Beginner Guides
12+
13+
New to :mod:`mkl_random`? Check out the Tutorials.
14+
They are a hands-on introduction for beginners.
15+
16+
+++
17+
18+
.. button-ref:: tutorials
19+
:expand:
20+
:color: secondary
21+
:click-parent:
22+
23+
To the beginner guides
24+
25+
.. grid-item-card:: User Guides
26+
27+
The user guides are recipes for key tasks and common problems.
28+
29+
+++
30+
31+
.. button-ref:: how_to
32+
:expand:
33+
:color: secondary
34+
:click-parent:
35+
36+
To the user guides
37+
38+
.. grid-item-card:: Reference Guide
39+
40+
The reference guide contains a detailed description of class :class:`mkl_random.RandomState` and its methods.
41+
42+
+++
43+
44+
.. button-ref:: reference/index
45+
:expand:
46+
:color: secondary
47+
:click-parent:
48+
49+
To the reference guide
50+
51+
.. grid-item-card:: Contributor Guides
52+
53+
Want to add to the codebase?
54+
The contributing guidelines will guide you through the
55+
process of improving :mod:`mkl_random`.
56+
57+
+++
58+
59+
.. button-ref:: maintenance/index
60+
:expand:
61+
:color: secondary
62+
:click-parent:
63+
64+
To the contributor guides
65+
66+
67+
.. toctree::
68+
:hidden:
69+
70+
tutorials
71+
how_to
72+
reference/index
73+
maintenance/index

‎docs/source/maintenance/index.rst‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
Contributing
2+
============
3+
4+
:mod:`mkl_random` is an free and open source project.
5+
We welcome and appreciate your contributions.
6+
7+
To contribute, fork the repo https://github.com/IntelPython/mkl_random.git,
8+
clone it:
9+
10+
.. code-block::
11+
:caption: How to clone the repo
12+
13+
git clone https://github.com/<fork-org>/mkl_random.git
14+
15+
16+
A working compiler is needed build :mod:`mkl_random`.
17+
Both Gnu :code:`g++` and Intel LLVM :code:`icpx` are supported.
18+
19+
Make sure to install Python packages required to build :mod:`mkl_random`:
20+
21+
* :mod:`python`
22+
* :mod:`numpy`
23+
* :mod:`cython`
24+
* :mod:`setuptools`
25+
26+
You would also need Intel(R) MKL library and its headers. Set :code:`MKLROOT` environment
27+
variable so that :code:`${MKLROOT}/include/mkl.h` and :code:`${MKLROOT}/lib/libmkl_rt.so`
28+
can be found.
29+
30+
.. code-block:: bash
31+
:caption: Building mkl_random
32+
33+
$ export MKLROOT=</path/to/mkl>
34+
python setup.py develop
35+
36+
To run test suite, install :mod:`pytest`, and run
37+
38+
.. code-block:: bash
39+
:caption: Running mkl_random test suite
40+
41+
python -m pytest mkl_random/tests
42+
43+
To build documentation, install dependencies and running
44+
45+
.. code-block:: bash
46+
:caption: Building mkl_random documentation
47+
48+
$ sphinx-build -M html docs/source docs/build
49+
50+
Rendered documentation can be found in "docs/build/html".

‎docs/source/reference/api.rst‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
.. _fullapi:
2+
3+
Class RandomState
4+
=================
5+
6+
.. autoclass:: mkl_random.RandomState
7+
:members:

‎docs/source/reference/ars5.rst‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
ARS5 brng
2+
=========
3+
4+
The ARS5 counter-based pseudorandom number generator based on AES encryption algorithm can be
5+
initialized with either an integral seed, a list of integral seeds, or automatically.
6+
7+
.. code-block:: python
8+
:caption: Construction for ARS5 basic random number generator with scalar seed
9+
10+
import mkl_random
11+
rs = mkl_random.RandomState(1234, brng="ars5")
12+
13+
# Use random state instance to generate 1000 random numbers from
14+
# Uniform(0, 1) distribution
15+
esample = rs.uniform(0, 1, size=1000)
16+
17+
.. code-block:: python
18+
:caption: Construction for ARS5 basic random number generator with vector seed
19+
20+
import mkl_random
21+
rs_vec = mkl_random.RandomState([1234, 567, 89, 0], brng="ars5")
22+
23+
# Use random state instance to generate 1000 random numbers from
24+
# Gamma(3, 1) distibution
25+
gsample = rs_vec.gamma(3, 1, size=1000)
26+
27+
When seed is not specified, the generator is initialized using system clock, e.g.:
28+
29+
.. code-block:: python
30+
:caption: Construction for ARS5 basic random number generator automatic seed
31+
32+
import mkl_random
33+
rs_def = mkl_random.RandomState(brng="ars5")
34+
35+
# Use random state instance to generate 1000 random numbers
36+
# from discrete uniform distribution [1, 6]
37+
isample = rs_def.randint(1, 6 + 1, size=1000)

0 commit comments

Comments
 (0)