Documentation/sphinx/kfigure.py

1 # -*- coding: utf-8; mode: python -*-
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
19     * ``.. kernel-image``: for image handling / a ``.. image::`` replacement
21     * ``.. kernel-figure``: for figure handling / a ``.. figure::`` replacement
23     * ``.. kernel-render``: for render markup / a concept to embed *render*
26       - ``DOT``: render embedded Graphviz's **DOC**
27       - ``SVG``: render embedded Scalable Vector Graphics (**SVG**)
28       - ... *developable*
33       available, the DOT language is inserted as literal-block.
34       For conversion to PDF, ``rsvg-convert(1)`` of librsvg
39       - ``convert(1)``: ImageMagick (https://www.imagemagick.org)
40       - ``inkscape(1)``: Inkscape (https://inkscape.org/)
46     * generate SVG (html-builder) and PDF (latex-builder) from DOT files.
47       DOT: see https://www.graphviz.org/content/dot-language
52 from os import path
71 # -------------
74     """Searches the ``cmd`` in the ``PATH`` environment.
76     This *which* searches the PATH for executable ``cmd`` . First match is
79     envpath = os.environ.get('PATH', None) or os.defpath
82         if path.isfile(fname):
86     if not path.isdir(folder):
101     return (path.exists(path1)
108 # -------------------------------------------
112 # dot(1) -Tpdf should be used
118 # librsvg's rsvg-convert(1) support
129     app.connect('builder-inited', setupTools)
132     app.add_directive("kernel-image",  KernelImage)
141     app.add_directive("kernel-figure", KernelFigure)
150     app.add_directive('kernel-render', KernelRender)
158     app.connect('doctree-read', add_kernel_figure_to_std_domain)
179     rsvg_convert_cmd = which('rsvg-convert')
186             dot_Thelp_list = subprocess.check_output([dot_cmd, '-Thelp'],
187                                     stderr=subprocess.STDOUT)
200         inkscape_ver = subprocess.check_output([inkscape_cmd, '--version'],
219             logger.verbose("use rsvg-convert(1) from: " + rsvg_convert_cmd)
220             logger.verbose("use 'dot -Tsvg' and rsvg-convert(1) for DOT -> PDF conversion")
224                 "rsvg-convert(1) not found.\n"
225                 "  SVG rendering of convert(1) is done by ImageMagick-native renderer."
228                 logger.verbose("use 'dot -Tpdf' for DOT -> PDF conversion")
230                 logger.verbose("use 'dot -Tsvg' and convert(1) for DOT -> PDF conversion")
234 # --------------------------
254     fname, in_ext = path.splitext(path.basename(img_node['uri']))
256         src_fname = path.join(translator.builder.srcdir, img_node['uri'])
257         if not path.exists(src_fname):
258             src_fname = path.join(translator.builder.outdir, img_node['uri'])
262     # in kernel builds, use 'make SPHINXOPTS=-v' to see verbose messages
273             dst_fname = path.join(translator.builder.outdir, fname + '.pdf')
279             dst_fname = path.join(
283             img_node['uri'] = path.join(
286                 '*': path.join(translator.builder.imgpath, fname + '.svg')}
303                 dst_fname = path.join(translator.builder.outdir, fname + '.pdf')
317             mkdir(path.dirname(dst_fname))
322                     svg_fname = path.join(translator.builder.outdir, fname + '.svg')
345     option ``-Txxx``). Normally you will use one of the following extensions:
347     - ``.ps`` for PostScript,
348     - ``.svg`` or ``svgz`` for Structured Vector Graphics,
349     - ``.fig`` for XFIG graphics and
350     - ``.png`` or ``gif`` for common bitmap graphics.
353     out_format = path.splitext(out_fname)[1][1:]
354     cmd = [dot_cmd, '-T%s' % out_format, dot_fname]
358         exit_code = subprocess.call(cmd, stdout = out)
381             cmd = [inkscape_cmd, '-o', pdf_fname, svg_fname]
383             cmd = [inkscape_cmd, '-z', '--export-pdf=%s' % pdf_fname, svg_fname]
386         warning_msg = subprocess.check_output(cmd, stderr=subprocess.STDOUT)
398                                 (cmd_name, str(warning_msg, 'utf-8')))
401                             (cmd_name, str(warning_msg, 'utf-8')))
406     """Convert SVG to PDF with ``rsvg-convert(1)`` command.
412     SVG -> PDF conversion is done by ``rsvg-convert(1)``.
414     If ``rsvg-convert(1)`` is unavailable, fall back to ``svg2pdf()``.
421         cmd = [rsvg_convert_cmd, '--format=pdf', '-o', pdf_fname, svg_fname]
422         # use stdout and stderr from parent
433 # ---------------------
438     Handles the ``image`` child-node with the ``convert_image(...)``.
444     """Node for ``kernel-image`` directive."""
457         if uri.endswith('.*') or uri.find('://') != -1:
470 # ---------------------
475     Handles the ``image`` child-node with the ``convert_image(...)``.
481     """Node for ``kernel-figure`` directive."""
493         if uri.endswith('.*') or uri.find('://') != -1:
508 # ---------------------
516     image child-node with the ``convert_image(...)``.
521     logger.verbose('visit kernel-render node lang: "%s"' % srclang)
525         logger.warning( 'kernel-render: "%s" unknown / include raw.' % srclang)
535     hashobj   = code.encode('utf-8') #  str(node.attributes)
536     fname     = path.join('%s-%s' % (srclang, sha1(hashobj).hexdigest()))
538     tmp_fname = path.join(
541     if not path.isfile(tmp_fname):
542         mkdir(path.dirname(tmp_fname))
547     img_node['uri'] = path.join(self.builder.imgpath, fname + tmp_ext)
549         '*': path.join(self.builder.imgpath, fname + tmp_ext)}
556     """Node for ``kernel-render`` directive."""
626     """Add kernel-figure anchors to 'std' domain.
629     the caption (label) of ``kernel-figure`` directive (it only knows about
631     this will result in a 'undefined label' for kernel-figures.
633     This handle adds labels of kernel-figure to the 'std' domain labels.