k3d_screenshot

A directive for including the screenshot of a K3D Jupyter plot into a Sphinx document.

By default, in HTML output, k3d-screenshot will include a small.png file with a link to a large.png, an .html and .pdf. In LaTeX output, it will include a .pdf.

The source code for the k3d application may be included in one of three ways:

  1. A path to a source file as the argument to the directive:

    .. k3d-screenshot:: path/to/plot.py
    

    When a path to a source file is given, the content of the directive may optionally contain a caption for the plot:

    .. k3d-screenshot:: path/to/plot.py
    
       The plot caption.
    

    Additionally, one may specify the name of a function to call (with no arguments) immediately after importing the module:

    .. k3d-screenshot:: path/to/plot.py function_name
    
  2. Using doctest syntax:

    .. k3d-screenshot::
    
       A plotting example:
       >>> import k3d
       >>> p = k3d.plot()
       >>> p
    
  3. Using code block syntax:

    .. k3d-screenshot::
    
       import k3d
       p = k3d.plot()
       p
    

Options

The k3d-screenshot directive supports the following options:

format{‘python’, ‘doctest’}

The format of the input. If unset, the format is auto-detected.

include-sourcebool

Whether to display the source code. The default can be changed using the k3d_screenshot_include_source variable in conf.py (which itself defaults to True).

contextbool or str

If provided, the code will be run in the context of all previous plot directives for which the :context: option was specified. This only applies to inline code plot directives, not those run from files. If the :context: reset option is specified, the context is reset for this and future plots. :context: previous keeps the context.

nofigsbool

If specified, the code block will be run, but no figures will be inserted. This is usually useful with the :context: option.

captionstr

If specified, the option’s argument will be used as a caption for the figure. This overwrites the caption given in the content, when the plot is generated from a file.

small-sizewidth, height

Specify the width and height (pixels) of the small-screen screenshot.

large-sizewidth, height

Specify the width and height (pixels) of the large-screen screenshot.

cameraxcam, ycam, zcam, xtarget, ytarget, ztarget, xzvec, yzvec, zzvec

Specify the camera settings for the current plot. Let fig be the a K3D plot; execute fig.camera to retrieve the current camera settings.

Additionally, this directive supports all of the options of the image directive, except for target (since k3d-screenshot will add its own target). These include alt, height, width, scale, align and class.

Configuration options

The k3d-screenshot directive has the following configuration options:

k3d_screenshot_include_source

Default value for the include-source option (default: True).

k3d_screenshot_html_show_source_link

Whether to show a link to the source in HTML (default: True).

k3d_screenshot_pre_code

Code that should be executed before each plot. If None (the default), it will default to a string containing:

import numpy as np
import k3d
k3d_screenshot_basedir

Base directory, to which k3d-screenshot:: file names are relative to. If None or empty (the default), file names are relative to the directory where the file containing the directive is.

k3d_screenshot_formats

File formats to generate (default: ['small.png', 'large.png', 'html', 'pdf']). List of tuples or strings:

[(suffix, dpi), suffix, ...]

that determine the file format and the DPI. For entries whose DPI was omitted, sensible defaults are chosen. When passing from the command line through sphinx_build the list should be passed as suffix:dpi,suffix:dpi, …

'small.png' refers to a small-screen browser. It is also the image visualized on the page.

'large.png' refers to a large-screen browser. It is meant to visualize a screenshot of the application on a usual browser window.

k3d_screenshot_html_show_formats

Whether to show links to the files in HTML (default: True).

k3d_screenshot_working_directory

By default, the working directory will be changed to the directory of the example, so the code can get at its data files, if any. Also its path will be added to sys.path so it can import any helper modules sitting beside it. This configuration option can be used to specify a central directory (also added to sys.path) where data files and helper modules for all code are located.

k3d_screenshot_template

Provide a customized template for preparing restructured text.

k3d_intercept_codecallable

A function accepting one argument (the current code block being processed), returning a modified code. There might be occasions where the programmer needs to performs edits to the code block being executed, without the final user to be aware of them.

k3d_screenshot_small_size(width, height)

Specify the width and height of the small-screen screenshot.

k3d_screenshot_large_size(width, height)

Specify the width and height of the large-screen screenshot.

k3d_screenshot_browserstr or None

Specify which browser to use to create screenshots. Possible options are "chrome" or "firefox". If not provided, Chrome will be used.

k3d_screenshot_browser_pathstr or None

Specify the path to the browser executable. If not provided, selenium will attempt to execute the browser from the system path.

k3d_screenshot_driver_pathstr or None

Specify the path to the driver executable. If not provided, selenium will attempt to execute the driver from the system path.

k3d_screenshot_driver_optionslist/tuple

A list of strings to be added to the browser options with the add_argument method. Default to empty list.

k3d_screenshot_modify_drivercallable or None

A user-defined function, f(driver), to further customize the browser behavior before taking a new screenshot.

k3d_screenshot_camera_factorfloat

The screenshot engine is able to maintain the specified camera orientation, however the actual screenshot might look a little bit different than what would be seen in Jupyter. Specifically, it might look like the camera has been zoomed out of the scene. This parameter can be though as a zoom factor: the lower the value, the more zoomed in the screenshot will be. Default value 1.5.

k3d_screenshot_logging_pathstr, optional

Default to /home/selenium/sphinx_k3d_screenshot.log

k3d_screenshot_logging_level :

Default to logging.INFO.