panel_screenshot

A directive for including the screenshot of a panel app in a Sphinx document

By default, in HTML output, panel-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 panel application may be included in one of three ways:

A path to a source file as the argument to the directive:
```
.. panel-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:
```
.. panel-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:
```
.. panel-screenshot:: path/to/plot.py function_name
```

Using doctest syntax:

.. panel-screenshot::

   >>> import panel as pn
   >>> pn.widgets.FloatSlider(start=0, end=2, value=0.5, name="Float Slider")

Using code block syntax:

.. panel-screenshot::

   floatslider = pn.widgets.FloatSlider(start=0, end=2, value=0.5, name="Float Slider")
   floatslider

Options

The panel-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 panel_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.

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

Configuration options

The panel-screenshot directive has the following configuration options:

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

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

panel_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 param
import panel as pn
panel_screenshot_basedir
Base directory, to which panel-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.

panel_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.
panel_screenshot_html_show_formats
Whether to show links to the files in HTML (default: True).

panel_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.

panel_screenshot_template
Provide a customized template for preparing restructured text.

panel_screenshot_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.

panel_screenshot_postprocess_imagecallable
A function accepting three arguments, f(namespace, size, img), and returning a modified image. The arguments:

namespace: a dictionary containing the variables defined in the current code block being processed by sphinx_panel_screenshot, which has already been executed. It can be used to extract Python objects for further processing.

size: the size of the screenshot taken by executing the current code block.

img: the current screenshot of the panel object, of type PIL.Image.

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

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

panel_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.

panel_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.

panel_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.

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

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

panel_screenshot_pdf_fromstr
The PDF file will include the specified screenshot. Default to "large.png"

panel_screenshot_logging_pathstr, optional
Default to /home/selenium/sphinx_panel_screenshot.log

panel_screenshot_logging_level :
Default to logging.INFO.