efl

1
#!/usr/bin/env python3
2
# encoding: utf-8
3
"""
4
Efl documentation generator
5

6
Use this script without arguments to generate the full documentation of the Efl
7
namespace in a folder called 'dokuwiki' (-v to see all generated files)
8

9
  --help to see all other options
10

11
"""
12
import os
13
import sys
14
import argparse
15
import atexit
16

17

18
# Use .eo files from the source tree (not the installed ones)
19
script_path = os.path.dirname(os.path.realpath(__file__))
20
root_path = os.path.abspath(os.path.join(script_path, '..', '..', '..'))
21
SCAN_FOLDER = os.path.join(root_path, 'src', 'lib')
22

23

24
# Use pyolian from source (not installed)
25
pyolian_path = os.path.join(root_path, 'src', 'scripts')
26
sys.path.insert(0, pyolian_path)
27
from pyolian import eolian
28
from pyolian.generator import Template
29

30

31
# parse args
32
parser = argparse.ArgumentParser(description='Pyolian DocuWiki generator.')
33
parser.add_argument('--root-path', '-r', metavar='FOLDER', default='dokuwiki',
34
                    help='where to write files to (root of dokuwiki) '
35
                         'default to: "./dokuwiki"')
36
parser.add_argument('--verbose', '-v', action='store_true',
37
                    help='print a line for each rendered file')
38
parser.add_argument('--exclude-beta', '-e', action='store_true',
39
                    help='do not generate docs for class in beta state')
40
parser.add_argument('--namespace', '-n', metavar='ROOT', default='Efl',
41
                    help='root namespace of the docs. (default to "Efl")')
42
_choices = ['start', 'classes', 'enums', 'structs', 'aliases']
43
parser.add_argument('--step', '-s', metavar='STEP', default=None,
44
                    choices=_choices,
45
                    help='A single step to run (default to all), '
46
                         'valid choices: ' + ', '.join(_choices))
47
args = parser.parse_args()
48

49

50
# load the whole eolian db (from .eo files in source tree)
51
eolian_db = eolian.Eolian_State()
52
if not isinstance(eolian_db, eolian.Eolian_State):
53
    raise(RuntimeError('Eolian, failed to create Eolian state'))
54

55
if not eolian_db.directory_add(SCAN_FOLDER):
56
    raise(RuntimeError('Eolian, failed to scan source directory'))
57

58
if not eolian_db.all_eot_files_parse():
59
    raise(RuntimeError('Eolian, failed to parse all EOT files'))
60
    
61
if not eolian_db.all_eo_files_parse():
62
    raise(RuntimeError('Eolian, failed to parse all EO files'))
63

64

65
# cleanup the database on exit
66
def cleanup_db():
67
    global eolian_db
68
    del eolian_db
69

70

71
atexit.register(cleanup_db)
72

73

74
# calculate the full path for the txt page of the given object
75
def page_path_for_object(obj):
76
    path = ['data', 'pages', 'develop', 'api']
77
    for ns in obj.namespaces:
78
        path.append(ns.lower())
79
    output_filename = obj.short_name.lower() + '.txt'
80
    return os.path.join(args.root_path, *path, output_filename)
81

82

83
class BetaNamespaceWrapper(eolian.Namespace):
84
    """ A Namespace wrapper that hide objects marked as beta to the template """
85
    def __init__(self, eolian_ns):
86
        super(BetaNamespaceWrapper, self).__init__(eolian_ns.unit, eolian_ns.name)
87
        self._ns = eolian_ns
88

89
    @property
90
    def sub_namespaces(self):
91
        return [BetaNamespaceWrapper(ns) for ns in self._ns.sub_namespaces]
92

93
    @property
94
    def classes(self):
95
        return [c for c in self._ns.classes if not (args.exclude_beta and c.is_beta)]
96

97
    @property
98
    def regulars(self):
99
        return [c for c in self._ns.regulars if not (args.exclude_beta and c.is_beta)]
100

101
    @property
102
    def abstracts(self):
103
        return [c for c in self._ns.abstracts if not (args.exclude_beta and c.is_beta)]
104

105
    @property
106
    def mixins(self):
107
        return [c for c in self._ns.mixins if not (args.exclude_beta and c.is_beta)]
108

109
    @property
110
    def interfaces(self):
111
        return [c for c in self._ns.interfaces if not (args.exclude_beta and c.is_beta)]
112

113
    @property
114
    def aliases(self):
115
        return [c for c in self._ns.aliases if not (args.exclude_beta and c.is_beta)]
116

117
    @property
118
    def structs(self):
119
        return [c for c in self._ns.structs if not (args.exclude_beta and c.is_beta)]
120

121
    @property
122
    def enums(self):
123
        return [c for c in self._ns.enums if not (args.exclude_beta and c.is_beta)]
124

125

126
# render a (temporary) page for analizying the namespaces hierarchy
127
t = Template('namespaces.template')
128
nspaces = [BetaNamespaceWrapper(ns) for ns in eolian_db.all_namespaces
129
           if ns.name.startswith(args.namespace)]
130

131
tot_classes = tot_regulars = tot_abstracts = tot_mixins = tot_ifaces = 0
132
tot_enums = tot_structs = tot_aliases = 0
133
for ns in nspaces:
134
    for cls in ns.classes:
135
        tot_classes += 1
136
        if cls.type == eolian.Eolian_Class_Type.REGULAR:
137
            tot_regulars += 1
138
        elif cls.type == eolian.Eolian_Class_Type.ABSTRACT:
139
            tot_abstracts += 1
140
        elif cls.type == eolian.Eolian_Class_Type.MIXIN:
141
            tot_mixins += 1
142
        elif cls.type == eolian.Eolian_Class_Type.INTERFACE:
143
            tot_ifaces += 1
144
    tot_enums += len(ns.enums)
145
    tot_structs += len(ns.structs)
146
    tot_aliases += len(ns.aliases)
147

148

149
totals = [
150
    ('Namespaces', len(nspaces)),
151
    ('ALL Classes', tot_classes),
152
    ('Regular classes', tot_regulars),
153
    ('Abstract classes', tot_abstracts),
154
    ('Mixins', tot_mixins),
155
    ('Interfaces', tot_ifaces),
156
    ('Enums', tot_enums),
157
    ('Structs', tot_structs),
158
    ('Aliases', tot_aliases),
159
]
160

161
root_ns = BetaNamespaceWrapper(eolian_db.namespace_get_by_name(args.namespace))
162

163
output_file = os.path.join(args.root_path, 'data', 'pages', 'develop', 'api', 'namespaces.txt')
164
t.render(output_file, args.verbose, root_ns=root_ns, totals=totals)
165

166

167
# render the main start.txt page
168
if args.step in ('start', None):
169
    t = Template('doc_start.template')
170

171
    nspaces = [BetaNamespaceWrapper(ns) for ns in eolian_db.all_namespaces
172
               if ns.name.startswith(args.namespace)]
173

174
    output_file = os.path.join(args.root_path, 'data', 'pages', 'develop', 'api', 'start.txt')
175
    t.render(output_file, args.verbose, nspaces=nspaces)
176

177

178
# render a page for each Class
179
if args.step in ('classes', None):
180
    t = Template('doc_class.template')
181
    for cls in eolian_db.classes:
182
        if cls.name.startswith(args.namespace):
183
            if not (args.exclude_beta and cls.is_beta):
184
                output_file = page_path_for_object(cls)
185
                t.render(output_file, args.verbose, cls=cls.name)
186

187
# render a page for each Enum
188
if args.step in ('enums', None):
189
    t = Template('doc_enum.template')
190
    for enum in eolian_db.enums:
191
        if enum.name.startswith(args.namespace):
192
            if not (args.exclude_beta and enum.is_beta):
193
                output_file = page_path_for_object(enum)
194
                t.render(output_file, args.verbose, enum=enum.name)
195

196
# render a page for each Struct
197
if args.step in ('structs', None):
198
    t = Template('doc_struct.template')
199
    for struct in eolian_db.structs:
200
        if struct.name.startswith(args.namespace):
201
            if not (args.exclude_beta and struct.is_beta):
202
                output_file = page_path_for_object(struct)
203
                t.render(output_file, args.verbose, struct=struct.name)
204

205
# render a page for each Alias
206
if args.step in ('aliases', None):
207
    t = Template('doc_alias.template')
208
    for alias in eolian_db.aliases:
209
        if alias.name.startswith(args.namespace):
210
            if not (args.exclude_beta and alias.is_beta):
211
                output_file = page_path_for_object(alias)
212
                t.render(output_file, args.verbose, alias=alias.name)
213