# 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.