• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1#!/usr/bin/python3 -i
2#
3# Copyright (c) 2013-2020 The Khronos Group Inc.
4#
5# SPDX-License-Identifier: Apache-2.0
6
7import re
8from generator import OutputGenerator, write
9
10def interfaceDocSortKey(item):
11    if item == None:
12        return '\0'
13    else:
14        return item.casefold()
15
16class InterfaceDocGenerator(OutputGenerator):
17    """InterfaceDocGenerator - subclass of OutputGenerator.
18    Generates AsciiDoc includes of the interfaces added by a an API version
19    or extension."""
20
21    def __init__(self, *args, **kwargs):
22        super().__init__(*args, **kwargs)
23        self.features = []
24
25    def beginFile(self, genOpts):
26        OutputGenerator.beginFile(self, genOpts)
27
28        # Create subdirectory, if needed
29        self.makeDir(self.genOpts.directory)
30
31    def beginFeature(self, interface, emit):
32        # Start processing in superclass
33        OutputGenerator.beginFeature(self, interface, emit)
34
35        self.features.append( self.featureName )
36
37    def endFeature(self):
38        # Finish processing in superclass
39        OutputGenerator.endFeature(self)
40
41    def writeNewInterfaces(self, feature, key, title, markup, fp):
42        dict = self.featureDictionary[feature][key]
43
44        parentmarkup = markup
45        if key == 'enumconstant':
46            parentmarkup = 'elink:'
47
48        if dict:
49            write('=== ' + title, file=fp)
50            write('',file=fp)
51
52            # Loop through required blocks, sorted so they start with "core" features
53            for required in sorted(dict, key = interfaceDocSortKey):
54                if required is not None:
55                    requiredlink = 'apiext:' + required
56                    match = re.search("[A-Z]+_VERSION_([0-9]+)_([0-9]+)",required)
57                    if match is not None:
58                        major = match.group(1)
59                        minor = match.group(2)
60                        version = major + '.' + minor
61                        requiredlink = '<<versions-' + version + ', Version ' + version + '>>'
62
63                    write('ifdef::' + required + '[]', file=fp)
64                    write('If ' + requiredlink + ' is supported:', file=fp)
65                    write('',file=fp)
66
67                # Commands are relatively straightforward
68                if key == 'command':
69                    for api in sorted(dict[required]):
70                        write('  * ' + markup + api, file=fp)
71                # Types and constants are potentially parented, so need to handle that
72                else:
73                    # Loop through parents, sorted so they start with unparented items
74                    for parent in sorted(dict[required], key = interfaceDocSortKey):
75                        parentstring = ''
76                        if parent:
77                            parentstring = parentmarkup + (', ' + markup).join(parent.split(','))
78                            write('  * Extending ' + parentstring + ':', file=fp)
79                            for api in sorted(dict[required][parent]):
80                                write('  ** ' + markup + api, file=fp)
81                        else:
82                            for api in sorted(dict[required][parent]):
83                                write('  * ' + markup + api, file=fp)
84
85                if required is not None:
86                    write('endif::' + required + '[]', file=fp)
87                write('',file=fp)
88
89    def makeInterfaceFile(self, feature):
90        """Generate a file containing feature interface documentation in
91           asciidoctor markup form.
92
93        - feature - name of the feature being generated"""
94
95        filename = feature + self.genOpts.conventions.file_suffix
96        fp = open(self.genOpts.directory + '/' + filename, 'w', encoding='utf-8')
97
98        # Write out the lists of new interfaces added by the feature
99        self.writeNewInterfaces(feature, 'define',      'New Macros',           'slink:',   fp)
100        self.writeNewInterfaces(feature, 'basetype',    'New Base Types',       'basetype:',fp)
101        self.writeNewInterfaces(feature, 'handle',      'New Object Types',     'slink:',   fp)
102        self.writeNewInterfaces(feature, 'command',     'New Commands',         'flink:',   fp)
103        self.writeNewInterfaces(feature, 'struct',      'New Structures',       'slink:',   fp)
104        self.writeNewInterfaces(feature, 'union',       'New Unions',           'slink:',   fp)
105        self.writeNewInterfaces(feature, 'funcpointer', 'New Function Pointers','tlink:',   fp)
106        self.writeNewInterfaces(feature, 'enum',        'New Enums',            'elink:',   fp)
107        self.writeNewInterfaces(feature, 'bitmask',     'New Bitmasks',         'tlink:',   fp)
108        self.writeNewInterfaces(feature, 'include',     'New Headers',          'code:',    fp)
109        self.writeNewInterfaces(feature, 'enumconstant','New Enum Constants',   'ename:',   fp)
110
111        fp.close()
112
113    def endFile(self):
114        # Generate metadoc feature files, in refpage and non-refpage form
115        for feature in self.features:
116            self.makeInterfaceFile(feature)
117
118        OutputGenerator.endFile(self)
119