7.16. sphinx.ext.imagewrap¶

The Sphinx extension setupdocx.sphinx.ext.imagewrap handles required different sizes for multiple builders. This includes in particular epub, html, and pdf*(*pdflatex). This includes a simple syntax extension for multiple variants. The extension is inspired by the article “Using Sphinx to Write Technical Books” and the contained example “Autoimage” see [DrPedroKroger].

The imagewrap covers all possible parameters in order to simply wrap the image directive, without the introduction of extra features. The original directive

.. image:: gnu.png
   (options)

is extended by inheritance of the class Image to:

.. imagewrap:: gnu.png
   (options)

Where the parameters are processed and passed to the class Image. For example:

.. imagewrap:: _static/gnu.png
   width-html: 400px         # for HTML
   width-latexpdf: 250px     # for latexpdf == PDF
   width-epub: 150px         # for epub
   width-epub2: 150px        # for epub
   width-mobi: 150px         # for mobi
   width: 200px              # for all non-specified

   scale-html': directives.percentage,
   scale-latex': directives.percentage,
   scale-epub': directives.percentage,
   scale-epub2': directives.percentage,
   scale-mobi': directives.percentage,
   scale': directives.percentage,

   height-html': directives.length_or_unitless,
   height-latex': directives.length_or_unitless,
   height-epub': directives.length_or_unitless,
   height-epub2': directives.length_or_unitless,
   height-mobi': directives.length_or_unitless,
   height': directives.length_or_unitless,

7.16.1. Module¶

Wrapper extension for the directive image / Image and figure/Figure. In order to avoid copy-of-code or mix-in, the instance is processed by functions.

7.16.2. Functions¶

7.16.2.1. cb_align_values_image¶

setupdocx.sphinx.ext.imagewrap.cb_align_values_image(argument)[source]¶

Imported callback, see:

docutils.parsers.rst.directives
docutils.parsers.rst.directives.images.Image.align_values

7.16.2.2. align_paths_to_top¶

setupdocx.sphinx.ext.imagewrap.align_paths_to_top(path, base, rel, depth)[source]¶

Aligns the provided image/figure relative paths. Checks first the existence of the path, if not exists adds the upward relative path as offset and checks the existence again. In case of a match the image path is replace by the existent, else kept unchanged. Ignores absolute paths.

Parameters

path – Path to be aligned. Only non-absolute paths are processed.
base – Base for relative input. Either absolute or relative to current position.
rel – Relative paths as side-branch of the search.
depth – Maximum number of upward directory nodes to be searched.

Returns

Resolved path, either absolute or relative.

Raises:

7.16.2.3. setup¶

setupdocx.sphinx.ext.imagewrap.setup(app)[source]¶: Initialize the extension.

7.16.3. ImageExt¶

class setupdocx.sphinx.ext.imagewrap.ImageExt(*args, **kargs)[source]¶

Wraps the class Image. Passes builder specific values. For the image parameters refer to [restdir].

Note

When multiple builder are called, requires to run with the cache erase option.

sphinx-build -E ..,

The wrapper is designed to be implemented as a mixin only.

7.16.3.1. option_spec¶

The member option_spec defines the known parameters.

option_spec = {
    'scale-html': directives.percentage,
    'scale-latex': directives.percentage,
    'scale-epub': directives.percentage,
    'scale-epub2': directives.percentage,
    'scale-mobi': directives.percentage,
    'scale': directives.percentage,

    'height-html': directives.length_or_unitless,
    'height-latex': directives.length_or_unitless,
    'height-epub': directives.length_or_unitless,
    'height-epub2': directives.length_or_unitless,
    'height-mobi': directives.length_or_unitless,
    'height': directives.length_or_unitless,

    'width-html': directives.length_or_percentage_or_unitless,
    'width-latex': directives.length_or_percentage_or_unitless,
    'width-epub': directives.length_or_percentage_or_unitless,
    'width-epub2': directives.length_or_percentage_or_unitless,
    'width-mobi': directives.length_or_percentage_or_unitless,
    'width': directives.length_or_percentage_or_unitless,

    'align': None,

}  #: wrap all image parameters

7.16.3.2. align_paths_to_top¶

ImageExt.align_paths_to_top(res)[source]¶

Aligns the provided image/figure relative paths. Checks first the existence of the path, if not exists adds the upward relative path as offset and checks the existence again. In case of a match the image path is replace by the existent, else kept unchanged. Ignores items with absolute paths.

Aligns::

source-path

target-html target

REMARK: Had to reengineer a bit of redundant attributes - so eventually some additional fixes may be required in future.

Parameters: res – result from call of ‘images.Image.run()’.
Returns: None, updates ‘res’.
Raises: pass-through –

7.16.3.3. extract_own_options¶

ImageExt.extract_own_options()[source]¶

Process the parameters, and maps the values to the parent class Image. The values are provided by the member self.options.

scale-{html, singlehtml, latex, epub, epub2, mobi,}
height-{html, singlehtml, latex, epub, epub2, mobi,}
width-{html, singlehtml, latex, epub, epub2, mobi,}
align-{html, singlehtml, latex, epub, epub2, mobi,}
target-{html, singlehtml, latex, epub, epub2, mobi,}

Defaults values are:

scale
height
width
align
target

Fetches the known-and-present special options only from ‘self.options’. These are stored in ‘self.own_opts’, the original default values remain untouched.

7.16.3.4. set_own_options¶

ImageExt.set_own_options(res)[source]¶

Updates the options of the result with the own extention-options.

scale-{html, latex, epub, mobi,}   => scale
height-{html, latex, epub, mobi,}  => height
width-{html, latex, epub, mobi,}   => width
align-{html, latex, epub, mobi,}   => align
target-{html, latex, epub, mobi,}  => target

Parameters: res – result from call of ‘images.Image.run()’.
Returns: None, updates ‘res’.
Raises: pass-through –

7.16.3.5. run¶

ImageExt.run()[source]¶

Process the parameters by self.setoptions, and calls the run method of the parent class Image. Inherits the option_spec from docutils.parsers.rst.directives.images.Image. Adds the following parameters.

scale-{html, latex, epub, mobi,}
height-{html, latex, epub, mobi,}
width-{html, latex, epub, mobi,}
align-{html, latex, epub, mobi,}
target-{html, latex, epub, mobi,}

7.16.4. FigureExt¶

class setupdocx.sphinx.ext.imagewrap.FigureExt(*args, **kargs)[source]¶

Wraps the class Figure. Passes builder specific values. For the figure parameters refer to [restdir].

Note

When multiple builder are called, requires to run with the cache erase option.

sphinx-build -E ..,

The permitted values of some parameters are slightly different from the parent image classes [restdir]. This is taken into account.

For the complete parameter description refer to [restdir], here a copy of the different semantics of “width” and “figwidth”. This option [figwidth] does not scale the included image; use the “width” image option for that.

+---------------------------+
|        figure             |
|                           |
|<------ figwidth --------->|
|                           |
|  +---------------------+  |
|  |     image           |  |
|  |                     |  |
|  |<--- width --------->|  |
|  +---------------------+  |
|                           |
|The figure's caption should|
|wrap at this width.        |
+---------------------------+

The wrapper is designed to be implemented as a mixin only.

7.16.4.1. option_spec¶

The member option_spec defines the known parameters.

option_spec = {
    'scale-html': directives.percentage,
    'scale-latex': directives.percentage,
    'scale-epub': directives.percentage,
    'scale-epub2': directives.percentage,
    'scale-mobi': directives.percentage,
    'scale': directives.percentage,

    'height-html': directives.length_or_unitless,
    'height-latex': directives.length_or_unitless,
    'height-epub': directives.length_or_unitless,
    'height-epub2': directives.length_or_unitless,
    'height-mobi': directives.length_or_unitless,
    'height': directives.length_or_unitless,

    'width-html': directives.length_or_percentage_or_unitless,
    'width-latex': directives.length_or_percentage_or_unitless,
    'width-epub': directives.length_or_percentage_or_unitless,
    'width-epub2': directives.length_or_percentage_or_unitless,
    'width-mobi': directives.length_or_percentage_or_unitless,
    'width': directives.length_or_percentage_or_unitless,

    'align': None,

}  #: wrap all image parameters

7.16.4.2. align_figure¶

FigureExt.align_figure(argument)[source]¶

7.16.4.3. extract_own_options¶

FigureExt.extract_own_options()[source]¶

Process the parameters, and maps the values to the parent class Figure. The values are provided by the member self.options.

figwidth-{html, latex, epub, mobi,}
figclass-{html, latex, epub, mobi,}

Fetches the known-and-present special options only from ‘self.options’. These are stored in ‘self.own_opts’, the original default values remain untouched.

7.16.4.4. setoptions_figure¶

FigureExt.setoptions_figure(inst)[source]¶

Process the parameters, and maps the values to the parent class Figure. The values are provided by the member self.options.

figwidth-{html, latex, epub, mobi,}
figclass-{html, latex, epub, mobi,}

7.16.4.5. run¶

FigureExt.run()[source]¶

Process the parameters by self.setoptions, and calls the run method of the parent class Figure. Inherits the option_spec from docutils.parsers.rst.directives.images.Figure. Adds the following parameters.

figwidth-{html, latex, epub, mobi,}
figclass-{html, latex, epub, mobi,}

7.16.5. Exceptions¶

exception setupdocx.sphinx.ext.imagewrap.ImageWrapError[source]¶: Image wrapper failed.

exception setupdocx.sphinx.ext.imagewrap.FigureWrapError[source]¶: Figure wrapper failed.