1
+ """Generate Documentation"""
2
+
1
3
import logging
2
4
import os
3
- import jinja2
4
- import click
5
5
import tempfile
6
6
from subprocess import call
7
- import string
8
- import time
9
- import shutil
10
- import yaml
11
7
import datetime
8
+ import markdown
9
+ import yaml
10
+ import jinja2
11
+ import click
12
12
13
13
logging .basicConfig (format = '%(levelname)s:%(message)s' , level = logging .DEBUG )
14
14
15
15
img_dir = 'img'
16
- property_dir = '.property.yml'
16
+ property_file = '.property.yml'
17
17
18
18
19
19
class Generator (object ):
20
20
def __init__ (self , root , env , jar ):
21
21
self .reference_generator = ReferenceGenerator (root , env , jar )
22
22
self .cover_generator = CoverGenerator (env )
23
-
23
+ self .tutorial_generator = TurotialGenerator (env )
24
+
24
25
def generate (self ):
25
26
self .cover_generator .generate ()
26
27
self .reference_generator .generate ()
28
+ self .tutorial_generator .generate ()
27
29
28
30
29
31
class CoverGenerator (object ):
@@ -37,6 +39,59 @@ def generate(self):
37
39
f .write (cover_template .render ())
38
40
39
41
42
+ class TurotialGenerator (object ):
43
+ def __init__ (self , env ):
44
+ self .env = env
45
+ self .input_dir = tutorials_dir
46
+ self .output_dir = output_tutorials_dir
47
+
48
+ def generate (self ):
49
+ file_name = os .path .join (self .input_dir , 'index.yml' )
50
+ items = []
51
+ with open (file_name ) as f :
52
+ raw_yaml_doc = f .read ()
53
+ yaml_obj = yaml .load (raw_yaml_doc )
54
+ items = yaml_obj ['index' ]
55
+ tutorial_items = []
56
+ for item in items :
57
+ tutorial_item = TutorialItem (
58
+ self .env , self .input_dir , item , self .output_dir )
59
+ with open (os .path .join (self .output_dir , item , 'index.html' ), 'w+' ) as f :
60
+ item_template = self .env .get_template (
61
+ 'tutorial_item_template.jinja' )
62
+ f .write (item_template .render (tutorial = tutorial_item ))
63
+ tutorial_items .append (tutorial_item )
64
+ index_template = self .env .get_template ('tutorial_index_template.jinja' )
65
+ with open (os .path .join (self .output_dir , 'index.html' ), 'w+' ) as f :
66
+ f .write (index_template .render (tutorials = tutorial_items ))
67
+
68
+
69
+ class TutorialItem (object ):
70
+ def __init__ (self , env , input_dir , item , output_dir ):
71
+ self .env = env
72
+ self .input_dir = input_dir
73
+ self .item = item
74
+ self .item_input_dir = os .path .join (self .input_dir , self .item )
75
+ self .output_dir = output_dir
76
+ self .item_output_dir = os .path .join (self .output_dir , self .item )
77
+ self .parse_property ()
78
+
79
+ def parse_property (self ):
80
+ with open (os .path .join (self .item_input_dir , property_file ), 'r' ) as f :
81
+ raw_yaml_doc = f .read ()
82
+ yaml_obj = yaml .load (raw_yaml_doc )
83
+ self .title = yaml_obj ['title' ]
84
+ # The directory must be named 'imgs'.
85
+ self .image = os .path .join (self .item , 'imgs' , yaml_obj ['image' ])
86
+ self .url = self .item + '/'
87
+ self .author = yaml_obj ['author' ]
88
+ self .introduction = yaml_obj ['introduction' ]
89
+ self .level = yaml_obj ['level' ]
90
+ with open (os .path .join (
91
+ self .item_input_dir , 'index.md' ), 'r' ) as index_f :
92
+ self .content = markdown .markdown (index_f .read ())
93
+
94
+
40
95
class ReferenceGenerator (object ):
41
96
def __init__ (self , root , env , jar ):
42
97
self .root_dir = root
@@ -62,9 +117,11 @@ def parse_reference(self):
62
117
63
118
def render_reference_items (self ):
64
119
for item in self .reference_items :
65
- reference_template = self .env .get_template ('reference_item_template.jinja' )
120
+ reference_template = self .env .get_template (
121
+ 'reference_item_template.jinja' )
66
122
with open (os .path .join (self .output_html_dir , ('%s.html' % item .name )), 'w+' ) as f :
67
- f .write (reference_template .render (item = item , today = datetime .datetime .now ().ctime ()))
123
+ f .write (reference_template .render (
124
+ item = item , today = datetime .datetime .now ().ctime ()))
68
125
69
126
def render_reference_index (self ):
70
127
categories = dict ()
@@ -74,9 +131,11 @@ def render_reference_index(self):
74
131
if item .category is '' :
75
132
# print(item.category)
76
133
path = (item .category , '' )
77
- if path == ('' , '' ): continue
134
+ if path == ('' , '' ):
135
+ continue
78
136
# Fields and Methods aren't included in the index
79
- if path [1 ] in ('Method' , 'Field' ): continue
137
+ if path [1 ] in ('Method' , 'Field' ):
138
+ continue
80
139
if path not in categories :
81
140
categories [path ] = list ()
82
141
categories [path ].append (item )
@@ -139,8 +198,10 @@ def render_reference_index(self):
139
198
current_cat = cat
140
199
if subcat != current_subcat :
141
200
if current_subcat is not None :
142
- elements .append ({'type' : 'end-subcategory' , 'content' : None })
143
- elements .append ({'type' : 'start-subcategory' , 'content' : subcat })
201
+ elements .append (
202
+ {'type' : 'end-subcategory' , 'content' : None })
203
+ elements .append (
204
+ {'type' : 'start-subcategory' , 'content' : subcat })
144
205
current_subcat = subcat
145
206
elements .append ({'type' : 'start-list' , 'content' : None })
146
207
# For demo.
@@ -152,10 +213,12 @@ def render_reference_index(self):
152
213
elements .append ({'type' : 'end-subcategory' , 'content' : None })
153
214
elements .append ({'type' : 'end-category' , 'content' : None })
154
215
155
- index_template = self .env .get_template ('reference_index_template.jinja' )
216
+ index_template = self .env .get_template (
217
+ 'reference_index_template.jinja' )
156
218
with open (os .path .join (self .output_html_dir , 'index.html' ), 'w+' ) as f :
157
219
f .write (index_template .render (elements = elements ))
158
220
221
+
159
222
class ReferenceItem (object ):
160
223
def __init__ (self , root , name , jar , output_img_dir ):
161
224
self .name = name
@@ -167,9 +230,9 @@ def __init__(self, root, name, jar, output_img_dir):
167
230
168
231
self .parse_reference_item ()
169
232
self .parse_property ()
170
-
233
+
171
234
def parse_property (self ):
172
- file_name = os .path .join (self .item_dir , property_dir )
235
+ file_name = os .path .join (self .item_dir , property_file )
173
236
with open (file_name ) as f :
174
237
raw_yaml_doc = f .read ()
175
238
yaml_obj = yaml .load (raw_yaml_doc )
@@ -204,9 +267,10 @@ def parse_reference_item(self):
204
267
continue
205
268
sketchFile = '%s/%s/%s.rpde' % (self .item_dir , filename , filename )
206
269
with open (sketchFile , 'r' ) as f :
207
- print (" Interpreting " + sketchFile )
270
+ print (' Interpreting ' + sketchFile )
208
271
code = f .read ()
209
- img_path = os .path .join (self .output_img_dir , ('%s.png' % filename ))
272
+ img_path = os .path .join (
273
+ self .output_img_dir , ('%s.png' % filename ))
210
274
testConfigFile = '%s/%s/.test.yml' % (self .item_dir , filename )
211
275
if os .path .isfile (testConfigFile ) is not True :
212
276
self .examples .append ({
@@ -231,19 +295,22 @@ def generate_image(self, code, to):
231
295
for i in range (pos , len (code ) - 1 ):
232
296
if code [i ] is '\n ' and code [i + 1 ] is '}' :
233
297
footer = '\n processing$saveFrame("%s")\n processing$exit()\n ' % to
234
- actual_code = code [:i ] + footer + code [i + 1 :]
298
+ actual_code = code [:i ] + footer + code [i + 1 :]
235
299
else :
236
300
footer = 'processing$saveFrame("%s")\n processing$exit()\n ' % to
237
301
actual_code = '%s\n %s' % (code , footer )
238
302
239
- # I don't know why temp file could not be written directly. It must be open() and written.
240
- temp_file = tempfile .NamedTemporaryFile (prefix = 'Processing.R.' , suffix = '.tmp.rpde' )
303
+ # I don't know why temp file could not be written directly. It must be
304
+ # open() and written.
305
+ temp_file = tempfile .NamedTemporaryFile (
306
+ prefix = 'Processing.R.' , suffix = '.tmp.rpde' )
241
307
temp_file .write (bytes (actual_code , 'utf-8' ))
242
308
temp_file .seek (0 )
243
309
retcode = call (['java' , '-jar' , self .jar_path , temp_file .name ])
244
310
if retcode is not 0 :
245
311
logging .error ('retcode of runner.jar: %d' , retcode )
246
312
313
+
247
314
@click .command ()
248
315
@click .option ('--core' , default = '' , help = 'The location of Processing.R source code.' )
249
316
@click .option ('--jar' , default = '' , help = 'The location of runner.jar' )
@@ -260,23 +327,31 @@ def generate(core, jar, docs_dir):
260
327
261
328
template_dir_short = 'templates'
262
329
output_reference_dir_short = 'docs/reference'
330
+ output_tutorial_dir_short = 'docs/tutorials'
263
331
output_dir_short = 'docs'
264
332
content_dir_short = 'content'
333
+ tutorials_dir_short = 'tutorials'
265
334
266
335
global template_dir
267
336
global output_dir
268
337
global content_dir
338
+ global tutorials_dir
269
339
global output_reference_dir
340
+ global output_tutorials_dir
270
341
271
342
template_dir = os .path .join (docs_dir , template_dir_short )
272
343
output_dir = os .path .join (docs_dir , output_dir_short )
273
344
content_dir = os .path .join (docs_dir , content_dir_short )
345
+ tutorials_dir = os .path .join (docs_dir , tutorials_dir_short )
274
346
output_reference_dir = os .path .join (docs_dir , output_reference_dir_short )
347
+ output_tutorials_dir = os .path .join (docs_dir , output_tutorial_dir_short )
275
348
276
- env = jinja2 .Environment (loader = jinja2 .FileSystemLoader (template_dir ), trim_blocks = 'true' )
349
+ env = jinja2 .Environment (loader = jinja2 .FileSystemLoader (
350
+ template_dir ), trim_blocks = 'true' )
277
351
278
352
generator = Generator (core , env , jar )
279
353
generator .generate ()
280
354
355
+
281
356
if __name__ == '__main__' :
282
357
generate ()
0 commit comments