Update documentation for 2021.5 release. (#690)

Signed-off-by: Olga Malysheva <[email protected]>

doc/GSG/_static/custom.js

@@ -0,0 +1,37 @@
+window.MathJax = {
+    TeX: {
+    Macros: {
+        src: '\\operatorname{src}',
+        srclayer: '\\operatorname{src\\_layer}',
+        srciter: '\\operatorname{src\\_iter}',
+        srciterc: '\\operatorname{src\\_iter\\_c}',
+        weights: '\\operatorname{weights}',
+        weightslayer: '\\operatorname{weights\\_layer}',
+        weightsiter: '\\operatorname{weights\\_iter}',
+        weightspeephole: '\\operatorname{weights\\_peephole}',
+        weightsprojection: '\\operatorname{weights\\_projection}',
+        bias: '\\operatorname{bias}',
+        dst: '\\operatorname{dst}',
+        dstlayer: '\\operatorname{dst\\_layer}',
+        dstiter: '\\operatorname{dst\\_iter}',
+        dstiterc: '\\operatorname{dst\\_iter\\_c}',
+        diffsrc: '\\operatorname{diff\\_src}',
+        diffsrclayer: '\\operatorname{diff\\_src\\_layer}',
+        diffsrciter: '\\operatorname{diff\\_src\\_iter}',
+        diffsrciterc: '\\operatorname{diff\\_src\\_iter\\_c}',
+        diffweights: '\\operatorname{diff\\_weights}',
+        diffweightslayer: '\\operatorname{diff\\_weights\\_layer}',
+        diffweightsiter: '\\operatorname{diff\\_weights\\_iter}',
+        diffweightspeephole: '\\operatorname{diff\\_weights\\_peephole}',
+        diffweightsprojection: '\\operatorname{diff\\_weights\\_projection}',
+        diffbias: '\\operatorname{diff\\_bias}',
+        diffdst: '\\operatorname{diff\\_dst}',
+        diffdstlayer: '\\operatorname{diff\\_dst\\_layer}',
+        diffdstiter: '\\operatorname{diff\\_dst\\_iter}',
+        diffdstiterc: '\\operatorname{diff\\_dst\\_iter\\_c}',
+        diffgamma: '\\operatorname{diff\\_\\gamma}',
+        diffbeta: '\\operatorname{diff\\_\\beta}',
+        workspace: '\\operatorname{workspace}'
+    }
+    }
+}

doc/GSG/_static/theme_overrides.css

@@ -0,0 +1,13 @@
+/* override table width restrictions */
+@media screen and (min-width: 767px) {
+
+   .wy-table-responsive table td {
+      /* !important prevents the common CSS stylesheets from overriding
+         this as on RTD they are loaded after this stylesheet */
+      white-space: normal !important;
+   }
+
+   .wy-table-responsive {
+      overflow: visible !important;
+   }
+}

doc/GSG/conf.py

@@ -26,7 +26,10 @@
 # -- Project information -----------------------------------------------------
 
 
-project = u'Intel® oneAPI Threading Building Blocks (oneTBB)'
+if BUILD_TYPE == 'oneapi' or BUILD_TYPE == 'dita':
+    project = u'Intel® oneAPI Threading Building Blocks (oneTBB)'
+else:
+    project = u'oneAPI Threading Building Blocks (oneTBB)'
 copyright = u'2021, Intel Corporation'
 author = u'Intel'
 
@@ -90,7 +93,8 @@
 highlight_language = 'cpp' 
 
 
-rst_prolog = """
+if BUILD_TYPE == 'oneapi' or BUILD_TYPE == 'dita':
+    rst_prolog = """
 .. |full_name| replace:: Intel\ |reg|\  oneAPI Threading Building Blocks (oneTBB)
 .. |short_name| replace:: oneTBB
 .. |product| replace:: oneTBB
@@ -99,6 +103,16 @@
 .. |base_tk| replace:: Intel\ |reg|\  oneAPI Base Toolkit
 .. |dpcpp| replace:: Intel\ |reg|\  oneAPI DPC++/C++ Compiler
     """
+else:
+    rst_prolog = """
+.. |full_name| replace:: oneAPI Threading Building Blocks (oneTBB)
+.. |short_name| replace:: oneTBB
+.. |product| replace:: oneTBB
+.. |reg| unicode:: U+000AE
+.. |copy| unicode:: U+000A9
+.. |base_tk| replace:: Intel\ |reg|\  oneAPI Base Toolkit
+.. |dpcpp| replace:: Intel\ |reg|\  oneAPI DPC++/C++ Compiler
+    """
 
 
 # -- Options for HTML output -------------------------------------------------
@@ -110,13 +124,36 @@
 # further.  For a list of options available for each theme, see the
 # documentation.
 #
-html_theme = 'sphinx_book_theme'
+if BUILD_TYPE == 'oneapi' or BUILD_TYPE == 'dita':
+    html_theme = 'sphinx_rtd_theme'
+else:
+    html_theme = 'sphinx_book_theme'
+    html_theme_options = {
+    'repository_url': 'https://github.com/oneapi-src/oneTBB',
+    'path_to_docs': 'doc/main',
+    'use_issues_button': True,
+    'use_edit_page_button': True,
+    'repository_branch': 'master',
+    'extra_footer': '<p align="right"><a href="https://www.intel.com/content/www/us/en/privacy/intel-cookie-notice.html">Cookies</a></p>'
+    }
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ['_static']
 
+if BUILD_TYPE == 'oneapi'  or BUILD_TYPE == 'dita':
+    html_context = {
+        'css_files': [
+            '_static/theme_overrides.css',  # override wide tables in RTD theme
+        ],
+    }
+else:
+    html_js_files = ['custom.js']
+    html_logo = '_static/oneAPI-rgb-rev-100.png'
+
+html_favicon = '_static/favicons.png'
+
 
 
 # Custom sidebar templates, must be a dictionary that maps document names

doc/main/conf.py

@@ -149,7 +149,8 @@
 else:
     html_js_files = ['custom.js']
     html_logo = '_static/oneAPI-rgb-rev-100.png'
-    html_favicon = '_static/favicons.png'
+
+html_favicon = '_static/favicons.png'
 
 # Custom sidebar templates, must be a dictionary that maps document names
 # to template names.

doc/main/index.rst

@@ -12,27 +12,17 @@ For a list of available documentation downloads by product version, see these pa
 * `Download Documentation for Intel Parallel Studio XE <https://software.intel.com/content/www/us/en/develop/articles/download-documentation-intel-parallel-studio-xe-current-previous.html>`_
 * `Download Documentation for Intel System Studio <https://software.intel.com/content/www/us/en/develop/articles/download-documentation-intel-system-studio-current-previous.html>`_
 
-The following are some important topics for the ``novice user``:
-
-**Get Started with oneAPI Threading Building Blocks (oneTBB)**
-
-`Get Started with oneTBB <https://software.intel.com/content/www/us/en/develop/documentation/get-started-with-onetbb/top.html>`_ gives you a brief explanation of what oneTBB is. 
-
-**oneTBB Benefits**
 
-:ref:`Benefits` describes how |short_name| differs from typical threading packages.
-
-**Package Contents**
-
-|short_name| includes dynamic library files and header files for Windows*, Linux*, and macOS* 
-operating systems as described in :ref:`Package_Contents`.
+The following are some important topics for the ``novice user``:
 
+* `Get Started with oneTBB <https://software.intel.com/content/www/us/en/develop/documentation/get-started-with-onetbb/top.html>`_ gives you a brief explanation of what oneTBB is. 
+* :ref:`Benefits` describes how |short_name| differs from typical threading packages.
+* :ref:`Package_Contents` describes dynamic library files and header files for Windows*, Linux*, and macOS* operating systems used in |short_name|.
 
-The following is important topic for the ``experienced user``:
 
-**Migrating from Threading Building Blocks (TBB)**
+The following is an important topic for the ``experienced user``:
 
-Learn how to migrate from TBB to oneTBB with :ref:`Migration_Guide`.
+:ref:`Migration_Guide` describes how to migrate from TBB to oneTBB.
 
 
 .. toctree::

doc/main/reference/parallel_sort_ranges_extension.rst

@@ -0,0 +1,72 @@
+.. _parallel_sort_ranges_extension:
+
+parallel_sort ranges interface extension
+========================================
+
+.. contents::
+    :local:
+    :depth: 1
+
+Description
+***********
+
+|full_name| implementation extends the `oneapi::tbb::parallel_sort specification <https://spec.oneapi.io/versions/latest/elements/oneTBB/source/algorithms/functions/parallel_sort_func.html>`_
+with overloads that takes the container by forwarding reference.
+
+
+API
+***
+
+Header
+------
+
+.. code:: cpp
+
+    #include <oneapi/tbb/parallel_sort.h>
+
+Syntax
+------
+
+.. code:: cpp
+
+    namespace oneapi {
+        namespace tbb {
+
+            template <typename Container>
+            void parallel_sort( Container&& c );
+            template <typename Container, typename Compare>
+            void parallel_sort( Container&& c, const Compare& comp );
+
+        } // namespace tbb
+    } // namespace oneapi
+
+Functions
+---------
+
+.. cpp:function:: template <typename Container> void parallel_sort( Container&& c );
+
+    Equivalent to ``parallel_sort( std::begin(c), std::end(c), comp )``, where `comp` uses `operator<` to determine relative orderings.
+
+.. cpp:function:: template <typename Container, typename Compare> void parallel_sort( Container&& c, const Compare& comp );
+
+    Equivalent to ``parallel_sort( std::begin(c), std::end(c), comp )``.
+
+Example
+-------
+
+This interface may be used for sorting rvalue or constant views:
+
+.. code:: cpp
+
+    #include <array>
+    #include <span> // requires C++20
+    #include <oneapi/tbb/parallel_sort.h>
+
+    std::span<int> get_span() {
+        static std::array<int, 3> arr = {3, 2, 1};
+        return std::span<int>(arr);
+    }
+
+    int main() {
+        tbb::parallel_sort(get_span());
+    }

doc/main/reference/reference.rst

@@ -18,6 +18,7 @@ It also describes features that are not included in the oneTBB specification.
 
     info_namespace
     parallel_for_each_semantics
+    parallel_sort_ranges_extension
 
 Preview features
 ****************

doc/main/reference/task_group_extensions.rst

@@ -15,9 +15,9 @@ Description
 
 |full_name| implementation extends the `tbb::task_group specification <https://spec.oneapi.com/versions/latest/elements/oneTBB/source/task_scheduler/task_group/task_group_cls.html>`_ with the following members:
 
-  - Constructor that takes a custom ``tbb::task_group_context`` object as an argument.
-  - Methods to create and run deferred tasks with ``task_handle``. 
-  - Requirements for a user-provided function object.
+  - constructor that takes a custom ``tbb::task_group_context`` object as an argument
+  - methods to create and run deferred tasks with ``task_handle`` 
+  - requirements for a user-provided function object
 
 
 API
@@ -46,22 +46,27 @@ Synopsis
                task_handle defer(F&& f);
                    
                void run(task_handle&& h);
+               
+               task_group_status run_and_wait(task_handle&&);
 
-               //only F return type requirements have changed              
+               //only the requirements for the return type of function F are changed              
                template<typename F>
                void run(F&& f);
            }; 
 
         } // namespace tbb
     } // namespace oneapi
 
+
+
 Member Functions
 ----------------
 
 .. cpp:function:: task_group(task_group_context& context)
 
 Constructs an empty ``task_group``, which tasks are associated with the ``context``.
 
+
 .. cpp:function:: template<typename F> task_handle  defer(F&& f)
 
 Creates a deferred task to compute ``f()`` and returns ``task_handle`` pointing to it.
@@ -78,15 +83,24 @@ As an optimization hint, ``F`` might return a ``task_handle``, which task object
 
 **Returns:** ``task_handle`` object pointing to task to compute ``f()``.
 
+
 .. cpp:function:: void run(task_handle&& h)
-   
+
 Schedules the task object pointed by the ``h`` for execution.
 
-.. note::
-   The failure to satisfy the following conditions leads to undefined behavior:
-      * ``h`` is not empty.
-      * ``*this`` is the same ``task_group`` that ``h`` is created with.    
+.. caution:: If ``h`` is empty or ``*this`` is not the same ``task_group`` that ``h`` is created with, the behavior is undefined.
+
+
+.. cpp:function:: task_group_status run_and_wait(task_handle&& h)
+
+Equivalent to ``{run(std::move(h)); return wait();}``.
+
+**Returns**: The status of ``task_group``.
+
+.. caution::
+   If ``h`` is empty or ``*this`` is not the same ``task_group`` that ``h`` is created with, the behavior is undefined.
 
+
 .. cpp:function:: template<typename F> void  run(F&& f)
 
 As an optimization hint, ``F`` might return a ``task_handle``, which task object can be executed next.
@@ -99,4 +113,5 @@ As an optimization hint, ``F`` might return a ``task_handle``, which task object
 
 * `oneapi::tbb::task_group specification <https://spec.oneapi.com/versions/latest/elements/oneTBB/source/task_scheduler/task_group/task_group_cls.html>`_
 * `oneapi::tbb::task_group_context specification <https://spec.oneapi.com/versions/latest/elements/oneTBB/source/task_scheduler/scheduling_controls/task_group_context_cls.html>`_
+* `oneapi::tbb::task_group_status specification <https://spec.oneapi.com/versions/latest/elements/oneTBB/source/task_scheduler/task_group/task_group_status_enum.html>`_ 
 * :doc:`oneapi::tbb::task_handle class <task_group_extensions/task_handle>`