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
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
|
import sys, os
import markdown
import apiparser
import time
# list of all the 'class' and 'id' attributes assigned to
# <div> and <span> tags by the renderer.
API_REFERENCE = 'api_reference'
MODULE_API_DOCS_CLASS = 'module_api_docs'
MODULE_API_DOCS_ID = '_module_api_docs'
API_HEADER = 'api_header'
API_NAME = 'api_name'
API_COMPONENT_GROUP = 'api_component_group'
API_COMPONENT = 'api_component'
DATATYPE = 'datatype'
RETURNS = 'returns'
PARAMETER_SET = 'parameter_set'
MODULE_DESCRIPTION = 'module_description'
HTML_HEADER = '''
<!DOCTYPE html>\n
<html>\n
<head>\n
<meta http-equiv="Content-type" content="text/html; charset=utf-8" />\n
<base target="_blank"/>\n
<link rel="stylesheet" type="text/css" media="all"\n
href="../../../css/base.css" />\n
<link rel="stylesheet" type="text/css" media="all"\n
href="../../../css/apidocs.css" />\n
<title>Add-on SDK Documentation</title>\n
<style type="text/css">\n
body {\n
border: 50px solid #FFFFFF;\n
}\n
</style>\n
\n
<script type="text/javascript">\n
function rewrite_links() {\n
var images = document.getElementsByTagName("img");\n
for (var i = 0; i < images.length; i++) {\n
var before = images[i].src.split("packages/")[0];\n
var after = images[i].src.split("/docs")[1];\n
images[i].src = before + after;\n
}\n
}\n
</script>\n
</head>\n
\n
<body onload = "rewrite_links()">\n'''
HTML_FOOTER = '''
</body>\n
\n
</html>\n'''
def indent(text_in):
text_out = ''
lines = text_in.splitlines(True)
indentation_level = 0
indentation_depth = 2
for line in lines:
if (line.startswith('<div')):
text_out += ((' ' * indentation_depth) * indentation_level) + line
if not '</div>' in line:
indentation_level += 1
else:
if (line.startswith('</div>')):
indentation_level -= 1
text_out += ((' ' * indentation_depth) * indentation_level) + line
return text_out
def tag_wrap_id(text, classname, id, tag = 'div'):
return ''.join(['\n<'+ tag + ' id="', id, '" class="', \
classname, '">\n', text + '\n</' + tag +'>\n'])
def tag_wrap(text, classname, tag = 'div', inline = False):
if inline:
return ''.join(['\n<' + tag + ' class="', classname, '">', \
text, '</'+ tag + '>\n'])
else:
return ''.join(['\n<' + tag + ' class="', classname, '">', \
text, '\n</'+ tag + '>\n'])
def tag_wrap_inline(text, classname, tag = 'div'):
return ''.join(['\n<' + tag + ' class="', classname, '">', \
text, '</'+ tag + '>\n'])
def span_wrap(text, classname):
return ''.join(['<span class="', classname, '">', \
text, '</span>'])
class API_Renderer(object):
def __init__(self, json, tag):
self.name = json.get('name', None)
self.tag = tag
self.description = json.get('description', '')
self.json = json
def render_name(self):
raise Exception('not implemented in this class')
def render_description(self):
return markdown.markdown(self.description)
def render_subcomponents(self):
raise Exception('not implemented in this class')
def get_tag(self):
return self.tag
class Class_Doc(API_Renderer):
def __init__(self, json, tag):
API_Renderer.__init__(self, json, tag)
def render_name(self):
return self.name
def render_subcomponents(self):
return render_object_contents(self.json, 'h5', 'h6')
class Event_Doc(API_Renderer):
def __init__(self, json, tag):
API_Renderer.__init__(self, json, tag)
self.arguments_json = json.get('arguments', None)
def render_name(self):
return self.name
def render_subcomponents(self):
if not self.arguments_json:
return ''
text = ''.join([render_comp(Argument_Doc(argument_json, 'div')) \
for argument_json in self.arguments_json])
return tag_wrap(text, PARAMETER_SET)
class Argument_Doc(API_Renderer):
def __init__(self, json, tag):
API_Renderer.__init__(self, json, tag)
self.datatype = json.get('datatype', None)
def render_name(self):
return span_wrap(self.datatype, DATATYPE)
def render_subcomponents(self):
return ''
class Function_Doc(API_Renderer):
def __init__(self, json, tag):
API_Renderer.__init__(self, json, tag)
self.signature = json['signature']
self.returns = json.get('returns', None)
self.parameters_json = json.get('params', None)
def render_name(self):
return self.signature
def render_subcomponents(self):
return self._render_parameters() + self._render_returns()
def _render_parameters(self):
if not self.parameters_json:
return ''
text = ''.join([render_comp(Parameter_Doc(parameter_json, 'div')) \
for parameter_json in self.parameters_json])
return tag_wrap(text, PARAMETER_SET)
def _render_returns(self):
if not self.returns:
return ''
text = 'Returns: ' + span_wrap(self.returns['datatype'], DATATYPE)
text += markdown.markdown(self.returns['description'])
return tag_wrap(text, RETURNS)
class Property_Doc(API_Renderer):
def __init__(self, json, tag):
API_Renderer.__init__(self, json, tag)
self.datatype = json.get('datatype', None)
self.required = json.get('required', True)
self.default = json.get('default', False)
def render_name(self):
rendered = self.name
if self.default:
rendered = rendered + " = " + self.default
if self.datatype:
rendered = rendered + ' : ' + span_wrap(self.datatype, DATATYPE)
if not self.required:
rendered = '[ ' + rendered + ' ]'
return rendered
def render_subcomponents(self):
return render_object_contents(self.json)
class Parameter_Doc(Property_Doc):
def __init__(self, json, tag):
Property_Doc.__init__(self, json, tag)
self.properties_json = json.get('props', None)
def render_subcomponents(self):
if not self.properties_json:
return ''
text = ''.join([render_comp(Property_Doc(property_json, 'div')) \
for property_json in self.properties_json])
return text
def render_object_contents(json, tag = 'div', comp_tag = 'div'):
ctors = json.get('constructors', None)
text = render_comp_group(ctors, 'Constructors', Function_Doc, tag, comp_tag)
methods = json.get('methods', None)
text += render_comp_group(methods, 'Methods', Function_Doc, tag, comp_tag)
properties = json.get('properties', None)
text += render_comp_group(properties, 'Properties', Property_Doc, tag, comp_tag)
events = json.get('events', None)
text += render_comp_group(events, 'Events', Event_Doc, tag, comp_tag)
return text
def render_comp(component):
# a component is wrapped inside a single div marked 'API_COMPONENT'
# containing:
# 1) the component name, marked 'API_NAME'
text = tag_wrap(component.render_name(), API_NAME, component.get_tag(), True)
# 2) the component description
text += component.render_description()
# 3) the component contents
text += component.render_subcomponents()
return tag_wrap(text, API_COMPONENT)
def render_comp_group(group, group_name, ctor, tag = 'div', comp_tag = 'div'):
if not group:
return ''
# component group is a list of components in a single div called
# 'API_COMPONENT_GROUP' containing:
# 1) a title for the group marked with 'API_HEADER'
text = tag_wrap(group_name, API_HEADER, tag, True)
# 2) each component
text += ''.join([render_comp(ctor(api, comp_tag)) for api in group])
return tag_wrap(text, API_COMPONENT_GROUP)
def render_descriptions(descriptions_md):
text = ''.join([description_md for description_md in descriptions_md])
return tag_wrap(markdown.markdown(text), MODULE_DESCRIPTION)
def render_api_reference(api_docs):
if (len(api_docs) == 0):
return ''
# at the top level api reference is in a single div marked 'API_REFERENCE',
# containing:
# 1) a title 'API Reference' marked with 'API_HEADER'
text = tag_wrap('API Reference', API_HEADER, 'h2', True)
# 2) a component group called 'Classes' containing any class elements
classes = [api for api in api_docs if api['type'] == 'class']
text += render_comp_group(classes, 'Classes', Class_Doc, 'h3', 'h4')
# 3) a component group called 'Functions' containing any global functions
functions = [api for api in api_docs if api['type'] == 'function']
text += render_comp_group(functions, 'Functions', Function_Doc, 'h3', 'h4')
# 4) a component group called 'Properties' containing any global properties
properties = [api for api in api_docs if api['type'] == 'property']
text += render_comp_group(properties, 'Properties', Property_Doc, 'h3', 'h4')
# 5) a component group called 'Events' containing any global events
events = [api for api in api_docs if api['type'] == 'event']
text += render_comp_group(events, 'Events', Event_Doc, 'h3', 'h4')
return tag_wrap(text, API_REFERENCE)
# take the JSON output of apiparser
# return the HTML DIV containing the rendered component
def json_to_div(json, markdown_filename):
module_name, ext = os.path.splitext(os.path.basename(markdown_filename))
descriptions = [hunk[1] for hunk in json if hunk[0]=='markdown']
api_docs = [hunk[1] for hunk in json if hunk[0]=='api-json']
text = "<h1>" + module_name + "</h1>"
text += render_descriptions(descriptions)
text += render_api_reference(api_docs)
text = tag_wrap_id(text, MODULE_API_DOCS_CLASS, \
module_name + MODULE_API_DOCS_ID)
return text.encode('utf8')
# take the JSON output of apiparser
# return standalone HTML containing the rendered component
def json_to_html(json, markdown_filename):
return indent(HTML_HEADER + \
json_to_div(json, markdown_filename) + HTML_FOOTER)
# take the name of a Markdown file
# return the HTML DIV containing the rendered component
def md_to_div(markdown_filename):
markdown_contents = open(markdown_filename).read().decode('utf8')
json = list(apiparser.parse_hunks(markdown_contents))
return json_to_div(json, markdown_filename)
# take the name of a Markdown file
# return standalone HTML containing the rendered component
def md_to_html(markdown_filename):
return indent(HTML_HEADER + md_to_div(markdown_filename) + HTML_FOOTER)
if __name__ == '__main__':
if (len(sys.argv) == 0):
print 'Supply the name of a docs file to parse'
else:
print md_to_html(sys.argv[1])
|
