[UR] Add script to generate experimental feature template files

Author: Petr Vesely

scripts/add_experimental_feature.py

@@ -0,0 +1,59 @@
+"""
+ Copyright (C) 2023 Intel Corporation
+
+ Part of the Unified-Runtime Project, under the Apache License v2.0 with LLVM Exceptions.
+ See LICENSE.TXT
+ SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+
+"""
+import argparse
+import sys
+from util import makoWrite
+import re
+
+def verify_kebab_case(input: str) -> bool:
+    # kebab case regex from https://github.com/expandjs/expandjs/blob/master/lib/kebabCaseRegex.js
+    kebab_case_re = r"^([a-z](?![\d])|[\d](?![a-z]))+(-?([a-z](?![\d])|[\d](?![a-z])))*$|^$"
+    pattern = re.compile(kebab_case_re)
+    if pattern.match(input) is None:
+        return False
+    return True
+
+
+def main():
+
+    argParser = argparse.ArgumentParser()
+    argParser.add_argument("name", help="must be lowercase and kebab case i.e. command-buffer", type=str)
+    args = argParser.parse_args()
+
+    if not verify_kebab_case(args.name):
+        print("Name must be lowercase and kebab-case i.e. command-buffer.")
+        sys.exit(1)
+
+    exp_feat_name = args.name
+    
+    out_yml_name = "exp-%s.yml" % exp_feat_name
+    out_rst_name = "EXP-%s.rst" % exp_feat_name.upper()
+
+    yaml_template_path = "./scripts/templates/%s" % "exp_feat.yml.mako"
+    rst_template_path = "./scripts/templates/%s" % "exp_feat.rst.mako"
+    out_yml_path = "./scripts/core/%s" % out_yml_name
+    out_rst_path = "./scripts/core/%s" % out_rst_name
+
+    makoWrite(yaml_template_path, out_yml_path, name=exp_feat_name)
+    makoWrite(rst_template_path, out_rst_path, name=exp_feat_name)
+
+
+    print("Successfully generated the template files needed for %s." % exp_feat_name)
+    print("""
+You can now implement your feature in the following files:
+    * %s 
+    * %s
+""" % (out_yml_name, out_rst_name))
+
+
+if __name__ == "__main__":
+    try:
+        main()
+    except KeyboardInterrupt:
+        exit(130)

scripts/core/CONTRIB.rst

@@ -207,6 +207,15 @@ Experimental features *must* be defined in two new files, where
 *   ``scripts/core/exp-<feature>.yml`` defines the interface as an input to
     `Generating Source`_.
 
+To simplify this process please use the provided python script which will create
+these template files for you. You can then freely modify these files to 
+implement your experimental feature. 
+
+.. code-block:: console
+
+    $ python scripts/add_experimental_feature.py <name-of-your-experimental-feature>
+
+
 Naming Convention
 -----------------
 

scripts/templates/exp_feat.rst.mako

@@ -0,0 +1,28 @@
+<%text><%
+    OneApi=tags['$OneApi']
+    x=tags['$x']
+    X=x.upper()
+%>
+</%text>
+.. _experimental-${name}
+
+================================================================================
+${" ".join(name.split("-")).title()}
+================================================================================
+
+
+.. warning:
+
+    Experimental features:
+
+    *   May be replaced, updated, or removed at any time.
+    *   Do not require maintaining API/ABI stability of their own additions over
+        time.
+    *   Do not require conformance testing of their own additions.
+
+
+.. todo::
+
+    In the following sections you should explain and document the motivation of 
+    the experimental feature, the additions made to the specification along with
+    its valid usage.

scripts/templates/exp_feat.yml.mako

@@ -0,0 +1,22 @@
+<%
+import re
+from templates import helper as th
+import datetime
+%><%
+    year_now=datetime.date.today().year
+%>#
+# Copyright (C) ${year_now} Intel Corporation
+#
+# Part of the Unified-Runtime Project, under the Apache License v2.0 with LLVM Exceptions.
+# See LICENSE.TXT
+# SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+#
+# See YaML.md for syntax definition
+#
+--- #--------------------------------------------------------------------------
+type: header
+desc: "Intel $OneApi Unified Runtime Experimental APIs for ${" ".join(name.split("-")).title()}"
+ordinal: "99"
+--- #--------------------------------------------------------------------------
+## TODO - Add you experimental feature additions here
+##      - refer to YaML.md for the syntax defintion