Merge pull request oneapi-src#653 from veselypeta/petr/608/support-va…

…lidation-over-multiple-lines

[UR] Support multi-line functions in rst files

scripts/core/EXP-COMMAND-BUFFER.rst

@@ -59,7 +59,8 @@ returned list of supported extensions.
 
     // Retrieve extension string 
     std::unique_ptr<char[]> returnedExtensions(new char[returnedSize]);
-    ${x}DeviceGetInfo(hDevice, ${X}_DEVICE_INFO_EXTENSIONS, returnedSize, returnedExtensions.get(), nullptr);
+    ${x}DeviceGetInfo(hDevice, ${X}_DEVICE_INFO_EXTENSIONS, returnedSize, 
+                      returnedExtensions.get(), nullptr);
     
     std::string_view ExtensionsString(returnedExtensions.get());
     bool CmdBufferSupport = 
@@ -117,11 +118,15 @@ were obtained from.
     // Append a memcpy with no sync-point dependencies
     ${x}_exp_command_buffer_sync_point_t syncPoint;
 
-    ${x}CommandBufferAppendMemcpyUSMExp(hCommandBuffer, pDst, pSrc, size, 0, nullptr, &syncPoint);
+    ${x}CommandBufferAppendMemcpyUSMExp(hCommandBuffer, pDst, pSrc, size, 0, 
+                                        nullptr, &syncPoint);
     
     // Append a kernel launch with syncPoint as a dependency, ignore returned
     // sync-point
-    ${x}CommandBufferAppendKernelLaunchExp(hCommandBuffer, hKernel, workDim, pGlobalWorkOffset, pGlobalWorkSize, pLocalWorkSize, 1, &syncPoint, nullptr);
+    ${x}CommandBufferAppendKernelLaunchExp(hCommandBuffer, hKernel, workDim, 
+                                           pGlobalWorkOffset, pGlobalWorkSize, 
+                                           pLocalWorkSize, 1, &syncPoint, 
+                                           nullptr);
 
 Enqueueing Command-Buffers
 --------------------------------------------------------------------------------

scripts/core/PROG.rst

@@ -60,11 +60,13 @@ Initialization and Discovery
 
     // Get number of total GPU devices in the platform
     uint32_t deviceCount = 0;
-    ${x}DeviceGet(platforms[0], ${X}_DEVICE_TYPE_GPU, &deviceCount, nullptr, nullptr);
+    ${x}DeviceGet(platforms[0], ${X}_DEVICE_TYPE_GPU, &deviceCount, nullptr, 
+                  nullptr);
 
     // Get handles of all GPU devices in the platform
     std::vector<${x}_device_handle_t> devices(deviceCount);
-    ${x}DeviceGet(platforms[0], ${X}_DEVICE_TYPE_GPU, &deviceCount, devices.data(), devices.size());
+    ${x}DeviceGet(platforms[0], ${X}_DEVICE_TYPE_GPU, &deviceCount, 
+                  devices.data(), devices.size());
 
 Device handle lifetime
 ----------------------
@@ -97,15 +99,17 @@ In case where the info size is only known at runtime then two calls are needed,
 
     // Size is known beforehand
     ${x}_device_type_t deviceType;
-    ${x}DeviceGetInfo(hDevice, ${X}_DEVICE_INFO_TYPE, sizeof(${x}_device_type_t), &deviceType, nullptr);
+    ${x}DeviceGetInfo(hDevice, ${X}_DEVICE_INFO_TYPE, 
+                      sizeof(${x}_device_type_t), &deviceType, nullptr);
 
     // Size is only known at runtime
     size_t infoSize;
     ${x}DeviceGetInfo(hDevice, ${X}_DEVICE_INFO_NAME, 0, &infoSize, nullptr);
     
     std::string deviceName;
     DeviceName.resize(infoSize);
-    ${x}DeviceGetInfo(hDevice, ${X}_DEVICE_INFO_NAME, infoSize, deviceName.data(), nullptr);
+    ${x}DeviceGetInfo(hDevice, ${X}_DEVICE_INFO_NAME, infoSize, 
+                      deviceName.data(), nullptr);
 
 Device partitioning into sub-devices
 ------------------------------------
@@ -133,7 +137,8 @@ fixed part of the parent device, which can explicitly be programmed individually
 
     if (count > 0) {
         subDevices.resize(count);
-        ${x}DevicePartition(Device, &properties, count, &subDevices.data(), nullptr);
+        ${x}DevicePartition(Device, &properties, count, &subDevices.data(), 
+                            nullptr);
     }
 
 The returned sub-devices may be requested for further partitioning into sub-sub-devices, and so on.
@@ -158,7 +163,8 @@ events, and programs are explicitly created against a context. A trivial work wi
 
     uint32_t deviceCount = 1;
     ${x}_device_handle_t hDevice;
-    ${x}DeviceGet(hPlatform, ${X}_DEVICE_TYPE_GPU, &deviceCount, &hDevice, nullptr);
+    ${x}DeviceGet(hPlatform, ${X}_DEVICE_TYPE_GPU, &deviceCount, &hDevice, 
+                  nullptr);
 
     // Create a context
     ${x}_context_handle_t hContext;
@@ -234,14 +240,16 @@ queue is created.
 
     // Create an out of order queue for hDevice in hContext
     ${x}_queue_handle_t hQueue;
-    ${x}QueueCreate(hContext, hDevice, ${X}_QUEUE_FLAG_OUT_OF_ORDER_EXEC_MODE_ENABLE, &hQueue);
+    ${x}QueueCreate(hContext, hDevice, 
+                    ${X}_QUEUE_FLAG_OUT_OF_ORDER_EXEC_MODE_ENABLE, &hQueue);
 
-    // Lanuch a kernel with 3D workspace partitioning
+    // Launch a kernel with 3D workspace partitioning
     const uint32_t nDim = 3;
     const size_t gWorkOffset = {0, 0, 0};
     const size_t gWorkSize = {128, 128, 128};
     const size_t lWorkSize = {1, 8, 8}; 
-    ${x}EnqueueKernelLaunch(hQueue, hKernel, nDim, gWorkOffset, gWorkSize, lWorkSize, 0, nullptr, nullptr);
+    ${x}EnqueueKernelLaunch(hQueue, hKernel, nDim, gWorkOffset, gWorkSize, 
+                            lWorkSize, 0, nullptr, nullptr);
 
 Queue object lifetime
 ---------------------

scripts/generate_docs.py

@@ -96,7 +96,8 @@ def _generate_valid_rst(fin, fout, namespace, tags, ver, rev, meta):
     error = False
 
     outlines = []
-    for iline, line in enumerate(util.textRead(fin)):
+    iter = enumerate(util.textRead(fin))
+    for iline, line in iter:
 
         if re.match(RE_ENABLE, line) or re.match(RE_PYCODE_BLOCK_END, line):
             enable = True
@@ -136,6 +137,17 @@ def _generate_valid_rst(fin, fout, namespace, tags, ver, rev, meta):
                         continue
 
                     if code_block and 'function' == symbol_type:
+                        # If function is split across multiple lines
+                        # then join lines until a ';' is encountered.
+                        try:
+                            line = line.strip()
+                            while not line.endswith(';'):
+                                _, n_line = next(iter)
+                                line = line + n_line.strip()
+                        except StopIteration:
+                            print(f"Function {line[:100]} was not terminated by a ';' character.")
+                            error = True
+
                         words = re.sub(RE_EXTRACT_PARAMS, r"\1", line)
                         words = line.split(",")
                         if len(words) != len(meta['function'][symbol]['params']):