On Thu, Dec 15, 2016 at 06:01:42PM +0100, Daniel Vetter wrote: > On Wed, Dec 07, 2016 at 09:49:44AM +0100, Markus Heiser wrote: > > This patch brings scalable figure, image handling and a concept to > > embed *render* markups: > > > > * DOT (http://www.graphviz.org) > > * SVG > > > > For image handling use the 'image' replacement:: > > > > .. kernel-image:: svg_image.svg > > :alt: simple SVG image > > > > For figure handling use the 'figure' replacement:: > > > > .. kernel-figure:: svg_image.svg > > :alt: simple SVG image > > > > SVG image example > > > > Embed *render* markups (or languages) like Graphviz's **DOC** is > > provided by the *render* directive.:: > > > > .. kernel-render:: DOT > > :alt: foobar digraph > > :caption: Embedded **DOT** (Graphviz) code. > > > > digraph foo { > > "bar" -> "baz"; > > } > > > > The *render* directive is a concept to integrate *render* markups and > > languages, yet supported markups: > > > > * DOT: render embedded Graphviz's **DOC** > > * SVG: render embedded Scalable Vector Graphics (**SVG**) > > > > Signed-off-by: Markus Heiser <markus.heiser@xxxxxxxxxxx> > > I started playing around with this. Another thing I've noticed after adding my hack, and I don't even know how that works in your code so top comment: The auto-generated .dot file for in-line kernel-render directives seems to depend upon the content and doesn't get auto-removed. Which means when I change back to an old version of an inline dot it's not regenerated. Which also means I don't get to see the stderr output again. For the kernel-render directive I think it'd be better to pass the graph to dot via stdin. -Daniel > > > --- > > Documentation/conf.py | 2 +- > > Documentation/doc-guide/hello.dot | 3 + > > Documentation/doc-guide/sphinx.rst | 90 +++++- > > Documentation/doc-guide/svg_image.svg | 10 + > > Documentation/process/changes.rst | 8 +- > > Documentation/sphinx/kfigure.py | 505 ++++++++++++++++++++++++++++++++++ > > 6 files changed, 612 insertions(+), 6 deletions(-) > > create mode 100644 Documentation/doc-guide/hello.dot > > create mode 100644 Documentation/doc-guide/svg_image.svg > > create mode 100644 Documentation/sphinx/kfigure.py > > > > diff --git a/Documentation/conf.py b/Documentation/conf.py > > index 1ac958c..19ea030 100644 > > --- a/Documentation/conf.py > > +++ b/Documentation/conf.py > > @@ -34,7 +34,7 @@ from load_config import loadConfig > > # Add any Sphinx extension module names here, as strings. They can be > > # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom > > # ones. > > -extensions = ['kerneldoc', 'rstFlatTable', 'kernel_include', 'cdomain'] > > +extensions = ['kerneldoc', 'rstFlatTable', 'kernel_include', 'cdomain', 'kfigure'] > > > > # The name of the math extension changed on Sphinx 1.4 > > if major == 1 and minor > 3: > > diff --git a/Documentation/doc-guide/hello.dot b/Documentation/doc-guide/hello.dot > > new file mode 100644 > > index 0000000..504621d > > --- /dev/null > > +++ b/Documentation/doc-guide/hello.dot > > @@ -0,0 +1,3 @@ > > +graph G { > > + Hello -- World > > +} > > diff --git a/Documentation/doc-guide/sphinx.rst b/Documentation/doc-guide/sphinx.rst > > index 96fe7ccb..c7c7876 100644 > > --- a/Documentation/doc-guide/sphinx.rst > > +++ b/Documentation/doc-guide/sphinx.rst > > @@ -34,8 +34,10 @@ format-specific subdirectories under ``Documentation/output``. > > > > To generate documentation, Sphinx (``sphinx-build``) must obviously be > > installed. For prettier HTML output, the Read the Docs Sphinx theme > > -(``sphinx_rtd_theme``) is used if available. For PDF output, ``rst2pdf`` is also > > -needed. All of these are widely available and packaged in distributions. > > +(``sphinx_rtd_theme``) is used if available. For PDF output you'll also need > > +``XeLaTeX`` and CairoSVG (http://cairosvg.org) or alternatively ``convert(1)`` > > +from ImageMagick (https://www.imagemagick.org). All of these are widely > > +available and packaged in distributions. > > > > To pass extra options to Sphinx, you can use the ``SPHINXOPTS`` make > > variable. For example, use ``make SPHINXOPTS=-v htmldocs`` to get more verbose > > @@ -217,3 +219,87 @@ Rendered as: > > * .. _`last row`: > > > > - column 3 > > + > > + > > +Figures & Images > > +================ > > + > > +If you want to add an image, you should use the ``kernel-figure`` and > > +``kernel-image`` directives. E.g. to insert a figure with a scalable > > +image format use SVG:: > > + > > + .. kernel-figure:: svg_image.svg > > + :alt: simple SVG image > > + > > + SVG image example > > + > > +.. kernel-figure:: svg_image.svg > > + :alt: simple SVG image > > + > > + SVG image example > > + > > +The kernel figure (and image) directive support **DOT** formated files, see > > + > > +* DOT: http://graphviz.org/pdf/dotguide.pdf > > +* Graphviz: http://www.graphviz.org/content/dot-language > > + > > +A simple example:: > > + > > + .. kernel-figure:: hello.dot > > + :alt: hello world > > + > > + DOT's hello world example > > + > > +.. kernel-figure:: hello.dot > > + :alt: hello world > > + > > + DOT's hello world example > > + > > +Embed *render* markups (or languages) like Graphviz's **DOC** is provided by the > > s/DOC/DOT/ I think? Same in the commit message. > > > +``kernel-render`` directives.:: > > + > > + .. kernel-render:: DOT > > + :alt: foobar digraph > > + :caption: Embedded **DOT** (Graphviz) code. > > + > > + digraph foo { > > + "bar" -> "baz"; > > + } > > + > > +How this will be rendered depends on the installed tools. If Graphviz is > > +installed, you will see an vector image. If not the raw markup is inserted as > > +*literal-block*. > > + > > +.. kernel-render:: DOT > > + :alt: foobar digraph > > + :caption: Embedded **DOT** (Graphviz) code. > > + > > + digraph foo { > > + "bar" -> "baz"; > > + } > > + > > +The *render* directive has all the options known from the *figure* directive, > > +plus option ``caption``. If ``caption`` has a value, a *figure* node is > > +inserted. If not, a *image* node is inserted. > > + > > +Embedded **SVG**:: > > + > > + .. kernel-render:: SVG > > + :caption: Embedded **SVG** markup. > > + :alt: so-nw-arrow > > + > > + <?xml version="1.0" encoding="UTF-8"?> > > + <svg xmlns="http://www.w3.org/2000/svg"; version="1.1" ...> > > + ... > > + </svg> > > + > > +.. kernel-render:: SVG > > + :caption: Embedded **SVG** markup. > > + :alt: so-nw-arrow > > + > > + <?xml version="1.0" encoding="UTF-8"?> > > + <svg xmlns="http://www.w3.org/2000/svg"; > > + version="1.1" baseProfile="full" width="70px" height="40px" viewBox="0 0 700 400"> > > + <line x1="180" y1="370" x2="500" y2="50" stroke="black" stroke-width="15px"/> > > + <polygon points="585 0 525 25 585 50" transform="rotate(135 525 25)"/> > > + </svg> > > diff --git a/Documentation/doc-guide/svg_image.svg b/Documentation/doc-guide/svg_image.svg > > new file mode 100644 > > index 0000000..5405f85 > > --- /dev/null > > +++ b/Documentation/doc-guide/svg_image.svg > > @@ -0,0 +1,10 @@ > > +<?xml version="1.0" encoding="UTF-8"?> > > +<!-- originate: https://commons.wikimedia.org/wiki/File:Variable_Resistor.svg --> > > +<svg xmlns="http://www.w3.org/2000/svg"; > > + version="1.1" baseProfile="full" > > + width="70px" height="40px" viewBox="0 0 700 400"> > > + <line x1="0" y1="200" x2="700" y2="200" stroke="black" stroke-width="20px"/> > > + <rect x="100" y="100" width="500" height="200" fill="white" stroke="black" stroke-width="20px"/> > > + <line x1="180" y1="370" x2="500" y2="50" stroke="black" stroke-width="15px"/> > > + <polygon points="585 0 525 25 585 50" transform="rotate(135 525 25)"/> > > +</svg> > > diff --git a/Documentation/process/changes.rst b/Documentation/process/changes.rst > > index 56ce661..de284ca 100644 > > --- a/Documentation/process/changes.rst > > +++ b/Documentation/process/changes.rst > > @@ -318,9 +318,11 @@ PDF outputs, it is recommended to use version 1.4.6. > > .. note:: > > > > Please notice that, for PDF and LaTeX output, you'll also need ``XeLaTeX`` > > - version 3.14159265. Depending on the distribution, you may also need > > - to install a series of ``texlive`` packages that provide the minimal > > - set of functionalities required for ``XeLaTex`` to work. > > + version 3.14159265. Depending on the distribution, you may also need to > > + install a series of ``texlive`` packages that provide the minimal set of > > + functionalities required for ``XeLaTex`` to work. For PDF output you'll also > > + need CairoSVG (http://cairosvg.org) or alternatively ``convert(1)`` from > > + ImageMagick (https://www.imagemagick.org). > > > > Other tools > > ----------- > > diff --git a/Documentation/sphinx/kfigure.py b/Documentation/sphinx/kfigure.py > > new file mode 100644 > > index 0000000..76425b4 > > --- /dev/null > > +++ b/Documentation/sphinx/kfigure.py > > @@ -0,0 +1,505 @@ > > +# -*- coding: utf-8; mode: python -*- > > +# pylint: disable=C0103 > > +u""" > > + scalable figure and image handling > > + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ > > + > > + Sphinx extension which implements scalable image handling. > > + > > + :copyright: Copyright (C) 2016 Markus Heiser > > + :license: GPL Version 2, June 1991 see Linux/COPYING for details. > > + > > + The build for image formats depence on image's source format and output's > > + destination format. This extension implement methods to simplify image > > + handling from the author's POV. Directives like ``kernel-figure`` implement > > + methods *to* always get the best output-format even if some tools are not > > + installed.For more details take a look at ``convert_image(...)`` which is > > + the core of all conversions. > > + > > + * ``.. kernel-image``: for image handling / ``.. image::`` replacement > > + > > + * ``.. kernel-figure``: for figure handling / ``.. figure::`` replacement > > + > > + * ``.. kernel-render``: for render markup / a concept to embed *render* > > + markups (or languages). Supported markups (see ``RENDER_MARKUP_EXT``) > > + > > + + ``DOT``: render embedded Graphviz's **DOC** > > + + ``SVG``: render embedded Scalable Vector Graphics (**SVG**) > > + + ... *developable* > > + > > + Used tools: > > + > > + * ``dot(1)``: Graphviz (http://www.graphviz.org). If Graphviz is not > > + available, the DOT language is inserted as literal-block. > > + > > + * SVG to PDF: To generate PDF, you need at least one of this tools: > > + > > + - CairoSVG (http://cairosvg.org) if installed or alternatively > > + - ``convert(1)``: ImageMagick (https://www.imagemagick.org) > > + > > + List of customizations: > > + > > + * generate PDF from SVG / used by PDF (LaTeX) builder > > + > > + * generate SVG (html-builder) and PDF (latex-builder) from DOT files. > > + DOT: see http://www.graphviz.org/content/dot-language > > + > > + """ > > + > > +import os > > +from os import path > > +import subprocess > > +from hashlib import sha1 > > + > > +from docutils import nodes > > +from docutils.statemachine import ViewList > > +from docutils.parsers.rst import directives > > +from docutils.parsers.rst.directives import images > > + > > +from sphinx.directives import patches > > + > > +__version__ = '1.0' > > + > > +# simple helper > > +# ------------- > > + > > +def which(cmd): > > + """Searches the ``cmd`` in the ``PATH`` enviroment. > > + > > + This *which* searches the PATH for executable ``cmd`` . First match is > > + returned, if nothing is found, ``None` is returned. > > + """ > > + envpath = os.environ.get('PATH', None) or os.defpath > > + for folder in envpath.split(os.pathsep): > > + fname = folder + os.sep + cmd > > + if path.isfile(fname): > > + return fname > > + > > +def mkdir(folder, mode=0o775): > > + if not path.isdir(folder): > > + os.makedirs(folder, mode) > > + > > +def isNewer(path1, path2): > > + """Returns True if ``path1`` is newer than ``path2`` > > + > > + If ``path1`` exists and is newer than ``path2`` the function returns > > + ``True`` is returned otherwise ``False`` > > + """ > > + return (path.exists(path1) > > + and os.stat(path1).st_ctime > os.stat(path2).st_ctime) > > + > > +# def debug_handle(self, node): # pylint: disable=W0613 > > +# from linuxdoc.kernel_doc import CONSOLE > > +# CONSOLE() > > + > > +def pass_handle(self, node): # pylint: disable=W0613 > > + pass > > + > > +# setup conversion tools and sphinx extension > > +# ------------------------------------------- > > + > > +# Graphviz's dot(1) support > > +dot_cmd = which('dot') > > + > > +# ImageMagick' convert(1) support > > +convert_cmd = which('convert') > > + > > +# cairosvg support > > +try: > > + import cairosvg # pylint: disable=C0413 > > +except ImportError: > > + cairosvg = None > > + > > + > > +def setup(app): > > + # check toolchain first > > + app.connect('builder-inited', checkTools) > > + > > + # image handling > > + app.add_directive("kernel-image", KernelImage) > > + app.add_node(kernel_image, > > + html = (visit_kernel_image, pass_handle), > > + latex = (visit_kernel_image, pass_handle), > > + texinfo = (visit_kernel_image, pass_handle), > > + text = (visit_kernel_image, pass_handle), > > + man = (visit_kernel_image, pass_handle), ) > > + > > + # figure handling > > + app.add_directive("kernel-figure", KernelFigure) > > + app.add_node(kernel_figure, > > + html = (visit_kernel_figure, pass_handle), > > + latex = (visit_kernel_figure, pass_handle), > > + texinfo = (visit_kernel_figure, pass_handle), > > + text = (visit_kernel_figure, pass_handle), > > + man = (visit_kernel_figure, pass_handle), ) > > + > > + # render handling > > + app.add_directive('kernel-render', KernelRender) > > + app.add_node(kernel_render, > > + html = (visit_kernel_render, pass_handle), > > + latex = (visit_kernel_render, pass_handle), > > + texinfo = (visit_kernel_render, pass_handle), > > + text = (visit_kernel_render, pass_handle), > > + man = (visit_kernel_render, pass_handle), ) > > + > > + return dict( > > + version = __version__, > > + parallel_read_safe = True, > > + parallel_write_safe = True > > + ) > > + > > + > > +def checkTools(app): > > + u""" > > + Check available build tools and log some *verbose* messages. > > + > > + This function is called once, when the builder is initiated. > > + """ > > + app.verbose("kfigure: check installed tools ...") > > + if dot_cmd: > > + app.verbose("use dot(1) from: " + dot_cmd) > > + else: > > + app.warn("dot(1) not found, for better output quality install " > > + "graphviz from http://www.graphviz.org";) > > + if cairosvg: > > + app.verbose("use CairoSVG from: " + str(cairosvg)) > > + if convert_cmd: > > + app.verbose("use ImageMagick: " + convert_cmd) > > + if cairosvg is None and convert_cmd is None: > > + app.warn("no SVG to PDF conversion available, " > > + "install CairoSVG (http://cairosvg.org) or alternatively " > > + "``convert(1)`` from ImageMagick (https://www.imagemagick.org)") > > + > > + > > +# integrate conversion tools > > +# -------------------------- > > + > > +RENDER_MARKUP_EXT = { > > + # The '.ext' must be handled by convert_image(..) function's *in_ext* input. > > + # <name> : <.ext> > > + 'DOT' : '.dot' > > + , 'SVG' : '.svg' > > +} > > + > > +def convert_image(img_node, translator): # pylint: disable=R0912 > > + """Convert an image node for the builder. > > + > > + Different builder prefer different image formats, e.g. *latex* builder > > + prefer PDF while *html* builder prefer SVG format for images. > > + > > + This function handles outputs image formats in depence of source the format > > + of the image and the translator's output format. This also means to > > + manipulate/update the *image* dictionary of the builder (``builder.images``) > > + > > + """ > > + fname, in_ext = path.splitext(path.basename(img_node['uri'])) > > + src_fname = path.join(translator.builder.srcdir, img_node['uri']) > > + src_folder = path.dirname(img_node['uri']) > > + out_dir = translator.builder.outdir > > + dst_fname = None > > + > > + # in kernel builds, use 'make SPHINXOPTS=-v' to see verbose messages > > + verbose = translator.builder.app.verbose > > + warn = translator.builder.warn > > + > > + verbose('assert best format for: ' + img_node['uri']) > > + > > + if in_ext == '.dot': > > + > > + # ---------- > > + # handle DOT > > + # ---------- > > + > > + if not dot_cmd: > > + verbose("dot from graphviz not available / include DOT raw.") > > + with open(src_fname, "r") as dot: > > + data = dot.read() > > + node = nodes.literal_block(data, data) > > + img_node.replace_self(node) > > + > > + elif translator.builder.format == 'latex': > > + dst_fname = path.join(out_dir, fname + '.pdf') > > + > > + elif translator.builder.format == 'html': > > + dst_fname = path.join(out_dir, src_folder, fname + '.svg') > > + else: > > + # all other builder formats will include DOT as raw > > + with open(src_fname, "r") as dot: > > + data = dot.read() > > + node = nodes.literal_block(data, data) > > + img_node.replace_self(node) > > + > > + > > + elif in_ext == '.svg': > > + > > + # ---------- > > + # handle SVG > > + # ---------- > > + > > + if translator.builder.format == 'latex': > > + if cairosvg is None and convert_cmd is None: > > + warn("no SVG to PDF conversion available") > > + else: > > + dst_fname = path.join(out_dir, fname + '.pdf') > > + > > + if dst_fname: > > + name = dst_fname[len(out_dir) + 1:] > > + # the builder needs not to copy one more time, so pop it if exists. > > + translator.builder.images.pop(img_node['uri'], None) > > + img_node['uri'] = dst_fname > > + img_node['candidates'] = {'*': dst_fname} > > + > > + if isNewer(dst_fname, src_fname): > > + verbose("convert: %s allready exists and is newer" % name) > > + else: > > + mkdir(path.dirname(dst_fname)) > > + > > + if in_ext == '.dot': > > + verbose('convert DOT to: {out}/' + name) > > + dot2format(src_fname, dst_fname) > > + > > + elif in_ext == '.svg': > > + verbose('convert SVG to: {out}/' + name) > > + svg2pdf(src_fname, dst_fname) > > + > > +def dot2format(dot_fname, out_fname): > > + """Converts DOT file to ``out_fname`` using ``dot(1)``. > > + > > + * ``dot_fname`` pathname of the input DOT file, including extension ``.dot`` > > + * ``out_fname`` pathname of the output file, including format extension > > + > > + The *format extension* depends on the ``dot`` command (see ``man dot`` > > + option ``-Txxx``). Normally you will use one of the following extensions: > > + > > + - ``.ps`` for PostScript, > > + - ``.svg`` or ``svgz`` for Structured Vector Graphics, > > + - ``.fig`` for XFIG graphics and > > + - ``.png`` or ``gif`` for common bitmap graphics. > > + > > + """ > > + out_format = path.splitext(out_fname)[1][1:] > > + cmd = [dot_cmd, '-T%s' % out_format, dot_fname] > > Hm, adding '-v' when we run in verbose sphinx mode might be useful for > more debugging here. > ' > > + exit_code = 42 > > + with open(out_fname, "w") as out: > > + exit_code = subprocess.call( > > + cmd, stdout = out, stderr = subprocess.PIPE ) > > + out.flush() > > This eats stderr, which is a bit unhelpful when debugging dot (or in the > case below, svg) formatting issues. I've hacked something up, but would be > good someone versed in python fixes it ;-) > > Cheers, Daniel > > > + return bool(exit_code == 0) > > + > > +def svg2pdf(svg_fname, pdf_fname): > > + """Converts SVG to PDF with CairoSVG or ``convert(1)`` command. > > + > > + Uses CairoSVG (http://cairosvg.org) if installed or alternatively > > + ``convert(1)`` from ImageMagick (https://www.imagemagick.org) for > > + conversion. Returns ``True`` on success and ``False`` if an error occurred > > + (e.g. none of the conversion tool is available). > > + > > + * ``svg_fname`` pathname of the input SVG file with extension (``.svg``) > > + * ``pdf_name`` pathname of the output PDF file with extension (``.pdf``) > > + > > + """ > > + if cairosvg: > > + # pylint: disable=E1101 > > + cairosvg.svg2pdf(url = svg_fname, write_to = pdf_fname) > > + return True > > + if convert_cmd: > > + cmd = [convert_cmd, svg_fname, pdf_fname] > > + exit_code = subprocess.call( > > + cmd, stdout = subprocess.PIPE, stderr = subprocess.PIPE ) > > + return bool(exit_code == 0) > > + return False > > + > > + > > +# image handling > > +# --------------------- > > + > > +def visit_kernel_image(self, node): # pylint: disable=W0613 > > + """Visitor of the ``kernel_image`` Node. > > + > > + Handles the ``image`` child-node with the ``convert_image(...)``. > > + """ > > + img_node = node[0] > > + convert_image(img_node, self) > > + > > +class kernel_image(nodes.General, nodes.Element): > > + """Node for ``kernel-image`` directive.""" > > + pass > > + > > +class KernelImage(images.Image): > > + u"""KernelImage directive > > + > > + Earns everything from ``.. image::`` directive, except *remote URI* and > > + *glob* pattern. The KernelImage wraps a image node into a > > + kernel_image node. See ``visit_kernel_image``. > > + """ > > + > > + def run(self): > > + uri = self.arguments[0] > > + if uri.endswith('.*') or uri.find('://') != -1: > > + raise self.severe( > > + 'Error in "%s: %s": glob pattern and remote images are not allowed' > > + % (self.name, uri)) > > + result = images.Image.run(self) > > + if len(result) == 2 or isinstance(result[0], nodes.system_message): > > + return result > > + (image_node,) = result > > + # wrap image node into a kernel_image node / see visitors > > + node = kernel_image('', image_node) > > + return [node] > > + > > +# figure handling > > +# --------------------- > > + > > +def visit_kernel_figure(self, node): # pylint: disable=W0613 > > + """Visitor of the ``kernel_figure`` Node. > > + > > + Handles the ``image`` child-node with the ``convert_image(...)``. > > + """ > > + img_node = node[0][0] > > + convert_image(img_node, self) > > + > > +class kernel_figure(nodes.General, nodes.Element): > > + """Node for ``kernel-figure`` directive.""" > > + > > +class KernelFigure(patches.Figure): > > + u"""KernelImage directive > > + > > + Earns everything from ``.. figure::`` directive, except *remote URI* and > > + *glob* pattern. The KernelFigure wraps a figure node into a kernel_figure > > + node. See ``visit_kernel_figure``. > > + """ > > + > > + def run(self): > > + uri = self.arguments[0] > > + if uri.endswith('.*') or uri.find('://') != -1: > > + raise self.severe( > > + 'Error in "%s: %s":' > > + ' glob pattern and remote images are not allowed' > > + % (self.name, uri)) > > + result = patches.Figure.run(self) > > + if len(result) == 2 or isinstance(result[0], nodes.system_message): > > + return result > > + (figure_node,) = result > > + # wrap figure node into a kernel_figure node / see visitors > > + node = kernel_figure('', figure_node) > > + return [node] > > + > > + > > +# render handling > > +# --------------------- > > + > > +def visit_kernel_render(self, node): > > + """Visitor of the ``kernel_render`` Node. > > + > > + If rendering tools available, save the markup of the ``literal_block`` child > > + node into a file and replace the ``literal_block`` node with a new created > > + ``image`` node, pointing to the saved markup file. Afterwards, handle the > > + image child-node with the ``convert_image(...)``. > > + """ > > + > > + verbose = self.builder.app.verbose > > + warn = self.builder.warn > > + srclang = node.get('srclang') > > + > > + verbose('visit kernel-render node lang: "%s"' % (srclang)) > > + > > + tmp_ext = RENDER_MARKUP_EXT.get(srclang, None) > > + if tmp_ext is None: > > + warn('kernel-render: "%s" unknow / include raw.' % (srclang)) > > + return > > + > > + literal_block = node[0] > > + code = literal_block.astext() > > + > > + if not dot_cmd and tmp_ext == '.dot': > > + verbose("dot from graphviz not available / include raw.") > > + tmp_ext = None > > + > > + if tmp_ext: > > + hashobj = code.encode('utf-8') # str(node.attributes) > > + fname = '%s-%s' % (srclang, sha1(hashobj).hexdigest()) > > + tmp_fname = path.join( > > + self.builder.outdir, self.builder.imagedir, fname + tmp_ext) > > + > > + if not path.isfile(tmp_fname): > > + mkdir(path.dirname(tmp_fname)) > > + with open(tmp_fname, "w") as out: > > + out.write(code) > > + > > + image_node = nodes.image(node.rawsource, **node.attributes) > > + image_node['uri'] = tmp_fname > > + > > + literal_block.replace_self(image_node) > > + convert_image(image_node, self) > > + > > + > > +class kernel_render(nodes.General, nodes.Inline, nodes.Element): > > + """Node for ``kernel-render`` directive.""" > > + pass > > + > > +class KernelRender(patches.Figure): > > + u"""KernelRender directive > > + > > + Render content by external tool. Has all the options known from the > > + *figure* directive, plus option ``caption``. If ``caption`` has a > > + value, a figure node with the *caption* is inserted. If not, a image node is > > + inserted. > > + > > + The KernelRender directive wraps the text of the directive into a > > + literal_block node and wraps it into a kernel_render node. See > > + ``visit_kernel_render``. > > + """ > > + has_content = True > > + required_arguments = 1 > > + optional_arguments = 0 > > + final_argument_whitespace = False > > + > > + # earn options from 'figure' > > + option_spec = patches.Figure.option_spec.copy() > > + option_spec['caption'] = directives.unchanged > > + > > + def run(self): > > + return [self.build_node()] > > + > > + def build_node(self): > > + > > + srclang = self.arguments[0].strip() > > + if srclang not in RENDER_MARKUP_EXT.keys(): > > + return [self.state_machine.reporter.warning( > > + 'Unknow source language "%s", use one of: %s.' % ( > > + srclang, ",".join(RENDER_MARKUP_EXT.keys())), > > + line=self.lineno)] > > + > > + code = '\n'.join(self.content) > > + if not code.strip(): > > + return [self.state_machine.reporter.warning( > > + 'Ignoring "%s" directive without content.' % ( > > + self.name), > > + line=self.lineno)] > > + > > + node = kernel_render() > > + node['alt'] = self.options.get('alt','') > > + node['srclang'] = srclang > > + literal_node = nodes.literal_block(code, code) > > + node += literal_node > > + > > + caption = self.options.get('caption') > > + if caption: > > + # parse cation's content > > + parsed = nodes.Element() > > + self.state.nested_parse( > > + ViewList([caption], source=''), self.content_offset, parsed) > > + caption_node = nodes.caption( > > + parsed[0].rawsource, '', *parsed[0].children) > > + caption_node.source = parsed[0].source > > + caption_node.line = parsed[0].line > > + > > + figure_node = nodes.figure('', node) > > + for k,v in self.options.items(): > > + figure_node[k] = v > > + figure_node += caption_node > > + > > + node = figure_node > > + > > + return node > > + > > -- > > 2.7.4 > > > > -- > Daniel Vetter > Software Engineer, Intel Corporation > http://blog.ffwll.ch -- Daniel Vetter Software Engineer, Intel Corporation http://blog.ffwll.ch -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
