Merge pull request #1418 from IntelPython/docs/fixes-to-docstrings

[Documentation] fixes to docstrings

Author: ZzEeKkAa

README.md

@@ -12,27 +12,36 @@
 
 
 
-Data-parallel Extension for Numba* (numba-dpex) is a standalone extension for
-the [Numba](http://numba.pydata.org) Python JIT compiler. Numba-dpex provides
-a generic kernel programming API and an offload feature that extends Numba's
-auto-parallelizer to generate data-parallel kernels for `parfor` nodes.
-
-Numba-dpex's kernel API has a design and API similar to Numba's `cuda.jit`
-module, but is based on the [SYCL](https://sycl.tech/) language. The
-code-generation for the kernel API currently supports
-[SPIR-V](https://www.khronos.org/spir/)-based
-[OpenCL](https://www.khronos.org/opencl/) and
-[oneAPI Level Zero](https://spec.oneapi.io/level-zero/latest/index.html)
-devices that are supported by Intel® DPC++ SYCL compiler runtime. Supported
-devices include Intel® CPUs, integrated GPUs and discrete GPUs.
-
-The offload functionality in numba-dpex is based on Numba's `parfor`
-loop-parallelizer. Our compiler extends Numba's `parfor` feature to generate
-kernels and offload them to devices supported by DPC++ SYCL compiler runtime.
-The offload functionality is supported via a new NumPy drop-in replacement
-library: [dpnp](https://github.com/IntelPython/dpnp). Note that `dpnp` and NumPy-based
-expressions can be used together in the same function, with `dpnp` expressions getting
-offloaded by `numba-dpex` and NumPy expressions getting parallelized by Numba.
+Data-parallel Extension for Numba* (numba-dpex) is an open-source standalone
+extension for the [Numba](http://numba.pydata.org) Python JIT compiler.
+Numba-dpex provides a [SYCL*](https://sycl.tech/)-like API for kernel
+programming Python. SYCL* is an open standard developed by the [Unified
+Acceleration Foundation](https://uxlfoundation.org/) as a vendor-agnostic way of
+programming different types of data-parallel hardware such as multi-core CPUs,
+GPUs, and FPGAs. Numba-dpex's kernel-programming API brings the same programming
+model and a similar API to Python. The API allows expressing portable
+data-parallel kernels  in Python and then JIT compiling them for different
+hardware targets. JIT compilation is supported for hardware that use the
+[SPIR-V](https://www.khronos.org/spir/) intermediate representation format that
+includes [OpenCL](https://www.khronos.org/opencl/) CPU (Intel, AMD) devices,
+OpenCL GPU (Intel integrated and discrete GPUs) devices, and [oneAPI Level
+Zero](https://spec.oneapi.io/level-zero/latest/index.html) GPU (Intel integrated
+and discrete GPUs) devices.
+
+The kernel programming API does not yet support every SYCL* feature. Refer to
+the [SYCL* and numba-dpex feature comparison](https://intelpython.github.io/numba-dpex/latest/supported_sycl_features.html)
+page to get a summary of supported features.
+Numba-dpex only implements SYCL*'s kernel programming API, all SYCL runtime
+Python bindings are provided by the [dpctl](https://github.com/IntelPython/dpctl)
+package.
+
+Along with the kernel programming API, numba-dpex extends Numba's
+auto-parallelizer to bring device offload capabilities to `prange` loops and
+NumPy-like vector expressions. The offload functionality is supported via the
+NumPy drop-in replacement library: [dpnp](https://github.com/IntelPython/dpnp).
+Note that `dpnp` and NumPy-based expressions can be used together in the same
+function, with `dpnp` expressions getting offloaded by `numba-dpex` and NumPy
+expressions getting parallelized by Numba.
 
 Refer the [documentation](https://intelpython.github.io/numba-dpex) and examples
 to learn more.

docs/source/conf.py

@@ -5,10 +5,12 @@
 # coding: utf-8
 # Configuration file for the Sphinx documentation builder.
 
-# -- Project information -----------------------------------------------------
+# -- Project information -------------------------------------------------------
 
 import sys
 
+import numba_dpex
+
 sys.path.append(".")
 
 from sycl_spec_links import sycl_ext_links  # noqa E402
@@ -18,23 +20,23 @@
 author = "Intel Corporation"
 
 # The full version, including alpha/beta/rc tags
-# release = "main"
+release = numba_dpex.__version__
 
-# -- General configuration ----------------------------------------------------
+# -- General configuration -----------------------------------------------------
 
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
     "sphinx.ext.todo",
-    "sphinx.ext.intersphinx",
     "sphinx.ext.extlinks",
     "sphinx.ext.githubpages",
     "sphinx.ext.napoleon",
     "sphinxcontrib.programoutput",
     "sphinxcontrib.googleanalytics",
     "myst_parser",
     "autoapi.extension",
+    "sphinx.ext.intersphinx",
     "sphinxcontrib.bibtex",
 ]
 
@@ -52,12 +54,11 @@
 extlinks = {}
 extlinks.update(sycl_ext_links)
 
-# -- Options for HTML output -------------------------------------------------
+# -- Options for HTML output ---------------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-# html_theme = "pydata_sphinx_theme"
 html_theme = "furo"
 
 html_theme_options = {
@@ -82,17 +83,23 @@
 
 html_show_sourcelink = False
 
-# -- Todo extension configuration  ----------------------------------------------
+# -- Todo extension configuration  ---------------------------------------------
 todo_include_todos = True
 todo_link_only = True
 
 # -- InterSphinx configuration: looks for objects in external projects -----
 intersphinx_mapping = {}
 
 
-# -- Prepend module name to an object name or not -----------------------------------
+# -- Prepend module name to an object name or not ------------------------------
 add_module_names = False
 
+
+# -- autodoc configurations ----------------------------------------------------
+
+autodoc_typehints_format = "short"
+python_use_unqualified_type_names = True
+
 # -- Auto API configurations ---------------------------------------------------
 
 autoapi_dirs = [

docs/source/contribution_guide.rst

@@ -1,43 +1,15 @@
 .. _index:
 .. include:: ./ext_links.txt
 
-.. Feedbacks:
-.. 	Use proper names (as provided by marketing)
-.. 	Do not use "we/I"
-.. 	Use correct acronym, expand acronym at the first instance
-
-
-.. Follow cupy docs.
-
-.. Overview:
-.. 	Main Features
-.. 	Project Goal
-
-.. Getting Started:
-.. 	Yevheni
-.. 	Docker page
-
-.. User Guide:
-.. 	https://intelpython.github.io/oneAPI-for-SciPy/details/programming_model/
-.. 	Kernel Programming API --> Kernel Programming Basics
-.. 	Compiling and Offloading DPNP
-.. 		- Introduce @dpjit
-.. 		- Array constructor in dpjit
-.. 		- ufunc (refer to numba)
-.. 		- prange
-.. 		-
-.. 	Debugging using GDB
-.. 	# Performance Tips
-.. 	# Troubleshooting
-.. 	Useful Links
-.. 	# To-Do
-
-.. API Reference:
-
-
 Data Parallel Extension for Numba*
 ==================================
 
+Numba-dpex is an open-source kernel-programming API and JIT compiler for
+portable accelerator programming directly in Python. The API and the compiler is
+modeled after the C++ SYCL* language and brings a similar programming model and
+language design to Python. The page lists the relevant documentation to learn to
+program data-parallel kernels using numba-dpex.
+
 .. module:: numba_dpex
 
 .. toctree::
@@ -55,14 +27,7 @@ Data Parallel Extension for Numba*
 
 .. toctree::
    :maxdepth: 1
-   :caption: Development
-
-   contribution_guide
-
-.. toctree::
-   :maxdepth: 1
-   :caption: Misc Notes
+   :caption: Miscellaneous Notes
 
-   examples
    license
    release-notes

docs/source/examples.rst

@@ -1,3 +1,5 @@
+.. include:: ./../../ext_links.txt
+
 
 Scalar mathematical functions from the Python `math`_ module and the `dpnp`_
 library can be used inside a kernel function. During compilation the