Update for Vulkan-Docs 1.2.131

registry/cgenerator.py

@@ -1,6 +1,6 @@
 #!/usr/bin/python3 -i
 #
-# Copyright (c) 2013-2019 The Khronos Group Inc.
+# Copyright (c) 2013-2020 The Khronos Group Inc.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.

registry/conventions.py

@@ -1,6 +1,6 @@
 #!/usr/bin/python3 -i
 #
-# Copyright (c) 2013-2019 The Khronos Group Inc.
+# Copyright (c) 2013-2020 The Khronos Group Inc.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -81,10 +81,8 @@ class ConventionsBase:
         self._type_prefix = None
 
     def formatExtension(self, name):
-        """Mark up a name as an extension for the spec.
+        """Mark up a name as an extension for the spec."""
-
+        return '`<<{}>>`'.format(name)
-        Must implement."""
-        raise NotImplementedError
 
     @property
     def null(self):
@@ -321,3 +319,34 @@ class ConventionsBase:
         be skipped for a command."""
 
         return False
+
+    @property
+    def generate_index_terms(self):
+        """Return True if asiidoctor index terms should be generated as part
+           of an API interface from the docgenerator."""
+
+        return False
+
+    @property
+    def generate_enum_table(self):
+        """Return True if asciidoctor tables describing enumerants in a
+           group should be generated as part of group generation."""
+        return False
+
+    def extension_include_string(self, ext):
+        """Return format string for include:: line for an extension appendix
+           file. ext is an object with the following members:
+            - name - extension string string
+            - vendor - vendor portion of name
+            - barename - remainder of name
+
+        Must implement."""
+        raise NotImplementedError
+
+    @property
+    def refpage_generated_include_path(self):
+        """Return path relative to the generated reference pages, to the
+           generated API include files.
+
+        Must implement."""
+        raise NotImplementedError

registry/generator.py

@@ -1,6 +1,6 @@
 #!/usr/bin/python3 -i
 #
-# Copyright (c) 2013-2019 The Khronos Group Inc.
+# Copyright (c) 2013-2020 The Khronos Group Inc.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -21,7 +21,9 @@ import io
 import os
 import pdb
 import re
+import shutil
 import sys
+import tempfile
 try:
     from pathlib import Path
 except ImportError:
@@ -46,6 +48,7 @@ def noneStr(s):
         return s
     return ""
 
+
 def enquote(s):
     """Return string argument with surrounding quotes,
       for serialization into Python code."""
@@ -53,16 +56,14 @@ def enquote(s):
         return "'{}'".format(s)
     return None
 
-def regSortCategoryKey(feature):
-    """Primary sort key for regSortFeatures.
 
+def regSortCategoryKey(feature):
+    """Sort key for regSortFeatures.
     Sorts by category of the feature name string:
 
     - Core API features (those defined with a `<feature>` tag)
     - ARB/KHR/OES (Khronos extensions)
-    - other       (EXT/vendor extensions)
+    - other       (EXT/vendor extensions)"""
-
-    This may need to change for some APIs"""
 
     if feature.elem.tag == 'feature':
         return 0
@@ -73,28 +74,27 @@ def regSortCategoryKey(feature):
 
     return 2
 
+
 def regSortOrderKey(feature):
-    """Secondary sort key for regSortFeatures.
+    """Sort key for regSortFeatures - key is the sortorder attribute."""
-    Sorts by sortorder attribute."""
 
     return feature.sortorder
 
-def regSortFeatureVersionKey(feature):
-    """Tertiary sort key for regSortFeatures.
 
-    Sorts by feature version.
+def regSortFeatureVersionKey(feature):
+    """Sort key for regSortFeatures - key is the feature version.
     `<extension>` elements all have version number 0."""
 
     return float(feature.versionNumber)
 
-def regSortExtensionNumberKey(feature):
-    """Last sort key for regSortFeatures.
 
-    Sorts by extension number.
+def regSortExtensionNumberKey(feature):
+    """Sort key for regSortFeatures - key is the extension number.
     `<feature>` elements all have extension number 0."""
 
     return int(feature.number)
 
+
 def regSortFeatures(featureList):
     """Default sort procedure for features.
 
@@ -107,6 +107,7 @@ def regSortFeatures(featureList):
     featureList.sort(key=regSortOrderKey)
     featureList.sort(key=regSortCategoryKey)
 
+
 class GeneratorOptions:
     """Base class for options used during header/documentation production.
 
@@ -557,17 +558,9 @@ class OutputGenerator:
 
         self.conventions = genOpts.conventions
 
-        # Open specified output file. Not done in constructor since a
+        # Open a temporary file for accumulating output.
-        # Generator can be used without writing to a file.
         if self.genOpts.filename is not None:
-            if sys.platform == 'win32':
+            self.outFile = tempfile.NamedTemporaryFile(mode='w', encoding='utf-8', delete=False)
-                directory = Path(self.genOpts.directory)
-                if not Path.exists(directory):
-                    os.makedirs(directory)
-                self.outFile = (directory / self.genOpts.filename).open('w', encoding='utf-8')
-            else:
-                filename = self.genOpts.directory + '/' + self.genOpts.filename
-                self.outFile = io.open(filename, 'w', encoding='utf-8')
         else:
             self.outFile = sys.stdout
 
@@ -581,6 +574,15 @@ class OutputGenerator:
         self.outFile.flush()
         if self.outFile != sys.stdout and self.outFile != sys.stderr:
             self.outFile.close()
+
+        # On successfully generating output, move the temporary file to the
+        # target file.
+        if self.genOpts.filename is not None:
+            if sys.platform == 'win32':
+                directory = Path(self.genOpts.directory)
+                if not Path.exists(directory):
+                    os.makedirs(directory)
+            shutil.move(self.outFile.name, self.genOpts.directory + '/' + self.genOpts.filename)
         self.genOpts = None
 
     def beginFeature(self, interface, emit):
@@ -707,6 +709,7 @@ class OutputGenerator:
         or structure/union member).
 
         - param - Element (`<param>` or `<member>`) to identify"""
+
         # Allow for missing <name> tag
         newLen = 0
         paramdecl = '    ' + noneStr(param.text)

registry/genvk.py

@@ -1,6 +1,6 @@
 #!/usr/bin/python3
 #
-# Copyright (c) 2013-2019 The Khronos Group Inc.
+# Copyright (c) 2013-2020 The Khronos Group Inc.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -103,7 +103,7 @@ def makeGenOpts(args):
     # Copyright text prefixing all headers (list of strings).
     prefixStrings = [
         '/*',
-        '** Copyright (c) 2015-2019 The Khronos Group Inc.',
+        '** Copyright (c) 2015-2020 The Khronos Group Inc.',
         '**',
         '** Licensed under the Apache License, Version 2.0 (the "License");',
         '** you may not use this file except in compliance with the License.',

registry/reg.py

@@ -1,6 +1,6 @@
 #!/usr/bin/python3 -i
 #
-# Copyright (c) 2013-2019 The Khronos Group Inc.
+# Copyright (c) 2013-2020 The Khronos Group Inc.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -22,6 +22,7 @@ import xml.etree.ElementTree as etree
 from collections import defaultdict, namedtuple
 from generator import OutputGenerator, write
 
+
 def matchAPIProfile(api, profile, elem):
     """Return whether an API and profile
     being generated matches an element's profile
@@ -79,11 +80,6 @@ def matchAPIProfile(api, profile, elem):
             return False
     return True
 
-# def printKeys(msg, elem):
-#     """Print all the keys in an Element - only for diagnostics"""
-#     print('printKeys:', msg, file=sys.stderr)
-#     for key in elem.keys():
-#         print('    {} -> {}'.format(key, elem.get(key)), file=sys.stderr)
 
 class BaseInfo:
     """Base class for information about a registry feature
@@ -205,6 +201,7 @@ class CmdInfo(BaseInfo):
         self.additionalValidity = []
         self.removedValidity = []
 
+
 class FeatureInfo(BaseInfo):
     """Registry information about an API <feature>
     or <extension>."""
@@ -221,10 +218,12 @@ class FeatureInfo(BaseInfo):
         """explicit numeric sort key within feature and extension groups.
         Defaults to 0."""
 
+        # Determine element category (vendor). Only works
+        # for <extension> elements.
         if elem.tag == 'feature':
             # Element category (vendor) is meaningless for <feature>
             self.category = 'VERSION'
-            "category, e.g. VERSION or khr/vendor tag"
+            """category, e.g. VERSION or khr/vendor tag"""
 
             self.version = elem.get('name')
             """feature name string"""
@@ -237,7 +236,7 @@ class FeatureInfo(BaseInfo):
             self.number = "0"
             self.supported = None
         else:
-            # Extract vendor portion of VK_<vendor>_<name>
+            # Extract vendor portion of <APIprefix>_<vendor>_<name>
             self.category = self.name.split('_', 2)[1]
             self.version = "0"
             self.versionNumber = "0"
@@ -294,7 +293,7 @@ class Registry:
         or False to just treat them as emitted"""
 
         self.breakPat = None
-        "regexp pattern to break on when generatng names"
+        "regexp pattern to break on when generating names"
         # self.breakPat     = re.compile('VkFenceImportFlagBits.*')
 
         self.requiredextensions = []  # Hack - can remove it after validity generator goes away
@@ -353,10 +352,7 @@ class Registry:
             if not dictionary[key].compareElem(info, infoName):
                 self.gen.logMsg('warn', 'Attempt to redefine', key,
                                 '(this should not happen)')
-                # printKeys('old element', dictionary[key].elem)
-                # printKeys('new element', info.elem)
             else:
-                # Benign redefinition - intentional cases exist.
                 True
         else:
             dictionary[key] = info

registry/spec_tools/util.py

@@ -1,6 +1,6 @@
 """Utility functions not closely tied to other spec_tools types."""
 # Copyright (c) 2018-2019 Collabora, Ltd.
-# Copyright (c) 2013-2019 The Khronos Group Inc.
+# Copyright (c) 2013-2020 The Khronos Group Inc.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.

registry/vkconventions.py

@@ -1,6 +1,6 @@
 #!/usr/bin/python3 -i
 #
-# Copyright (c) 2013-2019 The Khronos Group Inc.
+# Copyright (c) 2013-2020 The Khronos Group Inc.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -18,6 +18,7 @@
 # used in generation.
 
 import re
+import os
 
 from conventions import ConventionsBase
 
@@ -52,10 +53,6 @@ MAIN_RE = re.compile(
 
 
 class VulkanConventions(ConventionsBase):
-    def formatExtension(self, name):
-        """Mark up a name as an extension for the spec."""
-        return '`<<{}>>`'.format(name)
-
     @property
     def null(self):
         """Preferred spelling of NULL."""
@@ -214,8 +211,8 @@ class VulkanConventions(ConventionsBase):
 
     @property
     def spec_reflow_path(self):
-        """Return the relative path to the spec source folder to reflow"""
+        """Return the path to the spec source folder to reflow"""
-        return '.'
+        return os.getcwd()
 
     @property
     def spec_no_reflow_dirs(self):
@@ -246,3 +243,19 @@ class VulkanConventions(ConventionsBase):
         generate a VK_ERROR_FORMAT_NOT_SUPPORTED code."""
 
         return True
+
+    def extension_include_string(self, ext):
+        """Return format string for include:: line for an extension appendix
+           file. ext is an object with the following members:
+            - name - extension string string
+            - vendor - vendor portion of name
+            - barename - remainder of name"""
+
+        return 'include::{{appendices}}/{name}{suffix}[]'.format(
+                name=ext.name, suffix=self.file_suffix)
+
+    @property
+    def refpage_generated_include_path(self):
+        """Return path relative to the generated reference pages, to the
+           generated API include files."""
+        return "{generated}"