[SYCL][Doc] Move internal design docs

Move all the internal design documents to a separate directory.  This
declutters the "sycl/doc" directory, making it easier to find the
end-user documentation.  It also moves several documents out of
"sycl/doc/extensions" which were not actually extension specifications.

We decided that the "sycl/doc/dev" directory should hold BKMs (best
known methods) for developers, so rename it accordingly.

Author: gmlueck

sycl/ReleaseNotes.md

@@ -15,18 +15,18 @@ Release notes for commit range 4fc5ebe..bd68232
  - Added support for SYCL 2020 exceptions [5c0f748][eef07606][5af8c43d]
  - Added support for [SYCL_EXT_INTEL_BF16_CONVERSION extension](doc/extensions/experimental/SYCL_EXT_INTEL_BF16_CONVERSION.asciidoc)
    [8075463]
- - Added support for fallback implementation of [assert feature](doc/Assert.md)
+ - Added support for fallback implementation of [assert feature](doc/internal-design/Assert.md)
    [56c9ec4]
  - Added support SYCL 2020 `sycl::logical_and` and `sycl::logical_or` operators
    [6c077a0]
 ### Documentation
- - Added design document for [optional kernel features](doc/OptionalDeviceFeatures.md)
+ - Added design document for [optional kernel features](doc/internal-design/OptionalDeviceFeatures.md)
    [88cfe16]
  - Added [SYCL_INTEL_bf16_conversion extension document](doc/extensions/experimental/SYCL_EXT_INTEL_BF16_CONVERSION.asciidoc)
    [9f8cc3af]
  - Align [SYCL_EXT_ONEAPI_GROUP_MASK extension](doc/extensions/supported/SYCL_EXT_ONEAPI_SUB_GROUP_MASK.asciidoc)
    with SYCL 2020 specification [a06bd1fb]
- - Added [documentation](doc/SYCLInstrumentationUsingXPTI.md) of XPTI related
+ - Added [documentation](doc/internal-design/SYCLInstrumentationUsingXPTI.md) of XPTI related
    tracing in SYCL [1308fe7b]
  - Align `SYCL_EXT_ONEAPI_LOCAL_MEMORY` extension
    [document](doc/extensions/supported/SYCL_EXT_ONEAPI_LOCAL_MEMORY.asciidoc) with SYCL 2020
@@ -1104,7 +1104,7 @@ Release notes for commit range c9d50752..5d7e0925
   - The SYCL library doesn't guarantee stable API/ABI, so applications compiled
     with older version of the SYCL library may not work with new one.
     The workaround is to rebuild the application.
-    [ABI policy guide](doc/ABIPolicyGuide.md)
+    [ABI policy guide](doc/development-bkms/ABIPolicyGuide.md)
   - Using `cl::sycl::program` API to refer to a kernel defined in another
     translation unit leads to undefined behavior
   - Linkage errors with the following message:
@@ -1243,7 +1243,7 @@ Release notes for commit range 5976ff0..1fc0e4f
   - The SYCL library doesn't guarantee stable API/ABI, so applications compiled
     with older version of the SYCL library may not work with new one.
     The workaround is to rebuild the application.
-    [ABI policy guide](doc/ABIPolicyGuide.md)
+    [ABI policy guide](doc/development-bkms/ABIPolicyGuide.md)
   - Using `cl::sycl::program` API to refer to a kernel defined in another
     translation unit leads to undefined behavior
   - Linkage errors with the following message:
@@ -1431,7 +1431,7 @@ Release notes for the commit range 75b3dc2..5976ff0
   - The SYCL library doesn't guarantee stable API/ABI, so applications compiled
     with older version of the SYCL library may not work with new one.
     The workaround is to rebuild the application.
-    [ABI policy guide](doc/ABIPolicyGuide.md)
+    [ABI policy guide](doc/development-bkms/ABIPolicyGuide.md)
   - Using `cl::sycl::program` API to refer to a kernel defined in another
     translation unit leads to undefined behavior
   - Linkage errors with the following message:
@@ -1585,7 +1585,7 @@ Release notes for the commit range ba404be..24726df
   - The SYCL library doesn't guarantee stable API/ABI, so applications compiled
     with older version of the SYCL library may not work with new one.
     The workaround is to rebuild the application.
-    [ABI policy guide](doc/ABIPolicyGuide.md)
+    [ABI policy guide](doc/development-bkms/ABIPolicyGuide.md)
   - Using `cl::sycl::program` API to refer to a kernel defined in another
     translation unit leads to undefined behavior
   - Linkage errors with the following message:
@@ -1661,7 +1661,7 @@ Release notes for the commit range ba404be..67d3d9e
   - Updated prerequisites in GetStartedGuide(doc/GetStartedGuide.md) [5d0d034]
   - Published a [proposal](doc/extensions/KernelRHSAttributes/SYCL_INTEL_attribute_style.asciidoc)
     for function-type attributes (right-sided) for kernel attributes [5d5351b]
-  - The [compiler and runtime design doc](doc/CompilerAndRuntimeDesign.md) has
+  - The [compiler and runtime design doc](doc/internal-design/CompilerAndRuntimeDesign.md) has
     been updated to describe the CUDA target and reflect changed action graphs
     [91b597b] [212a26c]
   - [ExtendedAtomics documentation](doc/extensions/ExtendedAtomics/README.md)
@@ -1673,7 +1673,7 @@ Release notes for the commit range ba404be..67d3d9e
   - Published [device_specific_kernel_queries](doc/extensions/DeviceSpecificKernelQueries/SYCL_INTEL_device_specific_kernel_queries.asciidoc)
     extension which rephrases work group queries as device-specific kernel
     queries [4c07ff8]
-  - Added more information about the [plugin interface (PI)](doc/PluginInterface.md)
+  - Added more information about the [plugin interface (PI)](doc/internal-design/PluginInterface.md)
     [0614e9a]
   - [Contribution guidelines](../CONTRIBUTING.md) were simplified, now sign-off
     line is not required [7886fd8]
@@ -1736,7 +1736,7 @@ Release notes for the commit range ba404be..67d3d9e
   - The SYCL library doesn't guarantee stable API/ABI, so applications compiled
     with older version of the SYCL library may not work with new one.
     The workaround is to rebuild the application.
-    [ABI policy guide](doc/ABIPolicyGuide.md)
+    [ABI policy guide](doc/development-bkms/ABIPolicyGuide.md)
   - Using `cl::sycl::program` API to refer to a kernel defined in another
     translation unit leads to undefined behavior
   - Linkage errors with the following message:

sycl/doc/FAQ.md

@@ -58,7 +58,7 @@ compiler command-line interface in general, please refer to the
 To learn more about the concepts behind this flow, and the DPC++
 Compiler internals as such, we welcome you to study our
 [DPC++ Compiler and Runtime architecture design](
-CompilerAndRuntimeDesign.md) document.
+internal-design/CompilerAndRuntimeDesign.md) document.
 
 
 ## Using applications built with DPC++
@@ -150,7 +150,7 @@ debugging tools of your choice for the host device code.
 
 Furthermore, developers can extend capabilities of the DPC++ Runtime to
 non-OpenCL devices by writing correspondent plugins. To learn more, please
-check out our [Plugin Interface Guide](PluginInterface.md).
+check out our [Plugin Interface Guide](internal-design/PluginInterface.md).
 
 ### Q: DPC++ applications hang on Intel GPUs while working well on other devices
 **A:** One of the common reasons is Intel GPUs feature called "hang check".

sycl/doc/GetStartedGuide.md

@@ -54,7 +54,7 @@ docker run --name sycl_build -it -v /local/workspace/dir/:/src ghcr.io/intel/llv
 ```
 
 This command will start a terminal session, from which you can proceed with the
-instructions below. See [Docker BKMs](dev/DockerBKMs.md) for more info on Docker
+instructions below. See [Docker BKMs](development-bkms/DockerBKMs.md) for more info on Docker
 commands.
 
 ### Create DPC++ workspace
@@ -434,7 +434,7 @@ command:
 
 ### Obtain prerequisites for ahead of time (AOT) compilation
 
-[Ahead of time compilation](CompilerAndRuntimeDesign.md#ahead-of-time-aot-compilation)
+[Ahead of time compilation](internal-design/CompilerAndRuntimeDesign.md#ahead-of-time-aot-compilation)
 requires ahead of time compiler available in `PATH`. There is
 AOT compiler for each device type:
 
@@ -660,7 +660,7 @@ clang++ -fsycl -fsycl-targets=spir64_gen,spir64_x86_64 simple-sycl-app.cpp -o si
 
 Additionally, user can pass specific options of AOT compiler to
 the DPC++ compiler using ```-Xsycl-target-backend``` option, see
-[Device code formats](CompilerAndRuntimeDesign.md#device-code-formats) for
+[Device code formats](internal-design/CompilerAndRuntimeDesign.md#device-code-formats) for
 more. To find available options, execute:
 
 ```ocloc compile --help``` for GPU,

sycl/doc/conf.py

@@ -46,13 +46,33 @@
 # The suffix of source filenames.
 source_suffix = ['.rst', '.md']
 
-# Extensions are mostly in asciidoc which has poor support in Sphinx
-exclude_patterns = ['extensions/*']
+exclude_patterns = [
+    # Extensions are mostly in asciidoc which has poor support in Sphinx.
+    'extensions/*',
+
+    # Sphinx complains about syntax errors in these files.
+    'internal-design/DeviceLibExtensions.rst',
+    'internal-design/SYCLPipesLoweringToSPIRV.rst',
+    'internal-design/fpga_io_pipes_design.rst',
+    'internal-design/Reduction_status.md'
+]
 
 suppress_warnings = [ 'misc.highlighting_failure' ]
 
 def on_missing_reference(app, env, node, contnode):
-    new_target = "https://github.com/intel/llvm/tree/sycl/sycl/doc/" + node['reftarget']
+    # Get the directory that contains the *source* file of the link.  These
+    # files are always relative to the directory containing "conf.py"
+    # (<top>/sycl/doc).  For example, the file "sycl/doc/internal-design/foo.md"
+    # will have a directory "internal-design".
+    refdoc_components = node['refdoc'].split('/')
+    dirs = '/'.join(refdoc_components[:-1])
+    if dirs: dirs += '/'
+
+    # A missing reference usually occurs when the target file of the link is
+    # not processed by Sphinx.  Compensate by creating a link that goes to the
+    # file's location in the GitHub repo.
+    new_target = "https://github.com/intel/llvm/tree/sycl/sycl/doc/" + dirs + \
+        node['reftarget']
 
     newnode = nodes.reference('', '', internal=False, refuri=new_target)
     newnode.append(contnode)

sycl/doc/ABIPolicyGuide.md renamed to sycl/doc/development-bkms/ABIPolicyGuide.md

@@ -118,4 +118,4 @@ Whenever you need to change the existing ABI, please, follow these steps:
 1. If there is a need to add a new field in `sycl::handler` or/and
    `sycl::detail::CG` classes it can be done without breaking ABI using the
    approach described in the comment at the beggining of
-   [cg.hpp](../include/CL/sycl/detail/cg.hpp)
+   [cg.hpp](../../include/CL/sycl/detail/cg.hpp)

sycl/doc/dev/DockerBKMs.md renamed to sycl/doc/development-bkms/DockerBKMs.md

@@ -81,7 +81,7 @@ extension.
 
 ##### Features not supported with ESIMD extension:
 - The [C and C++ Standard libraries support](../supported/C-CXX-StandardLibrary.rst)
-- The [Device library extensions](https://github.com/intel/llvm/blob/sycl/sycl/doc/extensions/C-CXX-StandardLibrary/DeviceLibExtensions.rst)
+- The [Device library extensions](../../../internal-design/DeviceLibExtensions.rst)
 - Host device
 
 ##### Unsupported standard SYCL APIs:

sycl/doc/extensions/experimental/SYCL_EXT_INTEL_ESIMD/README.md

@@ -238,8 +238,8 @@ Device compiler
 Device compiler is free to implement these `__devicelib_*` functions.
 In order to indicate support for a particular set of functions,
 underlying runtime have to support the corresponding OpenCL (PI)
-extension. See ``DeviceLibExtensions.rst`` for a list of supported
-functions and corresponding extensions.
+extension. See ``../../internal-design/DeviceLibExtensions.rst`` for
+a list of supported functions and corresponding extensions.
 
 Fallback implementation
 =======================

sycl/doc/extensions/supported/C-CXX-StandardLibrary.rst

@@ -16,6 +16,7 @@ Using oneAPI DPC++ for Application Development
    FAQ
    User API Reference <https://intel.github.io/llvm-docs/doxygen/group__sycl__api.html>
    EnvironmentVariables
+   MultiTileCardWithLevelZero
 
 Developing oneAPI DPC++ Compiler
 --------------------------------
@@ -26,27 +27,26 @@ Developing oneAPI DPC++ Compiler
    API Reference <https://intel.github.io/llvm-docs/doxygen>
    Clang Documentation <https://intel.github.io/llvm-docs/clang>
    Clang API Reference <https://intel.github.io/llvm-docs/clang_doxygen>
-   CompilerAndRuntimeDesign
-   KernelParameterPassing
-   PluginInterface
-   ABIPolicyGuide
-   SpecializationConstants
-   KernelProgramCache
-   GlobalObjectsInRuntime
-   LinkedAllocations
-   Assert
-   SharedLibraries
-   MultiTileCardWithLevelZero
-   OptionalDeviceFeatures
-   SYCLInstrumentationUsingXPTI
-   ITTAnnotations
-   DeviceGlobal
-   CompileTimeProperties
+   internal-design/CompilerAndRuntimeDesign
+   internal-design/KernelParameterPassing
+   internal-design/PluginInterface
+   internal-design/SpecializationConstants
+   internal-design/KernelProgramCache
+   internal-design/GlobalObjectsInRuntime
+   internal-design/LinkedAllocations
+   internal-design/Assert
+   internal-design/SharedLibraries
+   internal-design/OptionalDeviceFeatures
+   internal-design/SYCLInstrumentationUsingXPTI
+   internal-design/ITTAnnotations
+   internal-design/DeviceGlobal
+   internal-design/CompileTimeProperties
 
 Development BKMs
 ~~~~~~~~~~~~~~~~
 
 .. toctree::
    :maxdepth: 1
 
-   dev/DockerBKMs
+   development-bkms/DockerBKMs
+   development-bkms/ABIPolicyGuide