Refresh documentation (#1485)

* Updated Overview page

* Added Quick Start Guide

* Updated developement guides

* Applied review comments

* Added examples

* Keeping existing docs instead of full clean-up

Author: antonwolfy

.github/workflows/build-sphinx.yml

@@ -4,17 +4,21 @@ on:
     branches:
       - master
   pull_request:
+    types: [opened, synchronize, reopened, closed]
+
+env:
+  PUBLISH_DIR: doc/_build/html/
+
+defaults:
+  run:
+    shell: bash -l {0}
 
 jobs:
   build-and-deploy:
     name: Build and Deploy Docs
 
     runs-on: ubuntu-20.04
 
-    defaults:
-      run:
-        shell: bash -l {0}
-
     env:
       python-ver: '3.9'
       CHANNELS: '-c dppy/label/dev -c intel -c conda-forge --override-channels'
@@ -116,4 +120,65 @@ jobs:
         uses: peaceiris/actions-gh-pages@v3.9.3
         with:
           github_token: ${{ secrets.GITHUB_TOKEN }}
-          publish_dir: doc/_build/html/
+          publish_dir: ${{ env.PUBLISH_DIR }}
+
+      - name: Publish pull-request docs
+        if: |
+          !github.event.pull_request.head.repo.fork  && github.event.pull_request && github.event.action != 'closed'
+        uses: peaceiris/actions-gh-pages@v3.9.3
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ${{ env.PUBLISH_DIR }}
+          destination_dir: ./pull/${{ github.event.number }}
+          allow_empty_commit : true
+          keep_files: true
+          commit_message: ${{ github.event.head_commit.message }}
+          publish_branch: gh-pages
+          user_name: 'github-actions[bot]'
+          user_email: 'github-actions[bot]@users.noreply.github.com'
+
+      - name: Comment with URL to published pull-request docs
+        if: |
+          !github.event.pull_request.head.repo.fork  && github.event.pull_request && github.event.action != 'closed'
+        env:
+          PR_NUM: ${{ github.event.number }}
+        uses: mshick/add-pr-comment@v2.8.1
+        with:
+          message: |
+            View rendered docs @ https://intelpython.github.io/dpnp/pull/${{ env.PR_NUM }}/index.html
+          allow-repeats: false
+
+  clean:
+    if: |
+      !github.event.pull_request.head.repo.fork  && github.event.pull_request && github.event.action == 'closed'
+
+    needs: build-and-deploy
+
+    runs-on: ubuntu-20.04
+
+    steps:
+      - uses: actions/checkout@v3.5.2
+        with:
+          fetch-depth: 0
+
+      - name: Remove docs [PR closed]
+        env:
+          PR_NUM: ${{ github.event.number }}
+        run: |
+          git remote add tokened_docs https://IntelPython:${{ secrets.GITHUB_TOKEN }}@github.com/IntelPython/dpnp.git
+          git fetch tokened_docs
+          git checkout --track tokened_docs/gh-pages
+          echo `pwd`
+          [ -d pull/${PR_NUM} ] && git rm -rf pull/${PR_NUM}
+          git config --global user.name 'github-actions[bot]'
+          git config --global user.email 'github-actions[bot]@users.noreply.github.com'
+          git commit -m "Removing docs for closed pull request ${PR_NUM}"
+          git push tokened_docs gh-pages
+
+      - name: Modify the comment with URL to official documentation
+        uses: mshick/add-pr-comment@v2.8.1
+        with:
+          find: |
+            View rendered docs @.+
+          replace: |
+            View rendered docs @ https://intelpython.github.io/dpnp/index.html

CHANGELOG.md

@@ -4,6 +4,14 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.12.2] - TBA
+
+### Added
+
+### Changed
+
+### Fixed
+
 ## [0.12.1] - 07/18/2023
 
 ### Added
@@ -23,11 +31,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 * Added a specialized kernel for `dpnp.sum` with `axis=0` as a pybind11 extension [#1479](https://github.com/IntelPython/dpnp/pull/1479)
 * Redesigned `dpnp.square` function through pybind11 extension of OneMKL call where possible or Leveraging on `dpctl.tensor` implementation [#1473](https://github.com/IntelPython/dpnp/pull/1473)
 * Redesigned `dpnp.cos` and `dpnp.sin` functions through pybind11 extension of OneMKL calls where possible or Leveraging on `dpctl.tensor` implementation [#1471](https://github.com/IntelPython/dpnp/pull/1471)
-* Redesigned `dpnp.sqrt` function through pybind11 extension of OneMKL call where possible or Leveraging on `dpctl.tensor` implementation [#1470](https://github.com/IntelPython/dpnp/pull/1470)
-* Redesigned `dpnp.log` function through pybind11 extension of OneMKL call where possible or Leveraging on `dpctl.tensor` implementation [#1469](https://github.com/IntelPython/dpnp/pull/1469)
+* Redesigned `dpnp.sqrt` function through pybind11 extension of OneMKL call where possible or leveraging on `dpctl.tensor` implementation [#1470](https://github.com/IntelPython/dpnp/pull/1470)
+* Redesigned `dpnp.log` function through pybind11 extension of OneMKL call where possible or leveraging on `dpctl.tensor` implementation [#1469](https://github.com/IntelPython/dpnp/pull/1469)
 * Leveraged `dpctl.tensor` implementation for logical operations [#1464](https://github.com/IntelPython/dpnp/pull/1464)
 * Leveraged `dpctl.tensor` implementation for `dpnp.floor_divide` function [#1462](https://github.com/IntelPython/dpnp/pull/1462)
 * Leveraged `dpctl.tensor` implementation for comparison functions [#1458](https://github.com/IntelPython/dpnp/pull/1458)
+
 ### Fixed
 
 * Improved `dpnp.dot` function to support OneMKL calls for input and output arrays with strides [#1477](https://github.com/IntelPython/dpnp/pull/1477)

doc/dpctl.rst

@@ -1,10 +1,19 @@
-DPCtl Usage
-===========
+.. _dptcl:
+.. include:: ./ext_links.txt
 
-`DPCtl <https://github.com/IntelPython/dpctl>`_ provides API to manage
-specific SYCL resources for SYCL-based Python packages. DPNP uses DPCtl as
-a global SYCL queue manager. Below code illustrates simple usage of DPNP
-in combination with dpCtl.
+Interplay with the Data Parallel Control Library
+===============================================
+
+`Data Parallel Control Library`_ provides API to manage specific
+`SYCL*`_ resources for SYCL-based Python packages.
+
+An example below demonstrates how the Data Parallel Extension for NumPy* can be
+easily combined with the device management interface provided by dpctl package.
+
+Literally, the SYCL* queue manager interface from the dpctl package allows
+to set an input queue as the currently usable queue inside the context
+manager's scope. This way an array creation function from the dpnp package
+which is defined inside the context will allocate the data using that queue.
 
 .. code-block:: python
   :linenos:
@@ -16,10 +25,11 @@ in combination with dpCtl.
       x = np.array([1, 2, 3])
       s = np.sum(x)
 
-For more information please refer to `DPCtl's documentation <https://intelpython.github.io/dpctl>`_.
+For more information please refer to `Data Parallel Control Library`_
+documentation.
 
 Example
-~~~~~~~
+-------
 .. literalinclude:: ../examples/example10.py
   :linenos:
   :language: python

doc/dpnp_backend_api.rst

@@ -4,4 +4,4 @@
 C++ backend API Reference
 *************************
 
-`DPNP C++ backend <backend_doc/>`_
+`C++ backend of Data Parallel Extension for NumPy* <backend_doc/>`_

doc/ext_links.txt

@@ -0,0 +1,16 @@
+..
+    **********************************************************
+    THESE ARE EXTERNAL PROJECT LINKS USED IN THE DOCUMENTATION
+    **********************************************************
+
+.. _NumPy*: https://numpy.org/
+.. _Python* Array API Standard: https://data-apis.org/array-api/
+.. _OpenCl*: https://www.khronos.org/opencl/
+.. _oneAPI Level Zero: https://spec.oneapi.io/level-zero/latest/index.html
+.. _DPC++: https://www.apress.com/gp/book/9781484255735
+.. _SYCL*: https://www.khronos.org/sycl/
+.. _dpctl: https://intelpython.github.io/dpctl/latest/index.html
+.. _Data Parallel Control Library: https://intelpython.github.io/dpctl/latest/index.html
+.. _Intel oneAPI Base Toolkit: https://www.intel.com/content/www/us/en/developer/tools/oneapi/base-toolkit.html
+.. _Intel Distribution for Python*: https://www.intel.com/content/www/us/en/developer/tools/oneapi/distribution-for-python.html
+.. _Intel AI Analytics Toolkit: https://www.intel.com/content/www/us/en/developer/tools/oneapi/ai-analytics-toolkit.html

doc/index.rst

@@ -1,37 +1,20 @@
-=========================================================
-DPNP -- A NumPy-compatible library for SYCL-based devices
-=========================================================
+.. _index:
+.. include:: ./ext_links.txt
 
-.. module:: dpnp
-
-`DPNP <https://github.com/IntelPython/dpnp>`_ is a NumPy-like library accelerated with SYCL on Intel devices.
-It provides Python interfaces for many NumPy functions, and includes a subset of methods of :class:`dpnp.ndarray`.
-Under the hood it is based on native C++ and oneMKL based kernels.
-
-Being drop-in replacement for Numpy its usage is very similar to Numpy:
-
-   >>> import dpnp as np
-
-The :class:`dpnp.ndarray` class is a compatible alternative of :class:`numpy.ndarray`.
-
-   >>> x = np.array([1, 2, 3])
-
-``x`` in the above example is an instance of :class:`dpnp.ndarray` that is created identically to ``NumPy``'s one.
-The key difference of :class:`dpnp.ndarray` from :class:`numpy.ndarray` is
-that the memory is allocated on Intel GPU when setting up ``DPNP_QUEUE_GPU=1`` in the environment.
+Data Parallel Extension for NumPy*
+==================================
 
-
-Most of the array manipulations are also done in the way similar to NumPy such as:
-
-   >>> s = np.sum(x)
-
-Please see the :ref:`API Reference <dpnp_reference>` for the complete list of supported NumPy APIs
-along with their limitations.
+.. module:: dpnp
 
 .. toctree::
    :maxdepth: 2
 
-   install
+   overview
+   quick_start_guide
    reference/index
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Development information
+
    dpnp_backend_api
-   dpctl

doc/install.rst

@@ -0,0 +1,40 @@
+.. _overview:
+.. include:: ./ext_links.txt
+
+Overview
+========
+
+.. module:: dpnp
+
+The Data Parallel Extension for NumPy* (dpnp package) - a library that
+implements a subset of `NumPy*`_ that can be executed on any
+data parallel device. The subset is a drop-in replacement of core `NumPy*`_
+functions and numerical data types.
+
+The Data Parallel Extension for NumPy* is being developed as part of
+`Intel AI Analytics Toolkit`_ and is distributed with the
+`Intel Distribution for Python*`_. The dpnp package is also available
+on Anaconda cloud. Please refer the :doc:`quick_start_guide` page to learn more.
+
+Being drop-in replacement for `NumPy*`_ means that the usage is very similar:
+
+   >>> import dpnp as np
+
+The :class:`dpnp.ndarray` class is a compatible alternative of
+:class:`numpy.ndarray`.
+
+   >>> x = np.array([1, 2, 3])
+
+``x`` in the above example is an instance of :class:`dpnp.ndarray` that
+is created identically to ``NumPy*``'s one. The key difference of
+:class:`dpnp.ndarray` from :class:`numpy.ndarray` is that the memory
+is allocated on the default `SYCL*`_ device, which is a ``"gpu"`` on systems
+with integrated or discrete GPU (otherwise it is the ``"host"`` device
+on systems that do not have GPU).
+
+Most of the array manipulations are also done in the way similar to `NumPy*`_ such as:
+
+   >>> s = np.sum(x)
+
+Please see the :ref:`API Reference <dpnp_reference>` for the complete list of supported `NumPy*`_ APIs
+along with their limitations.