119 lines
5.0 KiB
Python
119 lines
5.0 KiB
Python
#!/usr/bin/python3 -i
|
|
#
|
|
# Copyright 2013-2021 The Khronos Group Inc.
|
|
#
|
|
# SPDX-License-Identifier: Apache-2.0
|
|
|
|
import re
|
|
from generator import OutputGenerator, write
|
|
|
|
def interfaceDocSortKey(item):
|
|
if item == None:
|
|
return '\0'
|
|
else:
|
|
return item.casefold()
|
|
|
|
class InterfaceDocGenerator(OutputGenerator):
|
|
"""InterfaceDocGenerator - subclass of OutputGenerator.
|
|
Generates AsciiDoc includes of the interfaces added by a an API version
|
|
or extension."""
|
|
|
|
def __init__(self, *args, **kwargs):
|
|
super().__init__(*args, **kwargs)
|
|
self.features = []
|
|
|
|
def beginFile(self, genOpts):
|
|
OutputGenerator.beginFile(self, genOpts)
|
|
|
|
# Create subdirectory, if needed
|
|
self.makeDir(self.genOpts.directory)
|
|
|
|
def beginFeature(self, interface, emit):
|
|
# Start processing in superclass
|
|
OutputGenerator.beginFeature(self, interface, emit)
|
|
|
|
self.features.append( self.featureName )
|
|
|
|
def endFeature(self):
|
|
# Finish processing in superclass
|
|
OutputGenerator.endFeature(self)
|
|
|
|
def writeNewInterfaces(self, feature, key, title, markup, fp):
|
|
dict = self.featureDictionary[feature][key]
|
|
|
|
parentmarkup = markup
|
|
if key == 'enumconstant':
|
|
parentmarkup = 'elink:'
|
|
|
|
if dict:
|
|
write('=== ' + title, file=fp)
|
|
write('',file=fp)
|
|
|
|
# Loop through required blocks, sorted so they start with "core" features
|
|
for required in sorted(dict, key = interfaceDocSortKey):
|
|
if required is not None:
|
|
requiredlink = 'apiext:' + required
|
|
match = re.search("[A-Z]+_VERSION_([0-9]+)_([0-9]+)",required)
|
|
if match is not None:
|
|
major = match.group(1)
|
|
minor = match.group(2)
|
|
version = major + '.' + minor
|
|
requiredlink = '<<versions-' + version + ', Version ' + version + '>>'
|
|
|
|
write('ifdef::' + required + '[]', file=fp)
|
|
write('If ' + requiredlink + ' is supported:', file=fp)
|
|
write('',file=fp)
|
|
|
|
# Commands are relatively straightforward
|
|
if key == 'command':
|
|
for api in sorted(dict[required]):
|
|
write(' * ' + markup + api, file=fp)
|
|
# Types and constants are potentially parented, so need to handle that
|
|
else:
|
|
# Loop through parents, sorted so they start with unparented items
|
|
for parent in sorted(dict[required], key = interfaceDocSortKey):
|
|
parentstring = ''
|
|
if parent:
|
|
parentstring = parentmarkup + (', ' + markup).join(parent.split(','))
|
|
write(' * Extending ' + parentstring + ':', file=fp)
|
|
for api in sorted(dict[required][parent]):
|
|
write(' ** ' + markup + api, file=fp)
|
|
else:
|
|
for api in sorted(dict[required][parent]):
|
|
write(' * ' + markup + api, file=fp)
|
|
|
|
if required is not None:
|
|
write('endif::' + required + '[]', file=fp)
|
|
write('',file=fp)
|
|
|
|
def makeInterfaceFile(self, feature):
|
|
"""Generate a file containing feature interface documentation in
|
|
asciidoctor markup form.
|
|
|
|
- feature - name of the feature being generated"""
|
|
|
|
filename = feature + self.genOpts.conventions.file_suffix
|
|
fp = open(self.genOpts.directory + '/' + filename, 'w', encoding='utf-8')
|
|
|
|
# Write out the lists of new interfaces added by the feature
|
|
self.writeNewInterfaces(feature, 'define', 'New Macros', 'dlink:', fp)
|
|
self.writeNewInterfaces(feature, 'basetype', 'New Base Types', 'basetype:',fp)
|
|
self.writeNewInterfaces(feature, 'handle', 'New Object Types', 'slink:', fp)
|
|
self.writeNewInterfaces(feature, 'command', 'New Commands', 'flink:', fp)
|
|
self.writeNewInterfaces(feature, 'struct', 'New Structures', 'slink:', fp)
|
|
self.writeNewInterfaces(feature, 'union', 'New Unions', 'slink:', fp)
|
|
self.writeNewInterfaces(feature, 'funcpointer', 'New Function Pointers','tlink:', fp)
|
|
self.writeNewInterfaces(feature, 'enum', 'New Enums', 'elink:', fp)
|
|
self.writeNewInterfaces(feature, 'bitmask', 'New Bitmasks', 'tlink:', fp)
|
|
self.writeNewInterfaces(feature, 'include', 'New Headers', 'code:', fp)
|
|
self.writeNewInterfaces(feature, 'enumconstant','New Enum Constants', 'ename:', fp)
|
|
|
|
fp.close()
|
|
|
|
def endFile(self):
|
|
# Generate metadoc feature files, in refpage and non-refpage form
|
|
for feature in self.features:
|
|
self.makeInterfaceFile(feature)
|
|
|
|
OutputGenerator.endFile(self)
|