Add option to enable spec generation fast-mode

The new `--fast-mode` option to the `run.py` script disables the print
API section of the API listing mako template which causes the `generate`
CMake target to take an order of magnitude longer to complete.

Before these changes:

```
ninja generate  199.22s user 1.80s system 99% cpu 3:21.67 total
```

After these changes:

```
ninja generate  37.63s user 1.00s system 99% cpu 38.893 total
```

This greatly improves the iterative spec writing experience and can
opted by setting the CMake option `UR_ENABLE_FAST_SPEC_MODE=ON`.

Author: kbenzie

CMakeLists.txt

@@ -29,6 +29,7 @@ option(UR_BUILD_TESTS "Build unit tests." ON)
 option(UR_BUILD_TOOLS "build ur tools" ON)
 option(UR_FORMAT_CPP_STYLE "format code style of C++ sources" OFF)
 option(UR_DEVELOPER_MODE "enable developer checks, treats warnings as errors" OFF)
+option(UR_ENABLE_FAST_SPEC_MODE "enable fast specification generation mode" OFF)
 option(UR_USE_ASAN "enable AddressSanitizer" OFF)
 option(UR_USE_UBSAN "enable UndefinedBehaviorSanitizer" OFF)
 option(UR_USE_MSAN "enable MemorySanitizer" OFF)
@@ -292,7 +293,10 @@ if(UR_FORMAT_CPP_STYLE)
     # Generate source from the specification
     add_custom_target(generate-code USES_TERMINAL
         WORKING_DIRECTORY ${PROJECT_SOURCE_DIR}/scripts
-        COMMAND ${Python3_EXECUTABLE} run.py --api-json ${API_JSON_FILE} --clang-format=${CLANG_FORMAT}
+        COMMAND ${Python3_EXECUTABLE} run.py
+            --api-json ${API_JSON_FILE}
+            --clang-format=${CLANG_FORMAT}
+            $<$<BOOL:${UR_ENABLE_FAST_SPEC_MODE}>:--fast-mode>
         COMMAND ${Python3_EXECUTABLE} json2src.py --api-json ${API_JSON_FILE} ${PROJECT_SOURCE_DIR}
     )
 

README.md

@@ -122,6 +122,7 @@ List of options provided by CMake:
 | UR_BUILD_TOOLS | Build tools | ON/OFF | ON |
 | UR_FORMAT_CPP_STYLE | Format code style | ON/OFF | OFF |
 | UR_DEVELOPER_MODE | Treat warnings as errors and enables additional checks | ON/OFF | OFF |
+| UR_ENABLE_FAST_SPEC_MODE | Enable fast specification generation mode | ON/OFF | OFF |
 | UR_USE_ASAN | Enable AddressSanitizer | ON/OFF | OFF |
 | UR_USE_TSAN | Enable ThreadSanitizer | ON/OFF | OFF |
 | UR_USE_UBSAN | Enable UndefinedBehavior Sanitizer | ON/OFF | OFF |

scripts/generate_docs.py

@@ -86,7 +86,7 @@ def _make_ref(symbol, symbol_type, meta):
 """
     generate a valid reStructuredText file
 """
-def _generate_valid_rst(fin, fout, namespace, tags, ver, rev, meta):
+def _generate_valid_rst(fin, fout, namespace, tags, ver, rev, meta, fast_mode):
     ver=float(ver)
     enable = True
     code_block = False
@@ -185,13 +185,14 @@ def _generate_valid_rst(fin, fout, namespace, tags, ver, rev, meta):
                           ver=ver,
                           namespace=namespace,
                           tags=tags,
-                          meta=meta)
+                          meta=meta,
+                          fast_mode=fast_mode)
 
 """
 Entry-point:
     generate restructuredtext documents from templates
 """
-def generate_rst(docpath, section, namespace, tags, ver, rev, specs, meta):
+def generate_rst(docpath, section, namespace, tags, ver, rev, specs, meta, fast_mode):
     srcpath = os.path.join("./", section)
     dstpath = os.path.join(docpath, "source", section)
 
@@ -200,7 +201,7 @@ def generate_rst(docpath, section, namespace, tags, ver, rev, specs, meta):
     util.removeFiles(dstpath, "*.rst")
     for fin in util.findFiles(srcpath, "*.rst"):
         fout = os.path.join(dstpath, os.path.basename(fin))
-        loc += _generate_valid_rst(os.path.abspath(fin), fout, namespace, tags, ver, rev, meta)
+        loc += _generate_valid_rst(os.path.abspath(fin), fout, namespace, tags, ver, rev, meta, fast_mode)
 
     print("Generated %s lines of reStructuredText (rst).\n"%loc)
 
@@ -215,7 +216,8 @@ def generate_rst(docpath, section, namespace, tags, ver, rev, specs, meta):
             rev=rev,
             tags=tags,
             meta=meta,
-            specs=specs)
+            specs=specs,
+            fast_mode=fast_mode)
 
 """
 Entry-point:

scripts/run.py

@@ -1,3 +1,4 @@
+#!/usr/bin/env python3
 """
  Copyright (C) 2022 Intel Corporation
 
@@ -120,6 +121,7 @@ def main():
                         required=False, help="specification version to generate.")
     parser.add_argument("--api-json", type=str, default="unified_runtime.json", required=False, help="json output file for the spec")
     parser.add_argument("--clang-format", type=str, default="clang-format", required=False, help="path to clang-format executable")
+    parser.add_argument('--fast-mode', action='store_true', help='Disable sections which are slow to render')
     args = vars(parser.parse_args())
     args['rev'] = revision()
 
@@ -175,7 +177,7 @@ def main():
                     raise Exception("Failed to format ur_api.h")
 
                 if args['rst']:
-                    generate_docs.generate_rst(docpath, config['name'], config['namespace'], config['tags'], args['ver'], args['rev'], specs, input['meta'])
+                    generate_docs.generate_rst(docpath, config['name'], config['namespace'], config['tags'], args['ver'], args['rev'], specs, input['meta'], args['fast_mode'])
 
             if util.makeErrorCount():
                 print("\n%s Errors found during generation, stopping execution!"%util.makeErrorCount())

scripts/templates/api_listing.mako

@@ -265,6 +265,7 @@ ${th.make_type_name(n, tags, obj)}
 
 %endfor # s in specs
 
+%if not fast_mode:
 #################################################################
 ## Print API not part of the spec, needs to be generated separately
 #################################################################
@@ -359,3 +360,4 @@ Print Operators
     :project: UnifiedRuntime
     :outline:
 %endfor
+%endif