# sphinx_gallery.scrapers

Scrapers for embedding images.

Collect images that have been produced by code blocks.

The only scraper we natively support is Matplotlib, others should live in modules that will support them (e.g., PyVista, Plotly). Scraped images are injected as rst `image-sg` directives into the `.rst` file generated for each example script.

## Functions

sphinx_gallery.scrapers.clean_modules(gallery_conf, fname, when)

  Remove, unload, or reset modules.

  After a script is executed it can load a variety of settings that one does not want to influence in other examples in the gallery.

  Parameters:

    - gallery_conf (dict) – The gallery configuration.

    - fname (str or None) – The example being run. Will be None when this is called entering a directory of examples to be built.

    - when (str) –

      Whether this module is run before or after examples.

      This parameter is only forwarded when the callables accept 3 parameters.

sphinx_gallery.scrapers.figure_rst(figure_list, sources_dir, fig_titles='', srcsetpaths=None)

  Generate reST for a list of image filenames.

  Depending on whether we have one or more figures, we use a single rst call to ‘image’ or a horizontal list.

  Parameters:

    - figure_list (list) – List of strings of the figures’ absolute paths.

    - sources_dir (str) – absolute path of Sphinx documentation sources

    - fig_titles (str) – Titles of figures, empty string if no titles found. Currently only supported for matplotlib figures, default = ‘’.

    - srcsetpaths (list or None) – List of dictionaries containing absolute paths. If empty, then srcset field is populated with the figure path. (see `image_srcset` configuration option). Otherwise, each dict is of the form {0: /images/image.png, 2.0: /images/image_2_00x.png} where the key is the multiplication factor and the contents the path to the image created above.

  Returns:

    - images_rst (str) – rst code to embed the images in the document

    - The rst code will have a custom `image-sg` directive that allows

    - multiple resolution images to be served e.g.

    - `` (srcset: /plot_types/imgs/img_001.png,) – /plot_types/imgs/img_2_00x.png 2.00x``

sphinx_gallery.scrapers.matplotlib_scraper(block, block_vars, gallery_conf, **kwargs)

  Scrape Matplotlib images.

  Parameters:

    - block (sphinx_gallery.py_source_parser.Block) – The code block to be executed. Format (label, content, lineno).

    - block_vars (dict) – Dict of block variables.

    - gallery_conf (dict) – Contains the configuration of Sphinx-Gallery

    - **kwargs (dict) –

      Additional keyword arguments to pass to `savefig()`, e.g. `format='svg'`. The `format` keyword argument in particular is used to set the file extension of the output file (currently only ‘png’, ‘jpg’, ‘svg’, ‘gif’, and ‘webp’ are supported).

      This is not used internally, but intended for use when overriding the scraper.

  Returns:

    rst – The reStructuredText that will be rendered to HTML containing the images. This is often produced by `figure_rst()`.

  Return type:

    str

sphinx_gallery.scrapers.save_figures(block, block_vars, gallery_conf)

  Save all open figures of the example code-block.

  Parameters:

    - block (sphinx_gallery.py_source_parser.Block) – The code block to be executed. Format (label, content, lineno).

    - block_vars (dict) – Dict of block variables.

    - gallery_conf (dict) – Contains the configuration of Sphinx-Gallery

  Returns:

    images_rst – rst code to embed the images in the document.

  Return type:

    str

## Classes

class sphinx_gallery.scrapers.ImagePathIterator(image_path)

  Iterate over image paths for a given example.

  Parameters:

    image_path (str) – The template image path.

  next()

    Return the next image path, with numbering starting at 1.