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:
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
Using doctest syntax:
.. k3d-screenshot:: A plotting example: >>> import k3d >>> p = k3d.plot() >>> p
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; executefig.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.