[SYCL][Doc] Deploy Sphinx documentation (#1406)

Signed-off-by: Alexander Batashev <[email protected]>

Author: Alexander Batashev

.github/workflows/gh_pages.yml

@@ -13,14 +13,17 @@ jobs:
         ref: sycl
         path: repo
     - name: Install deps
-      run: sudo apt-get install -y doxygen graphviz ssh ninja-build
+      run: |
+        sudo apt-get install -y doxygen graphviz ssh ninja-build
+        sudo pip3 install sphinx recommonmark sphinx_markdown_tables
     - name: Build Docs
       run: |
         mkdir -p $GITHUB_WORKSPACE/build
         cd $GITHUB_WORKSPACE/build
         python $GITHUB_WORKSPACE/repo/buildbot/configure.py -w $GITHUB_WORKSPACE \
         -s $GITHUB_WORKSPACE/repo -o $GITHUB_WORKSPACE/build -t Release --docs
         cmake --build . --target doxygen-sycl
+        cmake --build . --target docs-sycl-html
     - name: Deploy
       env:
         SSH_KEY: ${{secrets.ACTIONS_DEPLOY_KEY}}
@@ -32,7 +35,11 @@ jobs:
         ssh-add -k ~/.ssh/id_rsa
         git clone [email protected]:intel/llvm-docs.git docs
         cd $GITHUB_WORKSPACE/docs
-        yes | \cp -rf $GITHUB_WORKSPACE/build/tools/sycl/doc/doxygen/html/* .
+        git rm -rf .
+        touch .nojekyll
+        yes | \cp -rf $GITHUB_WORKSPACE/build/tools/sycl/doc/html/* .
+        mkdir doxygen
+        yes | \cp -rf $GITHUB_WORKSPACE/build/tools/sycl/doc/doxygen/html/* doxygen/
         git config --global user.name "iclsrc"
         git config --global user.email "[email protected]"
         git add .

buildbot/configure.py

@@ -20,6 +20,7 @@ def do_configure(args):
     sycl_build_pi_cuda = 'OFF'
     llvm_enable_assertions = 'ON'
     llvm_enable_doxygen = 'OFF'
+    llvm_enable_sphinx = 'OFF'
     llvm_build_shared_libs = 'OFF'
 
     if platform.system() == 'Linux':
@@ -38,6 +39,7 @@ def do_configure(args):
 
     if args.docs:
         llvm_enable_doxygen = 'ON'
+        llvm_enable_sphinx = 'ON'
 
     if args.shared_libs:
         llvm_build_shared_libs = 'ON'
@@ -63,6 +65,7 @@ def do_configure(args):
         "-DCMAKE_INSTALL_PREFIX={}".format(install_dir),
         "-DSYCL_INCLUDE_TESTS=ON", # Explicitly include all kinds of SYCL tests.
         "-DLLVM_ENABLE_DOXYGEN={}".format(llvm_enable_doxygen),
+        "-DLLVM_ENABLE_SPHINX={}".format(llvm_enable_sphinx),
         "-DBUILD_SHARED_LIBS={}".format(llvm_build_shared_libs),
         "-DSYCL_ENABLE_XPTI_TRACING=ON", # Explicitly turn on XPTI tracing
         llvm_dir

sycl/doc/CMakeLists.txt

@@ -77,4 +77,11 @@ if (LLVM_ENABLE_DOXYGEN)
 endif()
 endif()
 
-# TODO enable sphinx
+if (LLVM_ENABLE_SPHINX)
+  include(AddSphinxTarget)
+  if (SPHINX_FOUND)
+    if (${SPHINX_OUTPUT_HTML})
+      add_sphinx_target(html sycl)
+    endif()
+  endif()
+endif()

sycl/doc/EnvironmentVariables.md

@@ -1,8 +1,9 @@
-# Overview
+# Environment Variables
 
-This file describes environment variables that are having effect on DPC++ compiler and runtime.
+This document describes environment variables that are having effect on DPC++ 
+compiler and runtime.
 
-# Controlling DPC++ RT
+## Controlling DPC++ RT
 
 **Warning:** the environment variables described in this document are used for
 development and debugging of DPC++ compiler and runtime. Their semantics are
@@ -24,7 +25,7 @@ subject to change. Do not rely on these variables in production code.
 | SYCL_DEVICE_ALLOWLIST | A list of devices and their minimum driver version following the pattern: DeviceName:{{XXX}},DriverVersion:{{X.Y.Z.W}}. Also may contain PlatformName and PlatformVersion | Filter out devices that do not match the pattern specified. Regular expression can be passed and the DPC++ runtime will select only those devices which satisfy the regex. |
 `(*) Note: Any means this environment variable is effective when set to any non-null value.`
 
-## SYCL_PRINT_EXECUTION_GRAPH Options
+### SYCL_PRINT_EXECUTION_GRAPH Options
 
 SYCL_PRINT_EXECUTION_GRAPH can accept one or more comma separated values from the table below
 

sycl/doc/GetStartedGuide.md

@@ -1,9 +1,9 @@
-# Overview
+# Getting Started with oneAPI DPC++
 
 The DPC++ Compiler compiles C++ and SYCL\* source files with code for both CPU
 and a wide range of compute accelerators such as GPU and FPGA.
 
-# Table of contents
+**Table of contents**
 
 * [Prerequisites](#prerequisites)
   * [Create DPC++ workspace](#create-dpc-workspace)
@@ -19,7 +19,7 @@ and a wide range of compute accelerators such as GPU and FPGA.
 * [CUDA backend limitations](#cuda-backend-limitations)
 * [Find More](#find-more)
 
-# Prerequisites
+## Prerequisites
 
 * `git` - https://git-scm.com/downloads
 * `cmake` version 3.2 or later - http://www.cmake.org/download/
@@ -30,7 +30,7 @@ and a wide range of compute accelerators such as GPU and FPGA.
   * Windows: `Visual Studio` version 15.7 preview 4 or later -
     https://visualstudio.microsoft.com/downloads/
 
-## Create DPC++ workspace
+### Create DPC++ workspace
 
 Throughout this document `DPCPP_HOME` denotes the path to the local directory
 created as DPC++ workspace. It might be useful to create an environment variable
@@ -66,7 +66,7 @@ mkdir %DPCPP_HOME%\build
 cd %DPCPP_HOME%\build
 ```
 
-# Build DPC++ toolchain
+## Build DPC++ toolchain
 
 The easiest way to get started is to use the buildbot [configure](../../buildbot/configure.py)
 and [compile](../../buildbot/configure.py) scripts.
@@ -104,7 +104,7 @@ For more, see [opencl-aot documentation](../../opencl-aot/README.md).
 
 TODO: add instructions how to deploy built DPC++ toolchain.
 
-## Build DPC++ toolchain with libc++ library
+### Build DPC++ toolchain with libc++ library
 
 There is experimental support for building and linking DPC++ runtime with
 libc++ library instead of libstdc++. To enable it the following CMake options
@@ -117,7 +117,7 @@ should be used.
 -DSYCL_LIBCXX_LIBRARY_PATH=<path to libc++ and libc++abi libraries>
 ```
 
-## Build DPC++ toolchain with support for NVIDIA CUDA
+### Build DPC++ toolchain with support for NVIDIA CUDA
 
 There is experimental support for DPC++ for CUDA devices.
 
@@ -133,9 +133,9 @@ Currently, the only combination tested is Ubuntu 18.04 with CUDA 10.2 using
 a Titan RTX GPU (SM 71), but it should work on any GPU compatible with SM 50 or
 above.
 
-# Use DPC++ toolchain
+## Use DPC++ toolchain
 
-## Using the DPC++ toolchain on CUDA platforms
+### Using the DPC++ toolchain on CUDA platforms
 
 The DPC++ toolchain support on CUDA platforms is still in an experimental phase.
 Currently, the DPC++ toolchain relies on having a recent OpenCL implementation
@@ -153,7 +153,7 @@ Instead of installing the low level CPU runtime, it is possible to build and
 install the [Khronos ICD loader](https://github.com/KhronosGroup/OpenCL-ICD-Loader), 
 which contains all the symbols required.
 
-## Install low level runtime
+### Install low level runtime
 
 To run DPC++ applications on OpenCL devices, OpenCL implementation(s) must be
 present in the system.
@@ -251,9 +251,9 @@ command:
 c:\oclcpu_rt_<cpu_version>\install.bat c:\tbb_<tbb_version>\tbb\bin\intel64\vc14
 ```
 
-## Test DPC++ toolchain
+### Test DPC++ toolchain
 
-### Run regression tests
+#### Run regression tests
 
 To verify that built DPC++ toolchain is working correctly, run:
 
@@ -273,7 +273,7 @@ skipped.
 If CUDA support has been built, it is tested only if there are CUDA devices 
 available.
 
-### Run Khronos\* SYCL\* conformance test suite (optional)
+#### Run Khronos\* SYCL\* conformance test suite (optional)
 
 Khronos\* SYCL\* conformance test suite (CTS) is intended to validate
 implementation conformance to Khronos\* SYCL\* specification. DPC++ compiler is
@@ -313,7 +313,7 @@ command:
 After CMake cache is generated, build the documentation with `doxygen-sycl`
 target. It will be put to `/path/to/build/tools/sycl/doc/html` directory.
 
-## Run simple DPC++ application
+### Run simple DPC++ application
 
 A simple DPC++ or SYCL\* program consists of following parts:
 1. Header section
@@ -442,7 +442,7 @@ selectors (e.g. `cl::sycl::cpu_selector`, `cl::sycl::gpu_selector`,
 explained in following section [Code the program for a specific
 GPU](#code-the-program-for-a-specific-gpu).
 
-## Code the program for a specific GPU
+### Code the program for a specific GPU
 
 To specify OpenCL device SYCL provides the abstract `cl::sycl::device_selector`
 class which the can be used to define how the runtime should select the best
@@ -506,11 +506,11 @@ class CUDASelector : public cl::sycl::device_selector {
 };
 ```
 
-# C++ standard
+## C++ standard
 
 - Minimal supported C++ standard is C++11 on Linux and C++14 on Windows.
 
-# Known Issues and Limitations
+## Known Issues and Limitations
 
 - DPC++ device compiler fails if the same kernel was used in different
   translation units.
@@ -521,15 +521,15 @@ class CUDASelector : public cl::sycl::device_selector {
 - On Windows linking DPC++ applications with `/MTd` flag is known to cause
   crashes.
 
-## CUDA back-end limitations
+### CUDA back-end limitations
 
 - Backend is only supported on Linux
 - The only combination tested is Ubuntu 18.04 with CUDA 10.2 using a Titan RTX
   GPU (SM 71), but it should work on any GPU compatible with SM 50 or above
 - The NVIDIA OpenCL headers conflict with the OpenCL headers required for this
   project and may cause compilation issues on some platforms
 
-# Find More
+## Find More
 
 DPC++ specification:
 [https://spec.oneapi.com/versions/latest/elements/dpcpp/source/index.html](https://spec.oneapi.com/versions/latest/elements/dpcpp/source/index.html)

sycl/doc/PreprocessorMacros.md

@@ -1,4 +1,4 @@
-# Overview
+# Preprocessor Macros 
 
 This file describes macros that have effect on SYCL compiler and run-time.
 

sycl/doc/UsersManual.md

@@ -1,4 +1,4 @@
-# Overview
+# Users Manual
 
 The DPC++ Compiler contains many options to generate the desired binaries for
 your application.
@@ -167,7 +167,7 @@ your application.
 
     Allow unnamed SYCL lambda kernels.
 
-# SYCL device code compilation
+## SYCL device code compilation
 
 To invoke SYCL device compiler set `-fsycl-device-only` flag.
 
@@ -183,18 +183,18 @@ By default the output format for SYCL device is LLVM bytecode.
 $ clang++ -fsycl-device-only -fno-sycl-use-bitcode sycl-app.cpp -o sycl-app.spv
 ```
 
-# Static archives with SYCL device code
+## Static archives with SYCL device code
 
 The DPC++ Compiler contains support to create and use static archives that
 contain device enabled fat objects.
 
-## Build your objects
+### Build your objects
 
 ```console
 $ clang++ -fsycl sycl-app1.cpp sycl-app2.cpp -c
 ```
 
-## Create the static archive
+### Create the static archive
 
 Build the static archive in the same manner as you would any other normal
 static archive, using the objects that were created using the above step.
@@ -203,7 +203,7 @@ static archive, using the objects that were created using the above step.
 $ ar cr libsyclapp.a sycl-app1.o sycl-app2.o
 ```
 
-## Use the static archive
+### Use the static archive
 
 Once you have created the archive, you can use it when creating your final
 application.  The fat archives are treated differently than a regular archive

sycl/doc/conf.py

@@ -0,0 +1,60 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+# import os
+# import sys
+# sys.path.insert(0, os.path.abspath('.'))
+
+import datetime
+
+# -- Project information -----------------------------------------------------
+
+now = datetime.datetime.now()
+
+project = 'oneAPI DPC++ Compiler'
+copyright = str(now.year) + ', Intel Corporation'
+author = 'Intel Corporation'
+
+# -- General configuration ---------------------------------------------------
+
+master_doc = 'contents'
+
+# 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_markdown_tables'
+]
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'friendly'
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+html_theme = 'haiku'
+
+# The suffix of source filenames.
+source_suffix = ['.rst', '.md']
+
+# Extensions are mostly in asciidoc which has poor support in Sphinx
+exclude_patterns = ['extensions/*']
+
+source_parsers = {'.md': 'recommonmark.parser.CommonMarkParser'}
+
+def on_missing_reference(app, env, node, contnode):
+    if node['reftype'] == 'any':
+        return contnode
+    else:
+        return None
+
+def setup(app):
+    app.connect('missing-reference', on_missing_reference)

sycl/doc/contents.rst

@@ -0,0 +1,27 @@
+Data Parallel C++ Documentation
+===============================
+
+Using oneAPI DPC++ for Application Development
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. toctree::
+   :maxdepth: 1
+
+   GetStartedGuide
+   UsersManual
+   PreprocessorMacros
+   cuda/contents
+   Extensions <https://github.com/intel/llvm/tree/sycl/sycl/doc/extensions>
+   FAQ
+
+Developing oneAPI DPC++ Compiler
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. toctree::
+   :maxdepth: 1
+
+   API Reference <https://intel.github.io/llvm-docs/doxygen>
+   CompilerAndRuntimeDesign
+   EnvironmentVariables
+   PluginInterface
+

sycl/doc/cuda/contents.rst

@@ -0,0 +1,8 @@
+Experimental CUDA backend for DPC++
+===================================
+
+.. toctree::
+   :maxdepth: 1
+
+   cuda-vs-opencl-math-builtin-precisions
+   opencl-subgroup-vs-cuda-crosslane-op