Updated Overview page

IntelPython · Jul 18, 2023 · 6c545ac · 6c545ac
1 parent af1af29
commit 6c545ac
Show file tree

Hide file tree

Showing 6 changed files with 133 additions and 37 deletions.
diff --git a/.github/workflows/build-sphinx.yml b/.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,45 @@ 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: Deploy docs [PR]
+        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
+          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'
+
+  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
diff --git a/CHANGELOG.md b/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)

diff --git a/doc/ext_links.txt b/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: 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
diff --git a/doc/install.rst → doc/getting_started.rst b/doc/install.rst → doc/getting_started.rst
@@ -1,5 +1,12 @@
-Installation Guide
-==================
+.. _getting_started:
+.. include:: ./ext_links.txt
+
+.. |copy| unicode:: U+000A9
+
+.. |trade| unicode:: U+2122
+
+Getting Started
+===============
 
 Requirements
 ------------

diff --git a/doc/index.rst b/doc/index.rst
@@ -1,37 +1,16 @@
-=========================================================
-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])
+Data Parallel Extension for Numpy*
+==================================
 
-``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.
-
-
-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
+   getting_started
    reference/index
    dpnp_backend_api
    dpctl
diff --git a/doc/overview.rst b/doc/overview.rst
@@ -0,0 +1,40 @@
+.. _overview
+.. include:: ./ext_links.txt
+
+Overview
+========
+
+.. module:: dpnp
+
+The Data Parallel Extensions 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 Extensions 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:`getting_started` 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.