Using the pygfx gallery scraper

Pygfx implements its own scraper for Sphinx-gallery. Upstream projects that want to create a gallery using pygfx, can make use of it.

In conf.py

Setup sphinx-gallery as usual. See the Sphinx-gallery docs.

When creating the conf, do the following:

sphinx_gallery_conf = {
    ...
    "image_scrapers": ("pygfx",),
}

from pygfx.utils.gallery_scraper import find_examples_for_gallery

extra_conf = find_examples_for_gallery(your_examples_dir)
sphinx_gallery_conf.update(extra_conf)

That last line sets the “examples_dirs”, “ignore_pattern”, and “filename_pattern” of the config dict.

Writing examples

There are a few modes by which an example can appear in the gallery. For this purpose the # sphinx_gallery_pygfx_docs comment must be present in each example that you want to have in the docs.

• sphinx_gallery_pygfx_docs = 'hidden' - not present in the gallery.

• sphinx_gallery_pygfx_docs = 'code' - present only as code (don’t run the code when building docs).

• sphinx_gallery_pygfx_docs = 'screenshot' - present in the gallery with a screenshot.

• sphinx_gallery_pygfx_docs = 'animate 3s' - present in the gallery with an animation (length specified in seconds).

Finding the canvas

The pygfx scraper needs to find the canvas or renderer to take the screenshot from. It does this by looking for an object called disp, renderer or canvas.

If your library hides these details, we’re open to expanding the logic so it is able to detect the canvas in more use-cases.

As a workaround, you can always write something like canvas = your_object.xxx.yyy.canvas.

Alternative usage

You don’t have to use the find_examples_for_gallery() to collect examples. You can also set “ignore_pattern” and “filename_pattern” yourself. However, if the scaper does not see the comment, it won’t render a screenshot.

You can also create your own scraper and re-use some parts of the pygfx scraper. We tried to write `pygfx/utils/gallery_scraper.py such that the code is very much re-usable.