linuxdoc.kfigure module

scalable figure and image handling

Sphinx extension which implements scalable image handling. User documentation see Scalable figure and image handling

class linuxdoc.kfigure.KernelFigure(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)

Bases: Figure

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.

run()

class linuxdoc.kfigure.KernelImage(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)

Bases: Image

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.

run()

class linuxdoc.kfigure.KernelRender(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)

Bases: Figure

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.

build_node()

final_argument_whitespace = False

May the final argument contain whitespace?

has_content = True

May the directive have content?

option_spec = {'align': <function Figure.align>, 'alt': <function unchanged>, 'caption': <function unchanged>, 'class': <function class_option>, 'figclass': <function class_option>, 'figwidth': <function Figure.figwidth_value>, 'height': <function length_or_unitless>, 'loading': <function Image.loading>, 'name': <function unchanged>, 'scale': <function percentage>, 'target': <function unchanged_required>, 'width': <function length_or_percentage_or_unitless>}

Mapping of option names to validator functions.

optional_arguments = 0

Number of optional arguments after the required arguments.

required_arguments = 1

Number of required directive arguments.

run()

linuxdoc.kfigure.add_kernel_figure_to_std_domain(app, doctree)

Add kernel-figure anchors to ‘std’ domain.

The StandardDomain.process_doc(..) method does not know how to resolve the caption (label) of kernel-figure directive (it only knows about standard nodes, e.g. table, figure etc.). Without any additional handling this will result in a ‘undefined label’ for kernel-figures.

This handle adds labels of kernel-figure to the ‘std’ domain labels.

linuxdoc.kfigure.convert_image(img_node, translator, src_fname=None)

Convert a 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 output image formats in dependence of source the format (of the image) and the translator’s output format.

linuxdoc.kfigure.dot2format(app, 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.

linuxdoc.kfigure.file2literal(fname)

linuxdoc.kfigure.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

class linuxdoc.kfigure.kernel_figure(rawsource='', *children, **attributes)

Bases: figure

Node for kernel-figure directive.

class linuxdoc.kfigure.kernel_image(rawsource='', *children, **attributes)

Bases: image

Node for kernel-image directive.

class linuxdoc.kfigure.kernel_render(rawsource='', *children, **attributes)

Bases: General, Inline, Element

Node for kernel-render directive.

linuxdoc.kfigure.mkdir(folder, mode=509)

linuxdoc.kfigure.pass_handle(self, node)

linuxdoc.kfigure.setup(app)

linuxdoc.kfigure.setupTools(app)

Check available build tools and log some verbose messages.

This function is called once, when the builder is initiated.

linuxdoc.kfigure.svg2pdf(app, svg_fname, pdf_fname)

Converts SVG to PDF with convert(1) command.

Uses convert(1) from ImageMagick (https://www.imagemagick.org) for conversion. Returns True on success and False if an error occurred.

• svg_fname pathname of the input SVG file with extension (.svg)

• pdf_name pathname of the output PDF file with extension (.pdf)

linuxdoc.kfigure.visit_kernel_figure(self, node)

Visitor of the kernel_figure Node.

Handles the image child-node with the convert_image(...).

linuxdoc.kfigure.visit_kernel_image(self, node)

Visitor of the kernel_image Node.

Handles the image child-node with the convert_image(...).

linuxdoc.kfigure.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(...).

linuxdoc.kfigure.which(cmd)

Searches the cmd in the PATH environment.

This which searches the PATH for executable cmd . First match is returned, if nothing is found, None is returned.