Restructure documentation (#838)

* Save changes to doc structure

* Restructure docs

* Fix links

* Fix links

* Update doc build instructions

* Update doc/build-doc.sh

Co-authored-by: Nikolay Petrov <[email protected]>

* Update requirements for doc build

* Update doc/sources/usage.rst

* Add patching options

* Add note about interchangebility

* Update doc/sources/conf.py

Co-authored-by: Nikolay Petrov <[email protected]>

* Fix pep

* Update gpu support table

Co-authored-by: Nikolay Petrov <[email protected]>

Author: outoftardis

.gitignore

@@ -10,6 +10,7 @@ daal4py.egg-info
 *.dll
 **/.ipynb_checkpoints
 doc/_build
+doc/sources/samples/*.ipynb
 
 # Cython generated code
 src/oneapi/oneapi_api.h

INSTALL.md

@@ -117,14 +117,16 @@ to create a Python package that can be easily managed by the package manager on
 ## Build documentation for Intel(R) Extension for Scikit-learn
 ### Prerequisites for creating documentation
 
-See [requirements-doc.txt](requirements-doc.txt).
+- [requirements-doc.txt](requirements-doc.txt)
+- [pandoc](https://pandoc.org/installing.html)
 
 ### Build documentation
 
 Run:
 
 ```
-cd doc && make html
+cd doc
+./build-doc.sh
 ```
 
 The documentation will be in ```doc/_build/html```.

README.md

@@ -48,7 +48,7 @@ One of the ways to patch scikit-learn is by modifying the code. You import an ad
         clustering = DBSCAN(eps=3, min_samples=2).fit(X)
     ```
 
-👀 Read about [other ways to patch scikit-learn](https://intel.github.io/scikit-learn-intelex/index.html#usage) and [other methods for offloading to GPU devices](https://intel.github.io/scikit-learn-intelex/oneapi_gpu.html).
+👀 Read about [other ways to patch scikit-learn](https://intel.github.io/scikit-learn-intelex/index.html#usage) and [other methods for offloading to GPU devices](https://intel.github.io/scikit-learn-intelex/oneapi-gpu.html).
 Check out available [notebooks](https://github.com/intel/scikit-learn-intelex/tree/master/examples/notebooks) for more examples.
 
 This software acceleration is achieved through the use of vector instructions, IA hardware-specific memory optimizations, threading, and optimizations for all upcoming Intel platforms at launch time.
@@ -70,7 +70,7 @@ Configurations:
 
 ## 🛠 Installation
 
-[System Requirements](https://intel.github.io/scikit-learn-intelex/system_requirements.html)   |    [Install via pip or conda](https://github.com/intel/scikit-learn-intelex/blob/master/INSTALL.md)   |   [Build from sources](INSTALL.md#build-from-sources)
+[System Requirements](https://intel.github.io/scikit-learn-intelex/system-requirements.html)   |    [Install via pip or conda](https://github.com/intel/scikit-learn-intelex/blob/master/INSTALL.md)   |   [Build from sources](INSTALL.md#build-from-sources)
 
 Intel(R) Extension for Scikit-learn is available at the [Python Package Index](https://pypi.org/project/scikit-learn-intelex/),
 on Anaconda Cloud in [Conda-Forge channel](https://anaconda.org/conda-forge/scikit-learn-intelex) and in [Intel channel](https://anaconda.org/intel/scikit-learn-intelex). You can also build the extension from [sources](INSTALL.md#build-from-sources).

doc/build-doc.sh

@@ -0,0 +1,9 @@
+#!/bin/bash
+
+# copy jupyter notebooks
+cd ..
+cp examples/notebooks/*.ipynb doc/sources/samples
+
+# build the documentation
+cd doc
+make html

doc/sources/acceleration.rst

@@ -0,0 +1,38 @@
+.. ******************************************************************************
+.. * Copyright 2021 Intel Corporation
+.. *
+.. * Licensed under the Apache License, Version 2.0 (the "License");
+.. * you may not use this file except in compliance with the License.
+.. * You may obtain a copy of the License at
+.. *
+.. *     http://www.apache.org/licenses/LICENSE-2.0
+.. *
+.. * Unless required by applicable law or agreed to in writing, software
+.. * distributed under the License is distributed on an "AS IS" BASIS,
+.. * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+.. * See the License for the specific language governing permissions and
+.. * limitations under the License.
+.. *******************************************************************************/
+
+##############
+Acceleration
+##############
+
+The software acceleration provided by |intelex| is achieved through the use of vector instructions,
+IA hardware-specific memory optimizations, threading, and optimizations for all upcoming Intel platforms at launch time.
+
+|intelex| dynamically patches scikit-learn estimators to use Intel(R) oneAPI Data Analytics Library
+as the underlying solver, while getting the same solution faster.
+
+|intelex| depends on daal4py. You can learn more in `daal4py documentation <https://intelpython.github.io/daal4py>`_.
+
+Speedup over original Scikit-learn
+----------------------------------
+
+.. image:: _static/scikit-learn-acceleration-2021.2.3.PNG
+  :width: 800
+
+Configurations:
+
+- HW: c5.24xlarge AWS EC2 Instance using an Intel Xeon Platinum 8275CL with 2 sockets and 24 cores per socket
+- SW: scikit-learn version 0.24.2, scikit-learn-intelex version 2021.2.3, Python 3.8

doc/sources/algorithms.rst

@@ -14,14 +14,16 @@
 .. * limitations under the License.
 .. *******************************************************************************/
 
+.. _sklearn_algorithms:
+
 ####################
-Supported algorithms
+Supported Algorithms
 ####################
 
-.. _sklearn_algorithms:
+Applying |intelex| will impact the following scikit-learn algorithms:
 
-Applying Intel(R) Extension for Scikit-learn will impact the following existing scikit-learn
-algorithms:
+on CPU
+------
 
 .. list-table::
    :widths: 10 10 30 15
@@ -121,10 +123,67 @@ algorithms:
      - Parameters ``average``, ``sample_weight``, ``max_fpr`` and ``multi_class`` are not supported.
      - No limitations.
 
+on GPU
+------
+
+.. list-table::
+   :widths: 10 10 30 15
+   :header-rows: 1
+   :align: left
+
+   * - Task
+     - Functionality
+     - Parameters support
+     - Data support
+   * - Classification
+     - SVC
+     - All parameters except ``kernel`` = 'sigmoid_poly', ``class_weight`` != None.
+     - Only binary dense data is supported.
+   * - Classification
+     - RandomForestClassifier
+     - All parameters except ``warm_start`` = True, ``cpp_alpha`` != 0, ``criterion`` != 'gini', ``oob_score`` = True.
+     - Multi-output, sparse data, out-of-bag score and sample_weight are not supported.
+   * - Classification
+     - KNeighborsClassifier
+     - All parameters except ``algorithm`` != 'brute', ``weights`` = 'callable'
+     - Only dense data is supported.
+   * - Classification
+     - LogisticRegression
+     - All parameters except ``solver`` != 'newton-cg', ``class_weight`` != None, ``sample_weight`` != None, ``penalty`` != 'l2'
+     - Only dense data is supported.
+   * - Regression
+     - RandomForestRegressor
+     - All parameters except ``warm_start`` = True, ``cpp_alpha`` != 0, ``criterion`` != 'mse', ``oob_score`` = True.
+     - Multi-output, sparse data, out-of-bag score and sample_weight are not supported.
+   * - Regression
+     - KNeighborsRegressor
+     - All parameters except ``algorithm`` != 'brute', ``weights`` = 'callable'
+     - Only dense data is supported.
+   * - Regression
+     - LinearRegression
+     - All parameters except ``normalize`` != False and ``sample_weight`` != None.
+     - Only dense data is supported, #observations should be >= #features.
+   * - Clustering
+     - KMeans
+     - All parameters except ``precompute_distances`` and ``sample_weight`` != None. Init = 'k-means++' fallbacks to CPU.
+     - Sparse data is not supported.
+   * - Clustering
+     - DBSCAN
+     - All parameters except ``metric`` != 'euclidean', ``algorithm`` != 'brute', ``algorithm`` != 'auto'.
+     - Only dense data is supported.
+   * - Dimensionality reduction
+     - PCA
+     - All parameters except ``svd_solver`` != 'full'.
+     - Sparse data is not supported.
+
+.. seealso:: :ref:`oneapi_gpu`
+
+Scikit-learn tests
+------------------
 
 Monkey-patched scikit-learn classes and functions passes scikit-learn's own test
 suite, with few exceptions, specified in `deselected_tests.yaml
 <https://github.com/intel/scikit-learn-intelex/blob/master/deselected_tests.yaml>`__.
 
-The results of the entire latest scikit-learn test suite with Intel(R) Extension for Scikit-learn: `CircleCI
-<https://circleci.com/gh/intel/scikit-learn-intelex>`_.
+The results of the entire latest scikit-learn test suite with |intelex|: `CircleCI
+<https://circleci.com/gh/intel/scikit-learn-intelex>`_.

doc/sources/blogs.rst

@@ -0,0 +1,34 @@
+.. ******************************************************************************
+.. * Copyright 2021 Intel Corporation
+.. *
+.. * Licensed under the Apache License, Version 2.0 (the "License");
+.. * you may not use this file except in compliance with the License.
+.. * You may obtain a copy of the License at
+.. *
+.. *     http://www.apache.org/licenses/LICENSE-2.0
+.. *
+.. * Unless required by applicable law or agreed to in writing, software
+.. * distributed under the License is distributed on an "AS IS" BASIS,
+.. * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+.. * See the License for the specific language governing permissions and
+.. * limitations under the License.
+.. *******************************************************************************/
+
+.. _blogs:
+
+Follow us on Medium
+--------------------
+We publish blogs on Medium, so `follow us <https://medium.com/intel-analytics-software/tagged/machine-learning>`_
+to learn tips and tricks for more efficient data analysis the help of |intelex|.
+Here are our latest blogs:
+
+- `Save Time and Money with Intel Extension for Scikit-learn <https://medium.com/intel-analytics-software/save-time-and-money-with-intel-extension-for-scikit-learn-33627425ae4>`_,
+- `Superior Machine Learning Performance on the Latest Intel Xeon Scalable Processors <https://medium.com/intel-analytics-software/superior-machine-learning-performance-on-the-latest-intel-xeon-scalable-processor-efdec279f5a3>`_,
+- `Leverage Intel Optimizations in Scikit-Learn <https://medium.com/intel-analytics-software/leverage-intel-optimizations-in-scikit-learn-f562cb9d5544>`_,
+- `Intel Gives Scikit-Learn the Performance Boost Data Scientists Need <https://medium.com/intel-analytics-software/intel-gives-scikit-learn-the-performance-boost-data-scientists-need-42eb47c80b18>`_,
+- `From Hours to Minutes: 600x Faster SVM <https://medium.com/intel-analytics-software/from-hours-to-minutes-600x-faster-svm-647f904c31ae>`_,
+- `Improve the Performance of XGBoost and LightGBM Inference <https://medium.com/intel-analytics-software/improving-the-performance-of-xgboost-and-lightgbm-inference-3b542c03447e>`_,
+- `Accelerate Kaggle Challenges Using Intel AI Analytics Toolkit <https://medium.com/intel-analytics-software/accelerate-kaggle-challenges-using-intel-ai-analytics-toolkit-beb148f66d5a>`_,
+- `Accelerate Your scikit-learn Applications <https://medium.com/intel-analytics-software/improving-the-performance-of-xgboost-and-lightgbm-inference-3b542c03447e>`_,
+- `Accelerate Linear Models for Machine Learning <https://medium.com/intel-analytics-software/accelerating-linear-models-for-machine-learning-5a75ff50a0fe>`_,
+- `Accelerate K-Means Clustering <https://medium.com/intel-analytics-software/accelerate-k-means-clustering-6385088788a1>`_.

doc/sources/conf.py

@@ -61,6 +61,7 @@
     'sphinx.ext.viewcode',
     'sphinx.ext.githubpages',
     'sphinx.ext.autodoc',
+    'nbsphinx'
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -73,7 +74,7 @@
 source_suffix = '.rst'
 
 # The master toctree document.
-master_doc = 'contents'
+master_doc = 'index'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -85,11 +86,18 @@
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This pattern also affects html_static_path and html_extra_path .
-exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', 'usage.rst', 'patching/*']
 
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = 'sphinx'
 
+# substitutions
+
+rst_prolog = """
+.. |reg| unicode:: U+000AE
+.. |intelex| replace:: Intel\\ |reg|\\  Extension for Scikit-learn*
+"""
+
 # -- Options for HTML output -------------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for

doc/sources/global_patching.rst renamed to doc/sources/global-patching.rst

@@ -17,28 +17,37 @@
 .. _global_patching:
 
 ###############
-Global patching
+Global Patching
 ###############
 
 Use global patching to patch all your scikit-learn applications without any additional actions.
 
-**Prerequisites for global patching**:
+.. rubric:: Prerequisites
 
-- Intel(R) Extension for Scikit-learn
+- |intelex|
 - Scikit-learn
+- read and write permissions to Scikit-learn files
 
-.. note::
-    For global patching to work, you need read and write permissions to Scikit-learn files.
+Patch all supported algorithms
+===============================
 
 To patch all :ref:`supported algorithms <sklearn_algorithms>`, run::
 
     python sklearnex.glob patch_sklearn
 
+Patch selected algorithms
+=========================
+
 If you want to patch only some algorithms, use ``--algorithm`` or ``-a`` keys
-with a list of algorithms to patch. For example, to patch only SVC and RandomForestClassifier estimators, run::
+with a list of algorithms to patch.
+
+For example, to patch only SVC and RandomForestClassifier estimators, run::
 
     python sklearnex.glob patch_sklearn -a svc random_forest_classifier
 
+Disable patching notifications
+==============================
+
 If you do not want to receive patching notifications, then use ``--no-verbose`` or ``-nv`` keys::
 
     python sklearnex.glob patch_sklearn -a svc random_forest_classifier -nv
@@ -47,10 +56,16 @@ If you do not want to receive patching notifications, then use ``--no-verbose``
     If you run the global patching command several times with different parameters,
     then only the last configuration will be applied.
 
+Disable global patching
+=======================
+
 To disable global patching, use the following command::
 
     python sklearnex.glob unpatch_sklearn
 
+Enable global patching via code
+===============================
+
 You can also enable global patching in your code. To do this,
 use the ``patch_sklearn`` function with the ``global_patch`` argument::
 
@@ -61,6 +76,9 @@ use the ``patch_sklearn`` function with the ``global_patch`` argument::
 After that, Scikit-learn patches will be enabled in the current application and
 in all others that use the same environment.
 
+Disable global patching via code
+================================
+
 To disable global patching via code, use the ``global_patch``
 argument in the ``unpatch_sklearn`` function::