[SYCL][Doc] Update Sphinx and dependencies (#4340)

recommonmark (which was used for mardown rendering) is deprecated and
will no longer be actively maintained. MyST and Sphinx 4 offer better
Markdown and C++ syntax highlighting support.

Author: alexbatashev

.github/workflows/gh_pages.yml

@@ -16,7 +16,7 @@ jobs:
     - name: Install deps
       run: |
         sudo apt-get install -y doxygen graphviz ssh ninja-build
-        sudo pip3 install 'sphinx==3.0.0' 'recommonmark==0.6.0' 'sphinx_markdown_tables==0.0.12'
+        sudo pip3 install 'sphinx==4.1.2' 'myst-parser==0.15.1'
     - name: Build Docs
       run: |
         mkdir -p $GITHUB_WORKSPACE/build

sycl/doc/PreprocessorMacros.md

@@ -2,38 +2,38 @@
 
 This file describes macros that have effect on SYCL compiler and run-time.
 
-### `RESTRICT_WRITE_ACCESS_TO_CONSTANT_PTR`
+- **RESTRICT_WRITE_ACCESS_TO_CONSTANT_PTR**
 
-The spec assumes that the SYCL implementation does address space deduction.
-However, for our implementation, the deduction is performed in the middle end,
-where it's hard to provide user friendly diagnositcs.
-Due to these problems writing to raw pointers obtained from `constant_ptr` is
-not diagnosed now.
-The user can enable diagnostics upon writing to such pointers via enabling the
-`RESTRICT_WRITE_ACCESS_TO_CONSTANT_PTR` macro.
-This allows `constant_ptr` to use constant pointers as underlying
-pointer types. Thus, conversions from `constant_ptr` to raw pointers will return
-constant pointers and writing to const pointers will be diagnosed by the
-front-end.
-This behavior is not following the SYCL spec since `constant_ptr` conversions to
-the underlying pointer types return pointers without any additional qualifiers
-so it's disabled by default.
+  The spec assumes that the SYCL implementation does address space deduction.
+  However, for our implementation, the deduction is performed in the middle end,
+  where it's hard to provide user friendly diagnositcs.
+  Due to these problems writing to raw pointers obtained from `constant_ptr` is
+  not diagnosed now.
+  The user can enable diagnostics upon writing to such pointers via enabling the
+  `RESTRICT_WRITE_ACCESS_TO_CONSTANT_PTR` macro.
+  This allows `constant_ptr` to use constant pointers as underlying
+  pointer types. Thus, conversions from `constant_ptr` to raw pointers will return
+  constant pointers and writing to const pointers will be diagnosed by the
+  front-end.
+  This behavior is not following the SYCL spec since `constant_ptr` conversions to
+  the underlying pointer types return pointers without any additional qualifiers
+  so it's disabled by default.
 
-### `DISABLE_SYCL_INSTRUMENTATION_METADATA`
+- **DISABLE_SYCL_INSTRUMENTATION_METADATA**
 
-This macro is used to disable passing of code location information to public
-methods.
+  This macro is used to disable passing of code location information to public
+  methods.
 
-### `SYCL2020_DISABLE_DEPRECATION_WARNINGS`
+- **SYCL2020_DISABLE_DEPRECATION_WARNINGS**
 
-Disables warnings coming from usage of SYCL 1.2.1 APIs, that are deprecated in
-SYCL 2020.
+  Disables warnings coming from usage of SYCL 1.2.1 APIs, that are deprecated in
+  SYCL 2020.
 
-### `SYCL_DISABLE_DEPRECATION_WARNINGS`
+- **SYCL_DISABLE_DEPRECATION_WARNINGS**
 
-Disables all deprecation warnings in SYCL runtime headers, including SYCL 1.2.1 deprecations.
+  Disables all deprecation warnings in SYCL runtime headers, including SYCL 1.2.1 deprecations.
 
-### Version macros
+## Version macros
 
 - `__LIBSYCL_MAJOR_VERSION` is set to SYCL runtime library major version.
 - `__LIBSYCL_MINOR_VERSION` is set to SYCL runtime library minor version.

sycl/doc/conf.py

@@ -32,8 +32,7 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
-    'recommonmark',
-    'sphinx_markdown_tables'
+    'myst_parser'
 ]
 
 # The name of the Pygments (syntax highlighting) style to use.
@@ -49,13 +48,11 @@
 # Extensions are mostly in asciidoc which has poor support in Sphinx
 exclude_patterns = ['extensions/*']
 
-source_parsers = {'.md': 'recommonmark.parser.CommonMarkParser'}
-
 suppress_warnings = [ 'misc.highlighting_failure' ]
 
 def on_missing_reference(app, env, node, contnode):
     if node['reftype'] == 'any':
-        contnode['refuri'] = "https://github.com/intel/llvm/tree/sycl/sycl/doc/" + contnode['refuri']
+        contnode['refuri'] = "https://github.com/intel/llvm/tree/sycl/sycl/doc/" + node['reftarget']
         return contnode
     else:
         return None