Skip to content

Commit 3df08fe

Browse files
omalysheomalyshe
authored
Update documentation for 2021.5 release. (#690)
Signed-off-by: Olga Malysheva <[email protected]>
1 parent e109790 commit 3df08fe

10 files changed

+195
-29
lines changed

‎doc/GSG/_static/custom.js

+37
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
window.MathJax = {
2+
TeX: {
3+
Macros: {
4+
src: '\\operatorname{src}',
5+
srclayer: '\\operatorname{src\\_layer}',
6+
srciter: '\\operatorname{src\\_iter}',
7+
srciterc: '\\operatorname{src\\_iter\\_c}',
8+
weights: '\\operatorname{weights}',
9+
weightslayer: '\\operatorname{weights\\_layer}',
10+
weightsiter: '\\operatorname{weights\\_iter}',
11+
weightspeephole: '\\operatorname{weights\\_peephole}',
12+
weightsprojection: '\\operatorname{weights\\_projection}',
13+
bias: '\\operatorname{bias}',
14+
dst: '\\operatorname{dst}',
15+
dstlayer: '\\operatorname{dst\\_layer}',
16+
dstiter: '\\operatorname{dst\\_iter}',
17+
dstiterc: '\\operatorname{dst\\_iter\\_c}',
18+
diffsrc: '\\operatorname{diff\\_src}',
19+
diffsrclayer: '\\operatorname{diff\\_src\\_layer}',
20+
diffsrciter: '\\operatorname{diff\\_src\\_iter}',
21+
diffsrciterc: '\\operatorname{diff\\_src\\_iter\\_c}',
22+
diffweights: '\\operatorname{diff\\_weights}',
23+
diffweightslayer: '\\operatorname{diff\\_weights\\_layer}',
24+
diffweightsiter: '\\operatorname{diff\\_weights\\_iter}',
25+
diffweightspeephole: '\\operatorname{diff\\_weights\\_peephole}',
26+
diffweightsprojection: '\\operatorname{diff\\_weights\\_projection}',
27+
diffbias: '\\operatorname{diff\\_bias}',
28+
diffdst: '\\operatorname{diff\\_dst}',
29+
diffdstlayer: '\\operatorname{diff\\_dst\\_layer}',
30+
diffdstiter: '\\operatorname{diff\\_dst\\_iter}',
31+
diffdstiterc: '\\operatorname{diff\\_dst\\_iter\\_c}',
32+
diffgamma: '\\operatorname{diff\\_\\gamma}',
33+
diffbeta: '\\operatorname{diff\\_\\beta}',
34+
workspace: '\\operatorname{workspace}'
35+
}
36+
}
37+
}

‎doc/GSG/_static/favicons.png

467 Bytes
Loading

‎doc/GSG/_static/oneAPI-rgb-rev-100.png

7.24 KB
Loading

‎doc/GSG/_static/theme_overrides.css

+13
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
/* override table width restrictions */
2+
@media screen and (min-width: 767px) {
3+
4+
.wy-table-responsive table td {
5+
/* !important prevents the common CSS stylesheets from overriding
6+
this as on RTD they are loaded after this stylesheet */
7+
white-space: normal !important;
8+
}
9+
10+
.wy-table-responsive {
11+
overflow: visible !important;
12+
}
13+
}

‎doc/GSG/conf.py

+40-3
Original file line numberDiff line numberDiff line change
@@ -26,7 +26,10 @@
2626
# -- Project information -----------------------------------------------------
2727

2828

29-
project = u'Intel® oneAPI Threading Building Blocks (oneTBB)'
29+
if BUILD_TYPE == 'oneapi' or BUILD_TYPE == 'dita':
30+
project = u'Intel® oneAPI Threading Building Blocks (oneTBB)'
31+
else:
32+
project = u'oneAPI Threading Building Blocks (oneTBB)'
3033
copyright = u'2021, Intel Corporation'
3134
author = u'Intel'
3235

@@ -90,7 +93,8 @@
9093
highlight_language = 'cpp'
9194

9295

93-
rst_prolog = """
96+
if BUILD_TYPE == 'oneapi' or BUILD_TYPE == 'dita':
97+
rst_prolog = """
9498
.. |full_name| replace:: Intel\ |reg|\ oneAPI Threading Building Blocks (oneTBB)
9599
.. |short_name| replace:: oneTBB
96100
.. |product| replace:: oneTBB
@@ -99,6 +103,16 @@
99103
.. |base_tk| replace:: Intel\ |reg|\ oneAPI Base Toolkit
100104
.. |dpcpp| replace:: Intel\ |reg|\ oneAPI DPC++/C++ Compiler
101105
"""
106+
else:
107+
rst_prolog = """
108+
.. |full_name| replace:: oneAPI Threading Building Blocks (oneTBB)
109+
.. |short_name| replace:: oneTBB
110+
.. |product| replace:: oneTBB
111+
.. |reg| unicode:: U+000AE
112+
.. |copy| unicode:: U+000A9
113+
.. |base_tk| replace:: Intel\ |reg|\ oneAPI Base Toolkit
114+
.. |dpcpp| replace:: Intel\ |reg|\ oneAPI DPC++/C++ Compiler
115+
"""
102116

103117

104118
# -- Options for HTML output -------------------------------------------------
@@ -110,13 +124,36 @@
110124
# further. For a list of options available for each theme, see the
111125
# documentation.
112126
#
113-
html_theme = 'sphinx_book_theme'
127+
if BUILD_TYPE == 'oneapi' or BUILD_TYPE == 'dita':
128+
html_theme = 'sphinx_rtd_theme'
129+
else:
130+
html_theme = 'sphinx_book_theme'
131+
html_theme_options = {
132+
'repository_url': 'https://github.com/oneapi-src/oneTBB',
133+
'path_to_docs': 'doc/main',
134+
'use_issues_button': True,
135+
'use_edit_page_button': True,
136+
'repository_branch': 'master',
137+
'extra_footer': '<p align="right"><a href="https://www.intel.com/content/www/us/en/privacy/intel-cookie-notice.html">Cookies</a></p>'
138+
}
114139

115140
# Add any paths that contain custom static files (such as style sheets) here,
116141
# relative to this directory. They are copied after the builtin static files,
117142
# so a file named "default.css" will overwrite the builtin "default.css".
118143
html_static_path = ['_static']
119144

145+
if BUILD_TYPE == 'oneapi' or BUILD_TYPE == 'dita':
146+
html_context = {
147+
'css_files': [
148+
'_static/theme_overrides.css', # override wide tables in RTD theme
149+
],
150+
}
151+
else:
152+
html_js_files = ['custom.js']
153+
html_logo = '_static/oneAPI-rgb-rev-100.png'
154+
155+
html_favicon = '_static/favicons.png'
156+
120157

121158

122159
# Custom sidebar templates, must be a dictionary that maps document names

‎doc/main/conf.py

+2-1
Original file line numberDiff line numberDiff line change
@@ -149,7 +149,8 @@
149149
else:
150150
html_js_files = ['custom.js']
151151
html_logo = '_static/oneAPI-rgb-rev-100.png'
152-
html_favicon = '_static/favicons.png'
152+
153+
html_favicon = '_static/favicons.png'
153154

154155
# Custom sidebar templates, must be a dictionary that maps document names
155156
# to template names.

‎doc/main/index.rst

+6-16
Original file line numberDiff line numberDiff line change
@@ -12,27 +12,17 @@ For a list of available documentation downloads by product version, see these pa
1212
* `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>`_
1313
* `Download Documentation for Intel System Studio <https://software.intel.com/content/www/us/en/develop/articles/download-documentation-intel-system-studio-current-previous.html>`_
1414

15-
The following are some important topics for the ``novice user``:
16-
17-
**Get Started with oneAPI Threading Building Blocks (oneTBB)**
18-
19-
`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.
20-
21-
**oneTBB Benefits**
2215

23-
:ref:`Benefits` describes how |short_name| differs from typical threading packages.
24-
25-
**Package Contents**
26-
27-
|short_name| includes dynamic library files and header files for Windows*, Linux*, and macOS*
28-
operating systems as described in :ref:`Package_Contents`.
16+
The following are some important topics for the ``novice user``:
2917

18+
* `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.
19+
* :ref:`Benefits` describes how |short_name| differs from typical threading packages.
20+
* :ref:`Package_Contents` describes dynamic library files and header files for Windows*, Linux*, and macOS* operating systems used in |short_name|.
3021

31-
The following is important topic for the ``experienced user``:
3222

33-
**Migrating from Threading Building Blocks (TBB)**
23+
The following is an important topic for the ``experienced user``:
3424

35-
Learn how to migrate from TBB to oneTBB with :ref:`Migration_Guide`.
25+
:ref:`Migration_Guide` describes how to migrate from TBB to oneTBB.
3626

3727

3828
.. toctree::

‎doc/main/reference/parallel_sort_ranges_extension.rst

+72
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,72 @@
1+
.. _parallel_sort_ranges_extension:
2+
3+
parallel_sort ranges interface extension
4+
========================================
5+
6+
.. contents::
7+
:local:
8+
:depth: 1
9+
10+
Description
11+
***********
12+
13+
|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>`_
14+
with overloads that takes the container by forwarding reference.
15+
16+
17+
API
18+
***
19+
20+
Header
21+
------
22+
23+
.. code:: cpp
24+
25+
#include <oneapi/tbb/parallel_sort.h>
26+
27+
Syntax
28+
------
29+
30+
.. code:: cpp
31+
32+
namespace oneapi {
33+
namespace tbb {
34+
35+
template <typename Container>
36+
void parallel_sort( Container&& c );
37+
template <typename Container, typename Compare>
38+
void parallel_sort( Container&& c, const Compare& comp );
39+
40+
} // namespace tbb
41+
} // namespace oneapi
42+
43+
Functions
44+
---------
45+
46+
.. cpp:function:: template <typename Container> void parallel_sort( Container&& c );
47+
48+
Equivalent to ``parallel_sort( std::begin(c), std::end(c), comp )``, where `comp` uses `operator<` to determine relative orderings.
49+
50+
.. cpp:function:: template <typename Container, typename Compare> void parallel_sort( Container&& c, const Compare& comp );
51+
52+
Equivalent to ``parallel_sort( std::begin(c), std::end(c), comp )``.
53+
54+
Example
55+
-------
56+
57+
This interface may be used for sorting rvalue or constant views:
58+
59+
.. code:: cpp
60+
61+
#include <array>
62+
#include <span> // requires C++20
63+
#include <oneapi/tbb/parallel_sort.h>
64+
65+
std::span<int> get_span() {
66+
static std::array<int, 3> arr = {3, 2, 1};
67+
return std::span<int>(arr);
68+
}
69+
70+
int main() {
71+
tbb::parallel_sort(get_span());
72+
}

‎doc/main/reference/reference.rst

+1
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,7 @@ It also describes features that are not included in the oneTBB specification.
1818

1919
info_namespace
2020
parallel_for_each_semantics
21+
parallel_sort_ranges_extension
2122

2223
Preview features
2324
****************

‎doc/main/reference/task_group_extensions.rst

+24-9
Original file line numberDiff line numberDiff line change
@@ -15,9 +15,9 @@ Description
1515

1616
|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:
1717

18-
- Constructor that takes a custom ``tbb::task_group_context`` object as an argument.
19-
- Methods to create and run deferred tasks with ``task_handle``.
20-
- Requirements for a user-provided function object.
18+
- constructor that takes a custom ``tbb::task_group_context`` object as an argument
19+
- methods to create and run deferred tasks with ``task_handle``
20+
- requirements for a user-provided function object
2121

2222

2323
API
@@ -46,22 +46,27 @@ Synopsis
4646
task_handle defer(F&& f);
4747
4848
void run(task_handle&& h);
49+
50+
task_group_status run_and_wait(task_handle&&);
4951
50-
//only F return type requirements have changed
52+
//only the requirements for the return type of function F are changed
5153
template<typename F>
5254
void run(F&& f);
5355
};
5456
5557
} // namespace tbb
5658
} // namespace oneapi
5759
60+
61+
5862
Member Functions
5963
----------------
6064

6165
.. cpp:function:: task_group(task_group_context& context)
6266

6367
Constructs an empty ``task_group``, which tasks are associated with the ``context``.
6468

69+
6570
.. cpp:function:: template<typename F> task_handle defer(F&& f)
6671

6772
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
7883

7984
**Returns:** ``task_handle`` object pointing to task to compute ``f()``.
8085

86+
8187
.. cpp:function:: void run(task_handle&& h)
82-
88+
8389
Schedules the task object pointed by the ``h`` for execution.
8490

85-
.. note::
86-
The failure to satisfy the following conditions leads to undefined behavior:
87-
* ``h`` is not empty.
88-
* ``*this`` is the same ``task_group`` that ``h`` is created with.
91+
.. caution:: If ``h`` is empty or ``*this`` is not the same ``task_group`` that ``h`` is created with, the behavior is undefined.
92+
93+
94+
.. cpp:function:: task_group_status run_and_wait(task_handle&& h)
95+
96+
Equivalent to ``{run(std::move(h)); return wait();}``.
97+
98+
**Returns**: The status of ``task_group``.
99+
100+
.. caution::
101+
If ``h`` is empty or ``*this`` is not the same ``task_group`` that ``h`` is created with, the behavior is undefined.
89102

103+
90104
.. cpp:function:: template<typename F> void run(F&& f)
91105

92106
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
99113

100114
* `oneapi::tbb::task_group specification <https://spec.oneapi.com/versions/latest/elements/oneTBB/source/task_scheduler/task_group/task_group_cls.html>`_
101115
* `oneapi::tbb::task_group_context specification <https://spec.oneapi.com/versions/latest/elements/oneTBB/source/task_scheduler/scheduling_controls/task_group_context_cls.html>`_
116+
* `oneapi::tbb::task_group_status specification <https://spec.oneapi.com/versions/latest/elements/oneTBB/source/task_scheduler/task_group/task_group_status_enum.html>`_
102117
* :doc:`oneapi::tbb::task_handle class <task_group_extensions/task_handle>`

0 commit comments

Comments
 (0)