##// END OF EJS Templates
Docstring decorator
Jonathan Frederic -
Show More
@@ -96,7 +96,7 b' class NbConvertApp(Application):'
96 ipynb_file = (self.extra_args)[2]
96 ipynb_file = (self.extra_args)[2]
97
97
98 #Export
98 #Export
99 return_value = export_by_name(ipynb_file, export_type)
99 return_value = export_by_name(export_type, ipynb_file)
100 if return_value is None:
100 if return_value is None:
101 print("Error: '%s' template not found." % export_type)
101 print("Error: '%s' template not found." % export_type)
102 return
102 return
@@ -15,6 +15,7 b' Module containing single call export functions.'
15
15
16 import sys
16 import sys
17 import inspect
17 import inspect
18 from functools import wraps
18
19
19 from IPython.nbformat.v3.nbbase import NotebookNode
20 from IPython.nbformat.v3.nbbase import NotebookNode
20
21
@@ -30,17 +31,15 b' from .exporters.rst import RstExporter'
30 from .exporters.sphinx_howto import SphinxHowtoExporter
31 from .exporters.sphinx_howto import SphinxHowtoExporter
31 from .exporters.sphinx_manual import SphinxManualExporter
32 from .exporters.sphinx_manual import SphinxManualExporter
32
33
33
34 #-----------------------------------------------------------------------------
34 #-----------------------------------------------------------------------------
35 # Functions
35 # Classes
36 #-----------------------------------------------------------------------------
36 #-----------------------------------------------------------------------------
37
37
38 def export(nb, config=None, transformers=None, filters=None, exporter_type=Exporter):
38 def DocDecorator(f):
39 """
40 Export a notebook object using specific exporter class.
41
39
42 Parameters
40 #Set docstring of function
43 ----------
41 f.__doc__ = f.__doc__ + """
42 nb : Notebook node
44 config : config
43 config : config
45 User configuration instance.
44 User configuration instance.
46 transformers : list[of transformer]
45 transformers : list[of transformer]
@@ -52,12 +51,6 b' def export(nb, config=None, transformers=None, filters=None, exporter_type=Expor'
52 Custom filters to make accessible to the Jinja templates. Any
51 Custom filters to make accessible to the Jinja templates. Any
53 filters specified here will override existing filters if a
52 filters specified here will override existing filters if a
54 naming conflict occurs.
53 naming conflict occurs.
55 exporter_type:
56 Class type of the exporter that should be used. This method
57 will initialize it's own instance of the class. It is
58 ASSUMED that the class type provided exposes a
59 constructor (__init__) with the same signature as the
60 base Exporter class.
61
54
62 Returns
55 Returns
63 ----------
56 ----------
@@ -70,7 +63,30 b' def export(nb, config=None, transformers=None, filters=None, exporter_type=Expor'
70 exporter_instance : Exporter
63 exporter_instance : Exporter
71 Instance of the Exporter class used to export the document. Useful
64 Instance of the Exporter class used to export the document. Useful
72 to caller because it provides a 'file_extension' property which
65 to caller because it provides a 'file_extension' property which
73 specifies what extension the output should be saved as.
66 specifies what extension the output should be saved as."""
67
68 @wraps(f)
69 def decorator(*args, **kwargs):
70 return f(*args, **kwargs)
71
72 return decorator
73
74
75 #-----------------------------------------------------------------------------
76 # Functions
77 #-----------------------------------------------------------------------------
78
79 @DocDecorator
80 def export(exporter_type, nb, config=None, transformers=None, filters=None):
81 """
82 Export a notebook object using specific exporter class.
83
84 exporter_type : Exporter class type
85 Class type of the exporter that should be used. This method
86 will initialize it's own instance of the class. It is
87 ASSUMED that the class type provided exposes a
88 constructor (__init__) with the same signature as the
89 base Exporter class.}
74 """
90 """
75
91
76 #Check arguments
92 #Check arguments
@@ -96,382 +112,95 b' def export(nb, config=None, transformers=None, filters=None, exporter_type=Expor'
96 return output, resources, exporter_instance
112 return output, resources, exporter_instance
97
113
98
114
115 @DocDecorator
99 def export_sphinx_manual(nb, config=None, transformers=None, filters=None):
116 def export_sphinx_manual(nb, config=None, transformers=None, filters=None):
100 """
117 """
101 Export a notebook object to Sphinx Manual LaTeX
118 Export a notebook object to Sphinx Manual LaTeX
102
103 Parameters
104 ----------
105 config : config
106 User configuration instance.
107 transformers : list[of transformer]
108 Custom transformers to apply to the notebook prior to engaging
109 the Jinja template engine. Any transformers specified here
110 will override existing transformers if a naming conflict
111 occurs.
112 filters : list[of filter]
113 Custom filters to make accessible to the Jinja templates. Any
114 filters specified here will override existing filters if a
115 naming conflict occurs.
116
117 Returns
118 ----------
119 tuple- output, resources, exporter_instance
120 output : str
121 Jinja 2 output. This is the resulting converted notebook.
122 resources : dictionary
123 Dictionary of resources used prior to and during the conversion
124 process.
125 exporter_instance : Exporter
126 Instance of the Exporter class used to export the document. Useful
127 to caller because it provides a 'file_extension' property which
128 specifies what extension the output should be saved as.
129 """
119 """
130 return export(nb, config, transformers, filters, SphinxManualExporter)
120 return export(SphinxManualExporter, nb, config, transformers, filters)
131
121
132
122
123 @DocDecorator
133 def export_sphinx_howto(nb, config=None, transformers=None, filters=None):
124 def export_sphinx_howto(nb, config=None, transformers=None, filters=None):
134 """
125 """
135 Export a notebook object to Sphinx HowTo LaTeX
126 Export a notebook object to Sphinx HowTo LaTeX
136
137 Parameters
138 ----------
139 config : config
140 User configuration instance.
141 transformers : list[of transformer]
142 Custom transformers to apply to the notebook prior to engaging
143 the Jinja template engine. Any transformers specified here
144 will override existing transformers if a naming conflict
145 occurs.
146 filters : list[of filter]
147 Custom filters to make accessible to the Jinja templates. Any
148 filters specified here will override existing filters if a
149 naming conflict occurs.
150
151 Returns
152 ----------
153 tuple- output, resources, exporter_instance
154 output : str
155 Jinja 2 output. This is the resulting converted notebook.
156 resources : dictionary
157 Dictionary of resources used prior to and during the conversion
158 process.
159 exporter_instance : Exporter
160 Instance of the Exporter class used to export the document. Useful
161 to caller because it provides a 'file_extension' property which
162 specifies what extension the output should be saved as.
163 """
127 """
164 return export(nb, config, transformers, filters, SphinxHowtoExporter)
128 return export(SphinxHowtoExporter, nb, config, transformers, filters)
165
129
166
130
131 @DocDecorator
167 def export_basic_html(nb, config=None, transformers=None, filters=None):
132 def export_basic_html(nb, config=None, transformers=None, filters=None):
168 """
133 """
169 Export a notebook object to Basic HTML
134 Export a notebook object to Basic HTML
170
171 Parameters
172 ----------
173 config : config
174 User configuration instance.
175 transformers : list[of transformer]
176 Custom transformers to apply to the notebook prior to engaging
177 the Jinja template engine. Any transformers specified here
178 will override existing transformers if a naming conflict
179 occurs.
180 filters : list[of filter]
181 Custom filters to make accessible to the Jinja templates. Any
182 filters specified here will override existing filters if a
183 naming conflict occurs.
184
185 Returns
186 ----------
187 tuple- output, resources, exporter_instance
188 output : str
189 Jinja 2 output. This is the resulting converted notebook.
190 resources : dictionary
191 Dictionary of resources used prior to and during the conversion
192 process.
193 exporter_instance : Exporter
194 Instance of the Exporter class used to export the document. Useful
195 to caller because it provides a 'file_extension' property which
196 specifies what extension the output should be saved as.
197 """
135 """
198 return export(nb, config, transformers, filters, BasicHtmlExporter)
136 return export(BasicHtmlExporter, nb, config, transformers, filters)
199
137
200
138
139 @DocDecorator
201 def export_full_html(nb, config=None, transformers=None, filters=None):
140 def export_full_html(nb, config=None, transformers=None, filters=None):
202 """
141 """
203 Export a notebook object to Full HTML
142 Export a notebook object to Full HTML
204
205 Parameters
206 ----------
207 config : config
208 User configuration instance.
209 transformers : list[of transformer]
210 Custom transformers to apply to the notebook prior to engaging
211 the Jinja template engine. Any transformers specified here
212 will override existing transformers if a naming conflict
213 occurs.
214 filters : list[of filter]
215 Custom filters to make accessible to the Jinja templates. Any
216 filters specified here will override existing filters if a
217 naming conflict occurs.
218
219 Returns
220 ----------
221 tuple- output, resources, exporter_instance
222 output : str
223 Jinja 2 output. This is the resulting converted notebook.
224 resources : dictionary
225 Dictionary of resources used prior to and during the conversion
226 process.
227 exporter_instance : Exporter
228 Instance of the Exporter class used to export the document. Useful
229 to caller because it provides a 'file_extension' property which
230 specifies what extension the output should be saved as.
231 """
143 """
232 return export(nb, config, transformers, filters, FullHtmlExporter)
144 return export(FullHtmlExporter, nb, config, transformers, filters)
233
145
234
146
147 @DocDecorator
235 def export_latex(nb, config=None, transformers=None, filters=None):
148 def export_latex(nb, config=None, transformers=None, filters=None):
236 """
149 """
237 Export a notebook object to LaTeX
150 Export a notebook object to LaTeX
238
239 Parameters
240 ----------
241 config : config
242 User configuration instance.
243 transformers : list[of transformer]
244 Custom transformers to apply to the notebook prior to engaging
245 the Jinja template engine. Any transformers specified here
246 will override existing transformers if a naming conflict
247 occurs.
248 filters : list[of filter]
249 Custom filters to make accessible to the Jinja templates. Any
250 filters specified here will override existing filters if a
251 naming conflict occurs.
252
253 Returns
254 ----------
255 tuple- output, resources, exporter_instance
256 output : str
257 Jinja 2 output. This is the resulting converted notebook.
258 resources : dictionary
259 Dictionary of resources used prior to and during the conversion
260 process.
261 exporter_instance : Exporter
262 Instance of the Exporter class used to export the document. Useful
263 to caller because it provides a 'file_extension' property which
264 specifies what extension the output should be saved as.
265 """
151 """
266 return export(nb, config, transformers, filters, LatexExporter)
152 return export(LatexExporter, nb, config, transformers, filters)
267
153
268
154
155 @DocDecorator
269 def export_markdown(nb, config=None, transformers=None, filters=None):
156 def export_markdown(nb, config=None, transformers=None, filters=None):
270 """
157 """
271 Export a notebook object to Markdown
158 Export a notebook object to Markdown
272
273 Parameters
274 ----------
275 config : config
276 User configuration instance.
277 transformers : list[of transformer]
278 Custom transformers to apply to the notebook prior to engaging
279 the Jinja template engine. Any transformers specified here
280 will override existing transformers if a naming conflict
281 occurs.
282 filters : list[of filter]
283 Custom filters to make accessible to the Jinja templates. Any
284 filters specified here will override existing filters if a
285 naming conflict occurs.
286
287 Returns
288 ----------
289 tuple- output, resources, exporter_instance
290 output : str
291 Jinja 2 output. This is the resulting converted notebook.
292 resources : dictionary
293 Dictionary of resources used prior to and during the conversion
294 process.
295 exporter_instance : Exporter
296 Instance of the Exporter class used to export the document. Useful
297 to caller because it provides a 'file_extension' property which
298 specifies what extension the output should be saved as.
299 """
159 """
300 return export(nb, config, transformers, filters, MarkdownExporter)
160 return export(MarkdownExporter, nb, config, transformers, filters)
301
161
302
162
163 @DocDecorator
303 def export_python(nb, config=None, transformers=None, filters=None):
164 def export_python(nb, config=None, transformers=None, filters=None):
304 """
165 """
305 Export a notebook object to Python
166 Export a notebook object to Python
306
307 Parameters
308 ----------
309 config : config
310 User configuration instance.
311 transformers : list[of transformer]
312 Custom transformers to apply to the notebook prior to engaging
313 the Jinja template engine. Any transformers specified here
314 will override existing transformers if a naming conflict
315 occurs.
316 filters : list[of filter]
317 Custom filters to make accessible to the Jinja templates. Any
318 filters specified here will override existing filters if a
319 naming conflict occurs.
320
321 Returns
322 ----------
323 tuple- output, resources, exporter_instance
324 output : str
325 Jinja 2 output. This is the resulting converted notebook.
326 resources : dictionary
327 Dictionary of resources used prior to and during the conversion
328 process.
329 exporter_instance : Exporter
330 Instance of the Exporter class used to export the document. Useful
331 to caller because it provides a 'file_extension' property which
332 specifies what extension the output should be saved as.
333 """
167 """
334 return export(nb, config, transformers, filters, PythonExporter)
168 return export(PythonExporter, nb, config, transformers, filters)
335
169
336
170
171 @DocDecorator
337 def export_python_armor(nb, config=None, transformers=None, filters=None):
172 def export_python_armor(nb, config=None, transformers=None, filters=None):
338 """
173 """
339 Export a notebook object to Python (Armor)
174 Export a notebook object to Python (Armor)
340
341 Parameters
342 ----------
343 config : config
344 User configuration instance.
345 transformers : list[of transformer]
346 Custom transformers to apply to the notebook prior to engaging
347 the Jinja template engine. Any transformers specified here
348 will override existing transformers if a naming conflict
349 occurs.
350 filters : list[of filter]
351 Custom filters to make accessible to the Jinja templates. Any
352 filters specified here will override existing filters if a
353 naming conflict occurs.
354
355 Returns
356 ----------
357 tuple- output, resources, exporter_instance
358 output : str
359 Jinja 2 output. This is the resulting converted notebook.
360 resources : dictionary
361 Dictionary of resources used prior to and during the conversion
362 process.
363 exporter_instance : Exporter
364 Instance of the Exporter class used to export the document. Useful
365 to caller because it provides a 'file_extension' property which
366 specifies what extension the output should be saved as.
367 """
175 """
368 return export(nb, config, transformers, filters, PythonArmorExporter)
176 return export(PythonArmorExporter, nb, config, transformers, filters)
369
177
370
178
179 @DocDecorator
371 def export_reveal(nb, config=None, transformers=None, filters=None):
180 def export_reveal(nb, config=None, transformers=None, filters=None):
372 """
181 """
373 Export a notebook object to Reveal
182 Export a notebook object to Reveal
374
375 Parameters
376 ----------
377 config : config
378 User configuration instance.
379 transformers : list[of transformer]
380 Custom transformers to apply to the notebook prior to engaging
381 the Jinja template engine. Any transformers specified here
382 will override existing transformers if a naming conflict
383 occurs.
384 filters : list[of filter]
385 Custom filters to make accessible to the Jinja templates. Any
386 filters specified here will override existing filters if a
387 naming conflict occurs.
388
389 Returns
390 ----------
391 tuple- output, resources, exporter_instance
392 output : str
393 Jinja 2 output. This is the resulting converted notebook.
394 resources : dictionary
395 Dictionary of resources used prior to and during the conversion
396 process.
397 exporter_instance : Exporter
398 Instance of the Exporter class used to export the document. Useful
399 to caller because it provides a 'file_extension' property which
400 specifies what extension the output should be saved as.
401 """
183 """
402 return export(nb, config, transformers, filters, RevealExporter)
184 return export(RevealExporter, nb, config, transformers, filters)
403
185
404
186
187 @DocDecorator
405 def export_rst(nb, config=None, transformers=None, filters=None):
188 def export_rst(nb, config=None, transformers=None, filters=None):
406 """
189 """
407 Export a notebook object to RST
190 Export a notebook object to RST
408
409 Parameters
410 ----------
411 config : config
412 User configuration instance.
413 transformers : list[of transformer]
414 Custom transformers to apply to the notebook prior to engaging
415 the Jinja template engine. Any transformers specified here
416 will override existing transformers if a naming conflict
417 occurs.
418 filters : list[of filter]
419 Custom filters to make accessible to the Jinja templates. Any
420 filters specified here will override existing filters if a
421 naming conflict occurs.
422
423 Returns
424 ----------
425 tuple- output, resources, exporter_instance
426 output : str
427 Jinja 2 output. This is the resulting converted notebook.
428 resources : dictionary
429 Dictionary of resources used prior to and during the conversion
430 process.
431 exporter_instance : Exporter
432 Instance of the Exporter class used to export the document. Useful
433 to caller because it provides a 'file_extension' property which
434 specifies what extension the output should be saved as.
435 """
191 """
436 return export(nb, config, transformers, filters, RstExporter)
192 return export(RstExporter, nb, config, transformers, filters)
437
193
438
194
439 def export_by_name(nb, template_name, config=None, transformers=None, filters=None):
195 @DocDecorator
196 def export_by_name(template_name, nb, config=None, transformers=None, filters=None):
440 """
197 """
441 Export a notebook object to a template type by its name. Reflection
198 Export a notebook object to a template type by its name. Reflection
442 (Inspect) is used to find the template's corresponding explicit export
199 (Inspect) is used to find the template's corresponding explicit export
443 method defined in this module. That method is then called directly.
200 method defined in this module. That method is then called directly.
444
201
445 Parameters
446 ----------
447 template_name : str
202 template_name : str
448 Name of the template style to export to.
203 Name of the template style to export to.
449 config : config
450 User configuration instance.
451 transformers : list[of transformer]
452 Custom transformers to apply to the notebook prior to engaging
453 the Jinja template engine. Any transformers specified here
454 will override existing transformers if a naming conflict
455 occurs.
456 filters : list[of filter]
457 Custom filters to make accessible to the Jinja templates. Any
458 filters specified here will override existing filters if a
459 naming conflict occurs.
460
461 Returns
462 ----------
463 tuple- (output, resources, exporter_instance)
464 None- if template not found
465
466 output : str
467 Jinja 2 output. This is the resulting converted notebook.
468 resources : dictionary
469 Dictionary of resources used prior to and during the conversion
470 process.
471 exporter_instance : Exporter
472 Instance of the Exporter class used to export the document. Useful
473 to caller because it provides a 'file_extension' property which
474 specifies what extension the output should be saved as.
475 """
204 """
476
205
477 function_name = "export_" + template_name.lower()
206 function_name = "export_" + template_name.lower()
General Comments 0
You need to be logged in to leave comments. Login now