[SYCL][Doc] Render user API classes on a dedicated page (#1578)

This does not add new meaningful documentation, only introduces
a new module for some public host-side APIs.

Also:
- Rename sycl/doc/contents.rst to sycl/doc/index.rst to generate
  index.html for final website.
- Link documentation from the README.md

Signed-off-by: Alexander Batashev <alexander.batashev@intel.com>

Author: alexbatashev

README.md

@@ -22,7 +22,7 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) for details.
 ## Sub-projects Documentation
 
 * oneAPI Data Parallel C++ compiler - See
-  [GetStartedGuide.md](sycl/doc/GetStartedGuide.md)
+  [DPC++ Documentation](https://intel.github.io/llvm-docs/)
 
 ## DPC++ extensions
 

sycl/doc/conf.py

@@ -26,7 +26,7 @@
 
 # -- General configuration ---------------------------------------------------
 
-master_doc = 'contents'
+master_doc = 'index'
 
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom

sycl/doc/doxygen.cfg.in

@@ -32,7 +32,7 @@ DOXYFILE_ENCODING      = UTF-8
 # title of most generated pages and in a few other places.
 # The default value is: My Project.
 
-PROJECT_NAME           = "SYCL Runtime"
+PROJECT_NAME           = "DPC++ Runtime"
 
 # The PROJECT_NUMBER tag can be used to enter a project or revision number. This
 # could be handy for archiving the generated documentation or if some version
@@ -44,7 +44,7 @@ PROJECT_NUMBER         = @PACKAGE_VERSION@
 # for a project that appears at the top of each page and should give viewer a
 # quick idea about the purpose of the project. Keep the description short.
 
-PROJECT_BRIEF          = "Runtime libraries for SYCL"
+PROJECT_BRIEF          = "Runtime libraries for oneAPI Data Parallel C++"
 
 # With the PROJECT_LOGO tag one can specify a logo or an icon that is included
 # in the documentation. The maximum height of the logo should not exceed 55
@@ -437,7 +437,7 @@ LOOKUP_CACHE_SIZE      = 2
 # normally produced when WARNINGS is set to YES.
 # The default value is: NO.
 
-EXTRACT_ALL            = NO
+EXTRACT_ALL            = YES
 
 # If the EXTRACT_PRIVATE tag is set to YES, all private members of a class will
 # be included in the documentation.
@@ -911,7 +911,7 @@ EXCLUDE_SYMBOLS        =
 # that contain example code fragments that are included (see the \include
 # command).
 
-EXAMPLE_PATH           =
+EXAMPLE_PATH           = @abs_srcdir@/../examples/
 
 # If the value of the EXAMPLE_PATH tag contains directories, you can use the
 # EXAMPLE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp and
@@ -1466,7 +1466,7 @@ ECLIPSE_DOC_ID         = org.doxygen.Project
 # The default value is: NO.
 # This tag requires that the tag GENERATE_HTML is set to YES.
 
-DISABLE_INDEX          = NO
+DISABLE_INDEX          = YES
 
 # The GENERATE_TREEVIEW tag is used to specify whether a tree-like index
 # structure should be generated to display hierarchical information. If the tag
@@ -1483,7 +1483,7 @@ DISABLE_INDEX          = NO
 # The default value is: NO.
 # This tag requires that the tag GENERATE_HTML is set to YES.
 
-GENERATE_TREEVIEW      = NO
+GENERATE_TREEVIEW      = YES
 
 # The ENUM_VALUES_PER_LINE tag can be used to set the number of enum values that
 # doxygen will group on one line in the generated HTML documentation.
@@ -2104,7 +2104,9 @@ INCLUDE_FILE_PATTERNS  =
 # recursively expanded use the := operator instead of the = operator.
 # This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
 
-PREDEFINED             = "__SYCL_INLINE_NAMESPACE(X)=namespace X"
+PREDEFINED             = "__SYCL_INLINE_NAMESPACE(X)=namespace X" \
+                         "__SYCL_EXPORT" \
+                         "__SYCL_EXPORT_DEPRECATED(x)="
 
 # If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then this
 # tag can be used to specify a list of macro names that should be expanded. The

sycl/doc/contents.rst renamed to sycl/doc/index.rst

@@ -13,6 +13,7 @@ Using oneAPI DPC++ for Application Development
    cuda/contents
    Extensions <https://github.com/intel/llvm/tree/sycl/sycl/doc/extensions>
    FAQ
+   User API Reference <https://intel.github.io/llvm-docs/doxygen/group__sycl__api.html>
 
 Developing oneAPI DPC++ Compiler
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

sycl/examples/simple-dpcpp-app.cpp

@@ -0,0 +1,54 @@
+#include <CL/sycl.hpp>
+
+using namespace cl::sycl;
+
+int main() {
+  // Create a buffer of 4 ints to be used inside the kernel code.
+  buffer<int, 1> Buffer(4);
+
+  // Create a simple asynchronous exception handler.
+  auto AsyncHandler = [](exception_list ExceptionList) {
+    for (auto &Exception : ExceptionList) {
+      std::rethrow_exception(Exception);
+    }
+  };
+
+  // Create a SYCL queue.
+  queue Queue(AsyncHandler);
+
+  // Size of index space for kernel.
+  range<1> NumOfWorkItems{Buffer.get_count()};
+
+  // Submit command group(work) to queue.
+  Queue.submit([&](handler &cgh) {
+    // Get write only access to the buffer on a device.
+    auto Accessor = Buffer.get_access<access::mode::write>(cgh);
+    // Execute kernel.
+    cgh.parallel_for<class FillBuffer>(NumOfWorkItems, [=](id<1> WIid) {
+      // Fill buffer with indices.
+      Accessor[WIid] = static_cast<int>(WIid.get(0));
+    });
+  });
+
+  // Get read only access to the buffer on the host.
+  // This introduces an implicit barrier which blocks execution until the
+  // command group above completes.
+  const auto HostAccessor = Buffer.get_access<access::mode::read>();
+
+  // Check the results.
+  bool MismatchFound = false;
+  for (size_t I = 0; I < Buffer.get_count(); ++I) {
+    if (HostAccessor[I] != I) {
+      std::cout << "The result is incorrect for element: " << I
+                << " , expected: " << I << " , got: " << HostAccessor[I]
+                << std::endl;
+      MismatchFound = true;
+    }
+  }
+
+  if (!MismatchFound) {
+    std::cout << "The results are correct!" << std::endl;
+  }
+
+  return MismatchFound;
+}