Loading...
1# -*- coding: utf-8; mode: python -*-
2# pylint: disable=C0103, R0903, R0912, R0915
3u"""
4 scalable figure and image handling
5 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
6
7 Sphinx extension which implements scalable image handling.
8
9 :copyright: Copyright (C) 2016 Markus Heiser
10 :license: GPL Version 2, June 1991 see Linux/COPYING for details.
11
12 The build for image formats depend on image's source format and output's
13 destination format. This extension implement methods to simplify image
14 handling from the author's POV. Directives like ``kernel-figure`` implement
15 methods *to* always get the best output-format even if some tools are not
16 installed. For more details take a look at ``convert_image(...)`` which is
17 the core of all conversions.
18
19 * ``.. kernel-image``: for image handling / a ``.. image::`` replacement
20
21 * ``.. kernel-figure``: for figure handling / a ``.. figure::`` replacement
22
23 * ``.. kernel-render``: for render markup / a concept to embed *render*
24 markups (or languages). Supported markups (see ``RENDER_MARKUP_EXT``)
25
26 - ``DOT``: render embedded Graphviz's **DOC**
27 - ``SVG``: render embedded Scalable Vector Graphics (**SVG**)
28 - ... *developable*
29
30 Used tools:
31
32 * ``dot(1)``: Graphviz (https://www.graphviz.org). If Graphviz is not
33 available, the DOT language is inserted as literal-block.
34
35 * SVG to PDF: To generate PDF, you need at least one of this tools:
36
37 - ``convert(1)``: ImageMagick (https://www.imagemagick.org)
38
39 List of customizations:
40
41 * generate PDF from SVG / used by PDF (LaTeX) builder
42
43 * generate SVG (html-builder) and PDF (latex-builder) from DOT files.
44 DOT: see https://www.graphviz.org/content/dot-language
45
46 """
47
48import os
49from os import path
50import subprocess
51from hashlib import sha1
52import sys
53
54from docutils import nodes
55from docutils.statemachine import ViewList
56from docutils.parsers.rst import directives
57from docutils.parsers.rst.directives import images
58import sphinx
59
60from sphinx.util.nodes import clean_astext
61from six import iteritems
62
63import kernellog
64
65PY3 = sys.version_info[0] == 3
66
67if PY3:
68 _unicode = str
69else:
70 _unicode = unicode
71
72# Get Sphinx version
73major, minor, patch = sphinx.version_info[:3]
74if major == 1 and minor > 3:
75 # patches.Figure only landed in Sphinx 1.4
76 from sphinx.directives.patches import Figure # pylint: disable=C0413
77else:
78 Figure = images.Figure
79
80__version__ = '1.0.0'
81
82# simple helper
83# -------------
84
85def which(cmd):
86 """Searches the ``cmd`` in the ``PATH`` environment.
87
88 This *which* searches the PATH for executable ``cmd`` . First match is
89 returned, if nothing is found, ``None` is returned.
90 """
91 envpath = os.environ.get('PATH', None) or os.defpath
92 for folder in envpath.split(os.pathsep):
93 fname = folder + os.sep + cmd
94 if path.isfile(fname):
95 return fname
96
97def mkdir(folder, mode=0o775):
98 if not path.isdir(folder):
99 os.makedirs(folder, mode)
100
101def file2literal(fname):
102 with open(fname, "r") as src:
103 data = src.read()
104 node = nodes.literal_block(data, data)
105 return node
106
107def isNewer(path1, path2):
108 """Returns True if ``path1`` is newer than ``path2``
109
110 If ``path1`` exists and is newer than ``path2`` the function returns
111 ``True`` is returned otherwise ``False``
112 """
113 return (path.exists(path1)
114 and os.stat(path1).st_ctime > os.stat(path2).st_ctime)
115
116def pass_handle(self, node): # pylint: disable=W0613
117 pass
118
119# setup conversion tools and sphinx extension
120# -------------------------------------------
121
122# Graphviz's dot(1) support
123dot_cmd = None
124
125# ImageMagick' convert(1) support
126convert_cmd = None
127
128
129def setup(app):
130 # check toolchain first
131 app.connect('builder-inited', setupTools)
132
133 # image handling
134 app.add_directive("kernel-image", KernelImage)
135 app.add_node(kernel_image,
136 html = (visit_kernel_image, pass_handle),
137 latex = (visit_kernel_image, pass_handle),
138 texinfo = (visit_kernel_image, pass_handle),
139 text = (visit_kernel_image, pass_handle),
140 man = (visit_kernel_image, pass_handle), )
141
142 # figure handling
143 app.add_directive("kernel-figure", KernelFigure)
144 app.add_node(kernel_figure,
145 html = (visit_kernel_figure, pass_handle),
146 latex = (visit_kernel_figure, pass_handle),
147 texinfo = (visit_kernel_figure, pass_handle),
148 text = (visit_kernel_figure, pass_handle),
149 man = (visit_kernel_figure, pass_handle), )
150
151 # render handling
152 app.add_directive('kernel-render', KernelRender)
153 app.add_node(kernel_render,
154 html = (visit_kernel_render, pass_handle),
155 latex = (visit_kernel_render, pass_handle),
156 texinfo = (visit_kernel_render, pass_handle),
157 text = (visit_kernel_render, pass_handle),
158 man = (visit_kernel_render, pass_handle), )
159
160 app.connect('doctree-read', add_kernel_figure_to_std_domain)
161
162 return dict(
163 version = __version__,
164 parallel_read_safe = True,
165 parallel_write_safe = True
166 )
167
168
169def setupTools(app):
170 u"""
171 Check available build tools and log some *verbose* messages.
172
173 This function is called once, when the builder is initiated.
174 """
175 global dot_cmd, convert_cmd # pylint: disable=W0603
176 kernellog.verbose(app, "kfigure: check installed tools ...")
177
178 dot_cmd = which('dot')
179 convert_cmd = which('convert')
180
181 if dot_cmd:
182 kernellog.verbose(app, "use dot(1) from: " + dot_cmd)
183 else:
184 kernellog.warn(app, "dot(1) not found, for better output quality install "
185 "graphviz from https://www.graphviz.org")
186 if convert_cmd:
187 kernellog.verbose(app, "use convert(1) from: " + convert_cmd)
188 else:
189 kernellog.warn(app,
190 "convert(1) not found, for SVG to PDF conversion install "
191 "ImageMagick (https://www.imagemagick.org)")
192
193
194# integrate conversion tools
195# --------------------------
196
197RENDER_MARKUP_EXT = {
198 # The '.ext' must be handled by convert_image(..) function's *in_ext* input.
199 # <name> : <.ext>
200 'DOT' : '.dot',
201 'SVG' : '.svg'
202}
203
204def convert_image(img_node, translator, src_fname=None):
205 """Convert a image node for the builder.
206
207 Different builder prefer different image formats, e.g. *latex* builder
208 prefer PDF while *html* builder prefer SVG format for images.
209
210 This function handles output image formats in dependence of source the
211 format (of the image) and the translator's output format.
212 """
213 app = translator.builder.app
214
215 fname, in_ext = path.splitext(path.basename(img_node['uri']))
216 if src_fname is None:
217 src_fname = path.join(translator.builder.srcdir, img_node['uri'])
218 if not path.exists(src_fname):
219 src_fname = path.join(translator.builder.outdir, img_node['uri'])
220
221 dst_fname = None
222
223 # in kernel builds, use 'make SPHINXOPTS=-v' to see verbose messages
224
225 kernellog.verbose(app, 'assert best format for: ' + img_node['uri'])
226
227 if in_ext == '.dot':
228
229 if not dot_cmd:
230 kernellog.verbose(app,
231 "dot from graphviz not available / include DOT raw.")
232 img_node.replace_self(file2literal(src_fname))
233
234 elif translator.builder.format == 'latex':
235 dst_fname = path.join(translator.builder.outdir, fname + '.pdf')
236 img_node['uri'] = fname + '.pdf'
237 img_node['candidates'] = {'*': fname + '.pdf'}
238
239
240 elif translator.builder.format == 'html':
241 dst_fname = path.join(
242 translator.builder.outdir,
243 translator.builder.imagedir,
244 fname + '.svg')
245 img_node['uri'] = path.join(
246 translator.builder.imgpath, fname + '.svg')
247 img_node['candidates'] = {
248 '*': path.join(translator.builder.imgpath, fname + '.svg')}
249
250 else:
251 # all other builder formats will include DOT as raw
252 img_node.replace_self(file2literal(src_fname))
253
254 elif in_ext == '.svg':
255
256 if translator.builder.format == 'latex':
257 if convert_cmd is None:
258 kernellog.verbose(app,
259 "no SVG to PDF conversion available / include SVG raw.")
260 img_node.replace_self(file2literal(src_fname))
261 else:
262 dst_fname = path.join(translator.builder.outdir, fname + '.pdf')
263 img_node['uri'] = fname + '.pdf'
264 img_node['candidates'] = {'*': fname + '.pdf'}
265
266 if dst_fname:
267 # the builder needs not to copy one more time, so pop it if exists.
268 translator.builder.images.pop(img_node['uri'], None)
269 _name = dst_fname[len(translator.builder.outdir) + 1:]
270
271 if isNewer(dst_fname, src_fname):
272 kernellog.verbose(app,
273 "convert: {out}/%s already exists and is newer" % _name)
274
275 else:
276 ok = False
277 mkdir(path.dirname(dst_fname))
278
279 if in_ext == '.dot':
280 kernellog.verbose(app, 'convert DOT to: {out}/' + _name)
281 ok = dot2format(app, src_fname, dst_fname)
282
283 elif in_ext == '.svg':
284 kernellog.verbose(app, 'convert SVG to: {out}/' + _name)
285 ok = svg2pdf(app, src_fname, dst_fname)
286
287 if not ok:
288 img_node.replace_self(file2literal(src_fname))
289
290
291def dot2format(app, dot_fname, out_fname):
292 """Converts DOT file to ``out_fname`` using ``dot(1)``.
293
294 * ``dot_fname`` pathname of the input DOT file, including extension ``.dot``
295 * ``out_fname`` pathname of the output file, including format extension
296
297 The *format extension* depends on the ``dot`` command (see ``man dot``
298 option ``-Txxx``). Normally you will use one of the following extensions:
299
300 - ``.ps`` for PostScript,
301 - ``.svg`` or ``svgz`` for Structured Vector Graphics,
302 - ``.fig`` for XFIG graphics and
303 - ``.png`` or ``gif`` for common bitmap graphics.
304
305 """
306 out_format = path.splitext(out_fname)[1][1:]
307 cmd = [dot_cmd, '-T%s' % out_format, dot_fname]
308 exit_code = 42
309
310 with open(out_fname, "w") as out:
311 exit_code = subprocess.call(cmd, stdout = out)
312 if exit_code != 0:
313 kernellog.warn(app,
314 "Error #%d when calling: %s" % (exit_code, " ".join(cmd)))
315 return bool(exit_code == 0)
316
317def svg2pdf(app, svg_fname, pdf_fname):
318 """Converts SVG to PDF with ``convert(1)`` command.
319
320 Uses ``convert(1)`` from ImageMagick (https://www.imagemagick.org) for
321 conversion. Returns ``True`` on success and ``False`` if an error occurred.
322
323 * ``svg_fname`` pathname of the input SVG file with extension (``.svg``)
324 * ``pdf_name`` pathname of the output PDF file with extension (``.pdf``)
325
326 """
327 cmd = [convert_cmd, svg_fname, pdf_fname]
328 # use stdout and stderr from parent
329 exit_code = subprocess.call(cmd)
330 if exit_code != 0:
331 kernellog.warn(app, "Error #%d when calling: %s" % (exit_code, " ".join(cmd)))
332 return bool(exit_code == 0)
333
334
335# image handling
336# ---------------------
337
338def visit_kernel_image(self, node): # pylint: disable=W0613
339 """Visitor of the ``kernel_image`` Node.
340
341 Handles the ``image`` child-node with the ``convert_image(...)``.
342 """
343 img_node = node[0]
344 convert_image(img_node, self)
345
346class kernel_image(nodes.image):
347 """Node for ``kernel-image`` directive."""
348 pass
349
350class KernelImage(images.Image):
351 u"""KernelImage directive
352
353 Earns everything from ``.. image::`` directive, except *remote URI* and
354 *glob* pattern. The KernelImage wraps a image node into a
355 kernel_image node. See ``visit_kernel_image``.
356 """
357
358 def run(self):
359 uri = self.arguments[0]
360 if uri.endswith('.*') or uri.find('://') != -1:
361 raise self.severe(
362 'Error in "%s: %s": glob pattern and remote images are not allowed'
363 % (self.name, uri))
364 result = images.Image.run(self)
365 if len(result) == 2 or isinstance(result[0], nodes.system_message):
366 return result
367 (image_node,) = result
368 # wrap image node into a kernel_image node / see visitors
369 node = kernel_image('', image_node)
370 return [node]
371
372# figure handling
373# ---------------------
374
375def visit_kernel_figure(self, node): # pylint: disable=W0613
376 """Visitor of the ``kernel_figure`` Node.
377
378 Handles the ``image`` child-node with the ``convert_image(...)``.
379 """
380 img_node = node[0][0]
381 convert_image(img_node, self)
382
383class kernel_figure(nodes.figure):
384 """Node for ``kernel-figure`` directive."""
385
386class KernelFigure(Figure):
387 u"""KernelImage directive
388
389 Earns everything from ``.. figure::`` directive, except *remote URI* and
390 *glob* pattern. The KernelFigure wraps a figure node into a kernel_figure
391 node. See ``visit_kernel_figure``.
392 """
393
394 def run(self):
395 uri = self.arguments[0]
396 if uri.endswith('.*') or uri.find('://') != -1:
397 raise self.severe(
398 'Error in "%s: %s":'
399 ' glob pattern and remote images are not allowed'
400 % (self.name, uri))
401 result = Figure.run(self)
402 if len(result) == 2 or isinstance(result[0], nodes.system_message):
403 return result
404 (figure_node,) = result
405 # wrap figure node into a kernel_figure node / see visitors
406 node = kernel_figure('', figure_node)
407 return [node]
408
409
410# render handling
411# ---------------------
412
413def visit_kernel_render(self, node):
414 """Visitor of the ``kernel_render`` Node.
415
416 If rendering tools available, save the markup of the ``literal_block`` child
417 node into a file and replace the ``literal_block`` node with a new created
418 ``image`` node, pointing to the saved markup file. Afterwards, handle the
419 image child-node with the ``convert_image(...)``.
420 """
421 app = self.builder.app
422 srclang = node.get('srclang')
423
424 kernellog.verbose(app, 'visit kernel-render node lang: "%s"' % (srclang))
425
426 tmp_ext = RENDER_MARKUP_EXT.get(srclang, None)
427 if tmp_ext is None:
428 kernellog.warn(app, 'kernel-render: "%s" unknown / include raw.' % (srclang))
429 return
430
431 if not dot_cmd and tmp_ext == '.dot':
432 kernellog.verbose(app, "dot from graphviz not available / include raw.")
433 return
434
435 literal_block = node[0]
436
437 code = literal_block.astext()
438 hashobj = code.encode('utf-8') # str(node.attributes)
439 fname = path.join('%s-%s' % (srclang, sha1(hashobj).hexdigest()))
440
441 tmp_fname = path.join(
442 self.builder.outdir, self.builder.imagedir, fname + tmp_ext)
443
444 if not path.isfile(tmp_fname):
445 mkdir(path.dirname(tmp_fname))
446 with open(tmp_fname, "w") as out:
447 out.write(code)
448
449 img_node = nodes.image(node.rawsource, **node.attributes)
450 img_node['uri'] = path.join(self.builder.imgpath, fname + tmp_ext)
451 img_node['candidates'] = {
452 '*': path.join(self.builder.imgpath, fname + tmp_ext)}
453
454 literal_block.replace_self(img_node)
455 convert_image(img_node, self, tmp_fname)
456
457
458class kernel_render(nodes.General, nodes.Inline, nodes.Element):
459 """Node for ``kernel-render`` directive."""
460 pass
461
462class KernelRender(Figure):
463 u"""KernelRender directive
464
465 Render content by external tool. Has all the options known from the
466 *figure* directive, plus option ``caption``. If ``caption`` has a
467 value, a figure node with the *caption* is inserted. If not, a image node is
468 inserted.
469
470 The KernelRender directive wraps the text of the directive into a
471 literal_block node and wraps it into a kernel_render node. See
472 ``visit_kernel_render``.
473 """
474 has_content = True
475 required_arguments = 1
476 optional_arguments = 0
477 final_argument_whitespace = False
478
479 # earn options from 'figure'
480 option_spec = Figure.option_spec.copy()
481 option_spec['caption'] = directives.unchanged
482
483 def run(self):
484 return [self.build_node()]
485
486 def build_node(self):
487
488 srclang = self.arguments[0].strip()
489 if srclang not in RENDER_MARKUP_EXT.keys():
490 return [self.state_machine.reporter.warning(
491 'Unknown source language "%s", use one of: %s.' % (
492 srclang, ",".join(RENDER_MARKUP_EXT.keys())),
493 line=self.lineno)]
494
495 code = '\n'.join(self.content)
496 if not code.strip():
497 return [self.state_machine.reporter.warning(
498 'Ignoring "%s" directive without content.' % (
499 self.name),
500 line=self.lineno)]
501
502 node = kernel_render()
503 node['alt'] = self.options.get('alt','')
504 node['srclang'] = srclang
505 literal_node = nodes.literal_block(code, code)
506 node += literal_node
507
508 caption = self.options.get('caption')
509 if caption:
510 # parse caption's content
511 parsed = nodes.Element()
512 self.state.nested_parse(
513 ViewList([caption], source=''), self.content_offset, parsed)
514 caption_node = nodes.caption(
515 parsed[0].rawsource, '', *parsed[0].children)
516 caption_node.source = parsed[0].source
517 caption_node.line = parsed[0].line
518
519 figure_node = nodes.figure('', node)
520 for k,v in self.options.items():
521 figure_node[k] = v
522 figure_node += caption_node
523
524 node = figure_node
525
526 return node
527
528def add_kernel_figure_to_std_domain(app, doctree):
529 """Add kernel-figure anchors to 'std' domain.
530
531 The ``StandardDomain.process_doc(..)`` method does not know how to resolve
532 the caption (label) of ``kernel-figure`` directive (it only knows about
533 standard nodes, e.g. table, figure etc.). Without any additional handling
534 this will result in a 'undefined label' for kernel-figures.
535
536 This handle adds labels of kernel-figure to the 'std' domain labels.
537 """
538
539 std = app.env.domains["std"]
540 docname = app.env.docname
541 labels = std.data["labels"]
542
543 for name, explicit in iteritems(doctree.nametypes):
544 if not explicit:
545 continue
546 labelid = doctree.nameids[name]
547 if labelid is None:
548 continue
549 node = doctree.ids[labelid]
550
551 if node.tagname == 'kernel_figure':
552 for n in node.next_node():
553 if n.tagname == 'caption':
554 sectname = clean_astext(n)
555 # add label to std domain
556 labels[name] = docname, labelid, sectname
557 break
1# -*- coding: utf-8; mode: python -*-
2# pylint: disable=C0103, R0903, R0912, R0915
3u"""
4 scalable figure and image handling
5 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
6
7 Sphinx extension which implements scalable image handling.
8
9 :copyright: Copyright (C) 2016 Markus Heiser
10 :license: GPL Version 2, June 1991 see Linux/COPYING for details.
11
12 The build for image formats depend on image's source format and output's
13 destination format. This extension implement methods to simplify image
14 handling from the author's POV. Directives like ``kernel-figure`` implement
15 methods *to* always get the best output-format even if some tools are not
16 installed. For more details take a look at ``convert_image(...)`` which is
17 the core of all conversions.
18
19 * ``.. kernel-image``: for image handling / a ``.. image::`` replacement
20
21 * ``.. kernel-figure``: for figure handling / a ``.. figure::`` replacement
22
23 * ``.. kernel-render``: for render markup / a concept to embed *render*
24 markups (or languages). Supported markups (see ``RENDER_MARKUP_EXT``)
25
26 - ``DOT``: render embedded Graphviz's **DOC**
27 - ``SVG``: render embedded Scalable Vector Graphics (**SVG**)
28 - ... *developable*
29
30 Used tools:
31
32 * ``dot(1)``: Graphviz (https://www.graphviz.org). If Graphviz is not
33 available, the DOT language is inserted as literal-block.
34
35 * SVG to PDF: To generate PDF, you need at least one of this tools:
36
37 - ``convert(1)``: ImageMagick (https://www.imagemagick.org)
38
39 List of customizations:
40
41 * generate PDF from SVG / used by PDF (LaTeX) builder
42
43 * generate SVG (html-builder) and PDF (latex-builder) from DOT files.
44 DOT: see https://www.graphviz.org/content/dot-language
45
46 """
47
48import os
49from os import path
50import subprocess
51from hashlib import sha1
52from docutils import nodes
53from docutils.statemachine import ViewList
54from docutils.parsers.rst import directives
55from docutils.parsers.rst.directives import images
56import sphinx
57from sphinx.util.nodes import clean_astext
58import kernellog
59
60# Get Sphinx version
61major, minor, patch = sphinx.version_info[:3]
62if major == 1 and minor > 3:
63 # patches.Figure only landed in Sphinx 1.4
64 from sphinx.directives.patches import Figure # pylint: disable=C0413
65else:
66 Figure = images.Figure
67
68__version__ = '1.0.0'
69
70# simple helper
71# -------------
72
73def which(cmd):
74 """Searches the ``cmd`` in the ``PATH`` environment.
75
76 This *which* searches the PATH for executable ``cmd`` . First match is
77 returned, if nothing is found, ``None` is returned.
78 """
79 envpath = os.environ.get('PATH', None) or os.defpath
80 for folder in envpath.split(os.pathsep):
81 fname = folder + os.sep + cmd
82 if path.isfile(fname):
83 return fname
84
85def mkdir(folder, mode=0o775):
86 if not path.isdir(folder):
87 os.makedirs(folder, mode)
88
89def file2literal(fname):
90 with open(fname, "r") as src:
91 data = src.read()
92 node = nodes.literal_block(data, data)
93 return node
94
95def isNewer(path1, path2):
96 """Returns True if ``path1`` is newer than ``path2``
97
98 If ``path1`` exists and is newer than ``path2`` the function returns
99 ``True`` is returned otherwise ``False``
100 """
101 return (path.exists(path1)
102 and os.stat(path1).st_ctime > os.stat(path2).st_ctime)
103
104def pass_handle(self, node): # pylint: disable=W0613
105 pass
106
107# setup conversion tools and sphinx extension
108# -------------------------------------------
109
110# Graphviz's dot(1) support
111dot_cmd = None
112
113# ImageMagick' convert(1) support
114convert_cmd = None
115
116
117def setup(app):
118 # check toolchain first
119 app.connect('builder-inited', setupTools)
120
121 # image handling
122 app.add_directive("kernel-image", KernelImage)
123 app.add_node(kernel_image,
124 html = (visit_kernel_image, pass_handle),
125 latex = (visit_kernel_image, pass_handle),
126 texinfo = (visit_kernel_image, pass_handle),
127 text = (visit_kernel_image, pass_handle),
128 man = (visit_kernel_image, pass_handle), )
129
130 # figure handling
131 app.add_directive("kernel-figure", KernelFigure)
132 app.add_node(kernel_figure,
133 html = (visit_kernel_figure, pass_handle),
134 latex = (visit_kernel_figure, pass_handle),
135 texinfo = (visit_kernel_figure, pass_handle),
136 text = (visit_kernel_figure, pass_handle),
137 man = (visit_kernel_figure, pass_handle), )
138
139 # render handling
140 app.add_directive('kernel-render', KernelRender)
141 app.add_node(kernel_render,
142 html = (visit_kernel_render, pass_handle),
143 latex = (visit_kernel_render, pass_handle),
144 texinfo = (visit_kernel_render, pass_handle),
145 text = (visit_kernel_render, pass_handle),
146 man = (visit_kernel_render, pass_handle), )
147
148 app.connect('doctree-read', add_kernel_figure_to_std_domain)
149
150 return dict(
151 version = __version__,
152 parallel_read_safe = True,
153 parallel_write_safe = True
154 )
155
156
157def setupTools(app):
158 u"""
159 Check available build tools and log some *verbose* messages.
160
161 This function is called once, when the builder is initiated.
162 """
163 global dot_cmd, convert_cmd # pylint: disable=W0603
164 kernellog.verbose(app, "kfigure: check installed tools ...")
165
166 dot_cmd = which('dot')
167 convert_cmd = which('convert')
168
169 if dot_cmd:
170 kernellog.verbose(app, "use dot(1) from: " + dot_cmd)
171 else:
172 kernellog.warn(app, "dot(1) not found, for better output quality install "
173 "graphviz from https://www.graphviz.org")
174 if convert_cmd:
175 kernellog.verbose(app, "use convert(1) from: " + convert_cmd)
176 else:
177 kernellog.warn(app,
178 "convert(1) not found, for SVG to PDF conversion install "
179 "ImageMagick (https://www.imagemagick.org)")
180
181
182# integrate conversion tools
183# --------------------------
184
185RENDER_MARKUP_EXT = {
186 # The '.ext' must be handled by convert_image(..) function's *in_ext* input.
187 # <name> : <.ext>
188 'DOT' : '.dot',
189 'SVG' : '.svg'
190}
191
192def convert_image(img_node, translator, src_fname=None):
193 """Convert a image node for the builder.
194
195 Different builder prefer different image formats, e.g. *latex* builder
196 prefer PDF while *html* builder prefer SVG format for images.
197
198 This function handles output image formats in dependence of source the
199 format (of the image) and the translator's output format.
200 """
201 app = translator.builder.app
202
203 fname, in_ext = path.splitext(path.basename(img_node['uri']))
204 if src_fname is None:
205 src_fname = path.join(translator.builder.srcdir, img_node['uri'])
206 if not path.exists(src_fname):
207 src_fname = path.join(translator.builder.outdir, img_node['uri'])
208
209 dst_fname = None
210
211 # in kernel builds, use 'make SPHINXOPTS=-v' to see verbose messages
212
213 kernellog.verbose(app, 'assert best format for: ' + img_node['uri'])
214
215 if in_ext == '.dot':
216
217 if not dot_cmd:
218 kernellog.verbose(app,
219 "dot from graphviz not available / include DOT raw.")
220 img_node.replace_self(file2literal(src_fname))
221
222 elif translator.builder.format == 'latex':
223 dst_fname = path.join(translator.builder.outdir, fname + '.pdf')
224 img_node['uri'] = fname + '.pdf'
225 img_node['candidates'] = {'*': fname + '.pdf'}
226
227
228 elif translator.builder.format == 'html':
229 dst_fname = path.join(
230 translator.builder.outdir,
231 translator.builder.imagedir,
232 fname + '.svg')
233 img_node['uri'] = path.join(
234 translator.builder.imgpath, fname + '.svg')
235 img_node['candidates'] = {
236 '*': path.join(translator.builder.imgpath, fname + '.svg')}
237
238 else:
239 # all other builder formats will include DOT as raw
240 img_node.replace_self(file2literal(src_fname))
241
242 elif in_ext == '.svg':
243
244 if translator.builder.format == 'latex':
245 if convert_cmd is None:
246 kernellog.verbose(app,
247 "no SVG to PDF conversion available / include SVG raw.")
248 img_node.replace_self(file2literal(src_fname))
249 else:
250 dst_fname = path.join(translator.builder.outdir, fname + '.pdf')
251 img_node['uri'] = fname + '.pdf'
252 img_node['candidates'] = {'*': fname + '.pdf'}
253
254 if dst_fname:
255 # the builder needs not to copy one more time, so pop it if exists.
256 translator.builder.images.pop(img_node['uri'], None)
257 _name = dst_fname[len(translator.builder.outdir) + 1:]
258
259 if isNewer(dst_fname, src_fname):
260 kernellog.verbose(app,
261 "convert: {out}/%s already exists and is newer" % _name)
262
263 else:
264 ok = False
265 mkdir(path.dirname(dst_fname))
266
267 if in_ext == '.dot':
268 kernellog.verbose(app, 'convert DOT to: {out}/' + _name)
269 ok = dot2format(app, src_fname, dst_fname)
270
271 elif in_ext == '.svg':
272 kernellog.verbose(app, 'convert SVG to: {out}/' + _name)
273 ok = svg2pdf(app, src_fname, dst_fname)
274
275 if not ok:
276 img_node.replace_self(file2literal(src_fname))
277
278
279def dot2format(app, dot_fname, out_fname):
280 """Converts DOT file to ``out_fname`` using ``dot(1)``.
281
282 * ``dot_fname`` pathname of the input DOT file, including extension ``.dot``
283 * ``out_fname`` pathname of the output file, including format extension
284
285 The *format extension* depends on the ``dot`` command (see ``man dot``
286 option ``-Txxx``). Normally you will use one of the following extensions:
287
288 - ``.ps`` for PostScript,
289 - ``.svg`` or ``svgz`` for Structured Vector Graphics,
290 - ``.fig`` for XFIG graphics and
291 - ``.png`` or ``gif`` for common bitmap graphics.
292
293 """
294 out_format = path.splitext(out_fname)[1][1:]
295 cmd = [dot_cmd, '-T%s' % out_format, dot_fname]
296 exit_code = 42
297
298 with open(out_fname, "w") as out:
299 exit_code = subprocess.call(cmd, stdout = out)
300 if exit_code != 0:
301 kernellog.warn(app,
302 "Error #%d when calling: %s" % (exit_code, " ".join(cmd)))
303 return bool(exit_code == 0)
304
305def svg2pdf(app, svg_fname, pdf_fname):
306 """Converts SVG to PDF with ``convert(1)`` command.
307
308 Uses ``convert(1)`` from ImageMagick (https://www.imagemagick.org) for
309 conversion. Returns ``True`` on success and ``False`` if an error occurred.
310
311 * ``svg_fname`` pathname of the input SVG file with extension (``.svg``)
312 * ``pdf_name`` pathname of the output PDF file with extension (``.pdf``)
313
314 """
315 cmd = [convert_cmd, svg_fname, pdf_fname]
316 # use stdout and stderr from parent
317 exit_code = subprocess.call(cmd)
318 if exit_code != 0:
319 kernellog.warn(app, "Error #%d when calling: %s" % (exit_code, " ".join(cmd)))
320 return bool(exit_code == 0)
321
322
323# image handling
324# ---------------------
325
326def visit_kernel_image(self, node): # pylint: disable=W0613
327 """Visitor of the ``kernel_image`` Node.
328
329 Handles the ``image`` child-node with the ``convert_image(...)``.
330 """
331 img_node = node[0]
332 convert_image(img_node, self)
333
334class kernel_image(nodes.image):
335 """Node for ``kernel-image`` directive."""
336 pass
337
338class KernelImage(images.Image):
339 u"""KernelImage directive
340
341 Earns everything from ``.. image::`` directive, except *remote URI* and
342 *glob* pattern. The KernelImage wraps a image node into a
343 kernel_image node. See ``visit_kernel_image``.
344 """
345
346 def run(self):
347 uri = self.arguments[0]
348 if uri.endswith('.*') or uri.find('://') != -1:
349 raise self.severe(
350 'Error in "%s: %s": glob pattern and remote images are not allowed'
351 % (self.name, uri))
352 result = images.Image.run(self)
353 if len(result) == 2 or isinstance(result[0], nodes.system_message):
354 return result
355 (image_node,) = result
356 # wrap image node into a kernel_image node / see visitors
357 node = kernel_image('', image_node)
358 return [node]
359
360# figure handling
361# ---------------------
362
363def visit_kernel_figure(self, node): # pylint: disable=W0613
364 """Visitor of the ``kernel_figure`` Node.
365
366 Handles the ``image`` child-node with the ``convert_image(...)``.
367 """
368 img_node = node[0][0]
369 convert_image(img_node, self)
370
371class kernel_figure(nodes.figure):
372 """Node for ``kernel-figure`` directive."""
373
374class KernelFigure(Figure):
375 u"""KernelImage directive
376
377 Earns everything from ``.. figure::`` directive, except *remote URI* and
378 *glob* pattern. The KernelFigure wraps a figure node into a kernel_figure
379 node. See ``visit_kernel_figure``.
380 """
381
382 def run(self):
383 uri = self.arguments[0]
384 if uri.endswith('.*') or uri.find('://') != -1:
385 raise self.severe(
386 'Error in "%s: %s":'
387 ' glob pattern and remote images are not allowed'
388 % (self.name, uri))
389 result = Figure.run(self)
390 if len(result) == 2 or isinstance(result[0], nodes.system_message):
391 return result
392 (figure_node,) = result
393 # wrap figure node into a kernel_figure node / see visitors
394 node = kernel_figure('', figure_node)
395 return [node]
396
397
398# render handling
399# ---------------------
400
401def visit_kernel_render(self, node):
402 """Visitor of the ``kernel_render`` Node.
403
404 If rendering tools available, save the markup of the ``literal_block`` child
405 node into a file and replace the ``literal_block`` node with a new created
406 ``image`` node, pointing to the saved markup file. Afterwards, handle the
407 image child-node with the ``convert_image(...)``.
408 """
409 app = self.builder.app
410 srclang = node.get('srclang')
411
412 kernellog.verbose(app, 'visit kernel-render node lang: "%s"' % (srclang))
413
414 tmp_ext = RENDER_MARKUP_EXT.get(srclang, None)
415 if tmp_ext is None:
416 kernellog.warn(app, 'kernel-render: "%s" unknown / include raw.' % (srclang))
417 return
418
419 if not dot_cmd and tmp_ext == '.dot':
420 kernellog.verbose(app, "dot from graphviz not available / include raw.")
421 return
422
423 literal_block = node[0]
424
425 code = literal_block.astext()
426 hashobj = code.encode('utf-8') # str(node.attributes)
427 fname = path.join('%s-%s' % (srclang, sha1(hashobj).hexdigest()))
428
429 tmp_fname = path.join(
430 self.builder.outdir, self.builder.imagedir, fname + tmp_ext)
431
432 if not path.isfile(tmp_fname):
433 mkdir(path.dirname(tmp_fname))
434 with open(tmp_fname, "w") as out:
435 out.write(code)
436
437 img_node = nodes.image(node.rawsource, **node.attributes)
438 img_node['uri'] = path.join(self.builder.imgpath, fname + tmp_ext)
439 img_node['candidates'] = {
440 '*': path.join(self.builder.imgpath, fname + tmp_ext)}
441
442 literal_block.replace_self(img_node)
443 convert_image(img_node, self, tmp_fname)
444
445
446class kernel_render(nodes.General, nodes.Inline, nodes.Element):
447 """Node for ``kernel-render`` directive."""
448 pass
449
450class KernelRender(Figure):
451 u"""KernelRender directive
452
453 Render content by external tool. Has all the options known from the
454 *figure* directive, plus option ``caption``. If ``caption`` has a
455 value, a figure node with the *caption* is inserted. If not, a image node is
456 inserted.
457
458 The KernelRender directive wraps the text of the directive into a
459 literal_block node and wraps it into a kernel_render node. See
460 ``visit_kernel_render``.
461 """
462 has_content = True
463 required_arguments = 1
464 optional_arguments = 0
465 final_argument_whitespace = False
466
467 # earn options from 'figure'
468 option_spec = Figure.option_spec.copy()
469 option_spec['caption'] = directives.unchanged
470
471 def run(self):
472 return [self.build_node()]
473
474 def build_node(self):
475
476 srclang = self.arguments[0].strip()
477 if srclang not in RENDER_MARKUP_EXT.keys():
478 return [self.state_machine.reporter.warning(
479 'Unknown source language "%s", use one of: %s.' % (
480 srclang, ",".join(RENDER_MARKUP_EXT.keys())),
481 line=self.lineno)]
482
483 code = '\n'.join(self.content)
484 if not code.strip():
485 return [self.state_machine.reporter.warning(
486 'Ignoring "%s" directive without content.' % (
487 self.name),
488 line=self.lineno)]
489
490 node = kernel_render()
491 node['alt'] = self.options.get('alt','')
492 node['srclang'] = srclang
493 literal_node = nodes.literal_block(code, code)
494 node += literal_node
495
496 caption = self.options.get('caption')
497 if caption:
498 # parse caption's content
499 parsed = nodes.Element()
500 self.state.nested_parse(
501 ViewList([caption], source=''), self.content_offset, parsed)
502 caption_node = nodes.caption(
503 parsed[0].rawsource, '', *parsed[0].children)
504 caption_node.source = parsed[0].source
505 caption_node.line = parsed[0].line
506
507 figure_node = nodes.figure('', node)
508 for k,v in self.options.items():
509 figure_node[k] = v
510 figure_node += caption_node
511
512 node = figure_node
513
514 return node
515
516def add_kernel_figure_to_std_domain(app, doctree):
517 """Add kernel-figure anchors to 'std' domain.
518
519 The ``StandardDomain.process_doc(..)`` method does not know how to resolve
520 the caption (label) of ``kernel-figure`` directive (it only knows about
521 standard nodes, e.g. table, figure etc.). Without any additional handling
522 this will result in a 'undefined label' for kernel-figures.
523
524 This handle adds labels of kernel-figure to the 'std' domain labels.
525 """
526
527 std = app.env.domains["std"]
528 docname = app.env.docname
529 labels = std.data["labels"]
530
531 for name, explicit in doctree.nametypes.items():
532 if not explicit:
533 continue
534 labelid = doctree.nameids[name]
535 if labelid is None:
536 continue
537 node = doctree.ids[labelid]
538
539 if node.tagname == 'kernel_figure':
540 for n in node.next_node():
541 if n.tagname == 'caption':
542 sectname = clean_astext(n)
543 # add label to std domain
544 labels[name] = docname, labelid, sectname
545 break