# beanbag_docutils.sphinx.ext.image_srcsets

Sphinx extension for srcsets in images.

Added in version 2.1.

This extension adds a `sources` option to the standard image directives, enabling responsive image support via srcsets.

These are specified a bit differently from `<img srcset="...">` values. The descriptor goes first, and a comma between entries is optional (a blank line can be used instead). For example:

    .. image:: path/to/file.png
       :sources: 2x path/to/file@2x.png
                 3x path/to/file@3x.png
                 100w path/to/file@100w.png
                 200h path/to/file@200h.png

If `sources` is not explicitly provided, but files with those standard `@`-based suffixes exist alongside the referenced main image, they’ll automatically be used to define the srcsets of the image. The `1x` entry is also automatically inserted based on the main image.

If relying on the default of scanning for srcset images, this becomes a zero-configuration, drop-in solution for all Sphinx documentation codebases.

## Setup

To use this, you just need to add the extension in `conf.py`:

    extensions = [
        ...
        'beanbag_docutils.sphinx.ext.image_srcsets',
        ...
    ]

Functions

`collect_pages`(app) | Collect srcset-specified images for use in HTML pages.
`collect_srcsets`(app, doctree) | Collect all images referenced by image nodes or scanned in directories.
`setup`(app) | Set up the Sphinx extension.

beanbag_docutils.sphinx.ext.image_srcsets.collect_pages(app: Sphinx) → List

  Collect srcset-specified images for use in HTML pages.

  This will go through the images referenced in a document for an HTML page and add any images found in srcsets to the list of images to collect for the page.

  Parameters:

    app (`sphinx.application.Sphinx`) – The Sphinx application to register roles and configuration on.

  Returns:

    An empty list (indicating no additional HTML pages are collected).

  Return type:

    `list`

beanbag_docutils.sphinx.ext.image_srcsets.collect_srcsets(app: Sphinx, doctree: document) → None

  Collect all images referenced by image nodes or scanned in directories.

  This will collect any explicit values defined via our `sources` option for image directives. If `sources` is not specified, but there are files in the directory with `@2x`, `@3x`, `@100w` `@100h`, etc. descriptors, those will be collected instead and associated with the image.

  Parameters:

    - app (`sphinx.application.Sphinx`) – The Sphinx application being run.

    - doctree (`docutils.nodes.document`) – The document tree being processed.

beanbag_docutils.sphinx.ext.image_srcsets.setup(app: Sphinx) → Dict

  Set up the Sphinx extension.

  This listens for the events needed to collect and bundle images for srcsets, and update the resulting HTML to specify them.

  Parameters:

    app (`sphinx.application.Sphinx`) – The Sphinx application being run.