beanbag_docutils.sphinx.ext.retina_images

Sphinx extension for Retina images.

Deprecated since version 2.1: We recommend using beanbag_docutils.sphinx.ext.image_srcsets instead. This extension will be removed in a future release.

This extension goes through all the images Sphinx will provide in _images and checks if Retina versions are available. If there are any, they will be copied as well.

Setup

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

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

Configuration

retina_suffixes:

A list of suffix identifiers for Retina images. Each of these go after the filename and before the extension. This defaults to ['@2x', '@3x'].

Functions

add_high_dpi_images(app, env)

Add high-DPI images to the list of bundled images.

collect_pages(app)

Collect high-DPI images for use in HTML pages.

setup(app)

Set up the Sphinx extension.

beanbag_docutils.sphinx.ext.retina_images.add_high_dpi_images(app, env)

Add high-DPI images to the list of bundled images.

Any image that has a “@2x” version will be included in the output directory for the docs.

Parameters:
  • app (sphinx.application.Sphinx) – The Sphinx application to register roles and configuration on.

  • env (sphinx.environment.BuildEnvironment) – The build environment for the generated docs.

beanbag_docutils.sphinx.ext.retina_images.collect_pages(app)

Collect high-DPI images for use in HTML pages.

This will go through the images referenced in a document for an HTML page and add any high-DPI versions previously found in add_high_dpi_images() 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.retina_images.setup(app)

Set up the Sphinx extension.

This listens for the events needed to collect and bundle high-DPI images.

Parameters:

app (sphinx.application.Sphinx) – The Sphinx application to listen to events on.