Merge master and add version support.

Author: Diptorup Deb

docs/CMakeLists.txt

@@ -7,6 +7,13 @@ option(DPCTL_ENABLE_DOXYREST
     OFF
 )
 
+# Option to add verion links to the side bar. This option is primarily
+# intended to generate dpctl's docs for our github.io page.
+option(DPCTL_USE_MULTIVERSION_TEMPLATE
+    "Enable adding verion links to side bar"
+    OFF
+)
+
 # This function defines everything needed to generate Doxygen docs
 function(_setup_doxygen)
     # We generate doxygen only for the public headers to keep the Doxyrest

docs/_templates/versions.html

@@ -0,0 +1,22 @@
+{% if READTHEDOCS or display_lower_left %}
+{# Add rst-badge after rst-versions for small badge style. #}
+  <div class="rst-versions" data-toggle="rst-versions" role="note" aria-label="versions">
+    <span class="rst-current-version" data-toggle="rst-current-version">
+      <span class="fa fa-book"> Other versions</span>
+      v: {{ current_version }}
+      <span class="fa fa-caret-down"></span>
+    </span>
+    <div class="rst-other-versions">
+      {% if versions|length >= 1 %}
+      <dl>
+        <dt>{{ _('Versions') }}</dt>
+        {% for slug, url in versions %}
+          {% if slug == current_version %} <strong> {% endif %}
+          <dd><a href="{{ url }}">{{ slug }}</a></dd>
+          {% if slug == current_version %} </strong> {% endif %}
+        {% endfor %}
+      </dl>
+      {% endif %}
+    </div>
+  </div>
+{% endif %}

docs/conf.in

@@ -99,3 +99,31 @@ html_theme_options = {
 # 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']
+
+generate_multiversion = "@DPCTL_USE_MULTIVERSION_TEMPLATE@"
+
+if generate_multiversion == "ON":
+    try:
+        html_context
+    except NameError:
+        html_context = dict()
+    html_context["display_lower_left"] = True
+    templates_path = ["_templates"]
+    html_context["current_version"] = version
+    html_context["version"] = version
+
+    # POPULATE LINKS TO OTHER VERSIONS
+    html_context["versions"] = list()
+
+    # Populate the list of documented versions from the doc_versions.tx
+    versions = []
+    with open("doc_versions.txt", "r") as doc_versions:
+        while True:
+            version = doc_versions.readline().strip()
+            if not version:
+                break
+            elif len(version):
+                versions.append(version)
+
+    for version in versions:
+        html_context["versions"].append((version, "../" + version + "/index.html"))

docs/doc_versions.txt

@@ -0,0 +1,2 @@
+0.6.1
+latest

docs/docfiles/intro.rst

@@ -1,11 +1,17 @@
 Welcome to Data-parallel Control (dpctl)'s documentation!
 =========================================================
 
-Data-parallel control (dpctl) is a library that exposes SYCL and DPCPP to
-languages other than C++. Currently, dpctl provides SYCL bindings for C and
-Python making it possible to access SYCL runtime objects and methods from these
-languages. The SYCL functionality covered by dpctl includes the core SYCL
-runtime classes described in Section 4.6 of the
-`SYCL 2020 spec <https://www.khronos.org/registry/SYCL/specs/sycl-2020/html/sycl-2020.html#_sycl_runtime_classes>`_
-and USM memory management. dpctl also has experimental support for SYCL's
-``kernel`` and ``program`` classes.
+The data-parallel control (dpctl) library provides C and Python bindings for
+`SYCL 2020 <https://www.khronos.org/registry/SYCL/specs/sycl-2020/html/sycl-2020.html>`_.
+The SYCL 2020 features supported by dpctl are limited to those included by
+Intel's DPCPP compiler and specifically cover the SYCL runtime classes described
+in `Section 4.6 <https://www.khronos.org/registry/SYCL/specs/sycl-2020/html/sycl-2020.html#_sycl_runtime_classes>`_
+of the SYCL 2020 specification. Apart from the bindings for these runtime
+classes, dpctl includes bindings for SYCL USM memory allocators and
+deallocators. Dpctl's Python API provides classes that implement
+`Python buffer protocol <https://docs.python.org/3/c-api/buffer.html>`_
+using SYCL USM memory; making it possible to create Python objects that are
+backed by SYCL USM memory.
+
+Dpctl also supports the DPCPP ``ONEAPI::filter_selector`` extension and has
+experimental support for SYCL's ``kernel`` and ``program`` classes.