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_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_srcsets(app, doctree)

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.collect_pages(app)

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.setup(app)

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.