1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
|
#!/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)
|
