merge from master

Author: rscohn2

.gitignore

@@ -14,3 +14,6 @@ _build
 /site.zip
 
 __pycache__
+
+# -------- Visual Studio --------
+.vs/*

README.rst

@@ -7,6 +7,16 @@ oneAPI Specifications
 
 This repo contains the sources for the `oneAPI Specification`_.
 
+For the latest build from master branch, see `this
+<http://staging.spec.oneapi.com.s3-website-us-west-2.amazonaws.com/exclude/ci/branches/refs/heads/master/versions/latest/index.html>`__.
+
+For more information about oneAPI, see `oneapi.com
+<https://oneapi.com>`__. For information about future releases of the
+oneAPI specification, see the `roadmap <roadmap.rst>`__. To be
+notified about new releases, become a release-only watcher of this
+repo. See `contribute <CONTRIBUTING.rst>`__ for information about
+contributing.
+
 The document is built with `Sphinx`_ using a theme provided by `Read
 the Docs`_.
 

requirements.txt

@@ -13,3 +13,4 @@ sphinx_substitution_extensions
 sphinx_tabs
 sphinxcontrib-spelling
 graphviz
+lxml

roadmap.rst

@@ -12,6 +12,7 @@ Version    Date        Notes
 0.6.0_     01/30/2020  Open source Release
 0.7.0_     03/26/2020  50% content
 0.8.0_     05/28/2020  80% content
+0.8.5_     06/26/2020  85% content
 0.9.0_     07/30/2020  Final Gold Preview
 1.0.0_     08/30/2020  Gold Release
 ========   ==========  ===========
@@ -145,6 +146,7 @@ Date       Milestone
 
 - oneDNN
 
+  - API's 95% complete
   - Rework API presentation into multiple sections
   - Add introduction, execution, primitive lifecycle, and programming model
     sections
@@ -171,6 +173,7 @@ Date       Milestone
 
 - oneMKL
 
+  - USM support
   - Skeleton of spec, breadown by domain
   - Sections that apply to all domains
   - subset of domains with high-level description and APIs, as determined by open source schedule
@@ -218,11 +221,13 @@ Date       Milestone
   - Extend page with collective operations
 
 - Level Zero
+
+  - Command queue groups, module linking, extensions, and improved profiling support
 
 - oneDAL
 
-  - Extend API description to 18 algorithms
-  - Add first version for sections on programming model, algorithmics
+  - Extend API description to kNN classification
+  - Add first version for sections on error handling, namespaces, terminology, math notations
   - Extend numeric tables and data structure sections
 
 - oneTBB
@@ -231,14 +236,25 @@ Date       Milestone
 
 - oneVPL
 
-  - 95% content
-    
+  - Updates deferred to 0.8.5_
+  
 - oneMKL
 
   - All domains complete
+  - Finalized BLAS, LAPACK domains
   - Draft suitable for review so we can distribute to reviewers before
     ISC (6/28/2020).
 
+0.8.5
+-----
+
+Summary
++++++++
+
+- oneVPL
+
+  - Breaking changes introduced.
+
 0.9.0
 -----
 
@@ -277,15 +293,19 @@ Elements
 
   - Finish extending individual primitives' pages with detailed information
     about underlying math and with usage examples
+  - explanation of principles complete
 
 - oneCCL
 
   - Finalize on sections content and details
 
 - Level Zero
+
+  - 1.0 release, support for OpenCL interoperability
 
 - oneDAL
 
+  - Extend algorithms section to cover Random Forest, K-Means, SVM, PCA algorithms
   - Finalize on sections content and details
 
 - oneTBB
@@ -296,6 +316,8 @@ Elements
 - oneVPL
 
 - oneMKL
+
+  - finalize FFT, sparse BLAS, RNG, and VM domains
 
 1.0.0
 -----

scripts/cleanup-mkl.py

@@ -2,7 +2,7 @@
 from os.path import join
 import re
 
-r = re.compile(r'\W+:name: (return-values|include-files|note|note-1|note-2|note-3|syntax|description|input-parameters|output-parameters|example)')
+r = re.compile(r'\W+:name: (known-limitations|return-values|include-files|note|note-1|note-2|note-3|syntax|description|input-parameters|output-parameters|example)')
 
 for root, dirs, files in walk("."):
     for file in files:

scripts/oneapi.py

@@ -120,11 +120,16 @@ def sphinx(root, target):
     if not args.verbose:
         os.environ['LATEXMKOPTS'] = '--silent'
         os.environ['LATEXOPTS'] = '-interaction=nonstopmode -halt-on-error'
+    sphinx_args = ''
+    if not args.verbose:
+        sphinx_args += ' -q'
+    if args.a:
+        sphinx_args += ' -a'
     shell('%s -M %s %s %s %s' % (sphinx_build,
                                  target,
                                  join(root,source_dir),
                                  join(root,build_dir),
-                                 '' if args.verbose else '-q'))
+                                 sphinx_args))
 
 def get_env(var):
     return os.environ[var] if var in os.environ else ''
@@ -389,6 +394,7 @@ def main():
     parser.add_argument('--branch')
     parser.add_argument('--verbose', action='store_true')
     parser.add_argument('--dry-run', action='store_true')
+    parser.add_argument('-a', action='store_true')
     args = parser.parse_args()
 
     commands[args.action](args.root, args.action)

source/_static/custom.css

@@ -1,5 +1,34 @@
 .wy-side-nav-search, .wy-nav-top {
-	background: #4308E5;
+    background: #4308E5;
+}
+
+.eqno {
+    margin-left: 5px;
+    float: right;
+}
+.math .headerlink {
+    display: none;
+    visibility: hidden;
+}
+.math:hover .headerlink {
+    display: inline-block;
+    visibility: visible;
+    margin-right: -0.7em;
+}
+
+/* override table width restrictions
+ * https://rackerlabs.github.io/docs-rackspace/tools/rtd-tables.html */
+@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;
+   }
 }
 
 /* override table width restrictions

source/_static/custom.js

@@ -13,3 +13,41 @@ var wapSection = "oneapi";
 	var s = document.getElementsByTagName('script')[0]; 
 	s.parentNode.insertBefore(po, s);     
 })(); 
+
+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}'
+	}
+    }
+}

source/conf.py

@@ -89,7 +89,7 @@
 #
 html_theme_options = {
   'includehidden': False
-} 
+}
 
 html_context = {
     'display_github': True,
@@ -159,9 +159,39 @@
                  '\\DeclareUnicodeCharacter{3C3}{$\\sigma$}'
                  '\\DeclareUnicodeCharacter{FB01}{$fi$}'
                  '\\DeclareUnicodeCharacter{FB02}{$fl$}'
+                 '\\newcommand{\\src}{\\operatorname{src}}'
+                 '\\newcommand{\\srclayer}{\\operatorname{src\\_layer}}'
+                 '\\newcommand{\\srciter}{\\operatorname{src\\_iter}}'
+                 '\\newcommand{\\srciterc}{\\operatorname{src\\_iter\\_c}}'
+                 '\\newcommand{\\weights}{\\operatorname{weights}}'
+                 '\\newcommand{\\weightslayer}{\\operatorname{weights\\_layer}}'
+                 '\\newcommand{\\weightsiter}{\\operatorname{weights\\_iter}}'
+                 '\\newcommand{\\weightspeephole}{\\operatorname{weights\\_peephole}}'
+                 '\\newcommand{\\weightsprojection}{\\operatorname{weights\\_projection}}'
+                 '\\newcommand{\\bias}{\\operatorname{bias}}'
+                 '\\newcommand{\\dst}{\\operatorname{dst}}'
+                 '\\newcommand{\\dstlayer}{\\operatorname{dst\\_layer}}'
+                 '\\newcommand{\\dstiter}{\\operatorname{dst\\_iter}}'
+                 '\\newcommand{\\dstiterc}{\\operatorname{dst\\_iter\\_c}}'
+                 '\\newcommand{\\diffsrc}{\\operatorname{diff\\_src}}'
+                 '\\newcommand{\\diffsrclayer}{\\operatorname{diff\\_src\\_layer}}'
+                 '\\newcommand{\\diffsrciter}{\\operatorname{diff\\_src\\_iter}}'
+                 '\\newcommand{\\diffsrciterc}{\\operatorname{diff\\_src\\_iter\\_c}}'
+                 '\\newcommand{\\diffweights}{\\operatorname{diff\\_weights}}'
+                 '\\newcommand{\\diffweightslayer}{\\operatorname{diff\\_weights\\_layer}}'
+                 '\\newcommand{\\diffweightsiter}{\\operatorname{diff\\_weights\\_iter}}'
+                 '\\newcommand{\\diffweightspeephole}{\\operatorname{diff\\_weights\\_peephole}}'
+                 '\\newcommand{\\diffweightsprojection}{\\operatorname{diff\\_weights\\_projection}}'
+                 '\\newcommand{\\diffbias}{\\operatorname{diff\\_bias}}'
+                 '\\newcommand{\\diffdst}{\\operatorname{diff\\_dst}}'
+                 '\\newcommand{\\diffdstlayer}{\\operatorname{diff\\_dst\\_layer}}'
+                 '\\newcommand{\\diffdstiter}{\\operatorname{diff\\_dst\\_iter}}'
+                 '\\newcommand{\\diffdstiterc}{\\operatorname{diff\\_dst\\_iter\\_c}}'
+                 '\\newcommand{\\diffgamma}{\\operatorname{diff\\_\\gamma}}'
+                 '\\newcommand{\\diffbeta}{\\operatorname{diff\\_\\beta}}'
+                 '\\newcommand{\\workspace}{\\operatorname{workspace}}'
     ),
 
-
     # Latex figure (float) alignment
     #
     # 'figure_align': 'htbp',
@@ -238,3 +268,5 @@
 
 notfound_default_language = 'versions'
 
+# oneDAL project directory is needed for `dalapi` extension
+onedal_project_dir = 'elements/oneDAL'

source/conf/common_conf.py

@@ -1,5 +1,16 @@
+import os
+import sys
 import string
 
+def path_relative_to_repo_root(relative_path):
+    this_dir = os.path.dirname(os.path.realpath(__file__))
+    root_dir = os.path.abspath(os.path.join(this_dir, '../..'))
+    return os.path.abspath(os.path.join(root_dir, relative_path))
+
+# oneDAL uses custom API generator based on `breathe`.
+# Extend path to let Sphinx find `dalapi` module:
+sys.path.insert(0, path_relative_to_repo_root('source/elements/oneDAL'))
+
 extensions = [
     'notfound.extension',
     'sphinx.ext.autodoc',
@@ -13,8 +24,10 @@
     'sphinx.ext.githubpages',
     'sphinx.ext.graphviz',
     'sphinxcontrib.spelling',
+    'sphinx-prompt',
     'sphinx_substitution_extensions',
     'breathe',
+    'dalapi', # oneDAL API generator
 ]
 
 env = {
@@ -43,7 +56,7 @@
 .. |vpl_version| replace:: $oneapi_version
 .. |mkl_full_name| replace:: oneAPI Math Kernel Library
 .. |mkl_version| replace:: $oneapi_version
-.. _`Level Zero Specification`: https://spec.oneapi.com/versions/$oneapi_version/oneL0/index.html
+.. _`Level Zero Specification`: https://spec.oneapi.com/level-zero/latest/index.html
 """)
 
 rst_prolog = prolog_template.substitute(env)