beanbag_docutils.sphinx.ext.image_srcsets

Sphinx extension for srcsets in images.

New 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_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_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) None

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.