Add a Sphinx extension for working with srcsets for images.

Review Request #12737 — Created Nov. 23, 2022 and submitted

Information

beanbag-docutils
master

Reviewers

Sphinx and docutils lack any ability to work with modern <img srcset>
attributes, making it difficult to work with responsive/high-DPI images.
We've historically provided a retina_images extension that made use
of a legacy JavaScript library for swapping images at runtime based on
data attributes, but we don't even ship this anymore on our sites.

This change introduces a new extension that gives us a nice way of using
modern srcsets.

It extends the existing image directive to take an optional
sources option. If provided, this will determine the images that
will be collected in the resulting documentation and provided as a
srcset=. This looks like:

.. image:: path/to/file.png
   :sources: 2x path/to/file@2x.png
             3x path/to/file@3x.png
             ...

The structure is a bit different from the native value for
<img srcset>. Descriptors (e.g., 2x) go first, commas aren't
required if splitting across multiple lines, and 1x is inferred from
the main image.

This is actually entirely optional. If any suitable files exist
alongside the main referenced file, they'll be found and used to build
up the srcset. So the above file@2x.png and file@3x.png don't
even need to be specified. They'll be directly scanned and added.

This makes this extension a drop-in option for codebases without needing
to rely on the custom option.

The reason we're modifying image to begin with, rather than adding a
new directive, is in part to faciliate a drop-in solution that can still
render images without the use of the extension (such as when viewed on
GitHub), but also because the image machinery in both docutils and
Sphinx is baked in and complicated. It's far more error-prone to
introduce something new that replicates all that logic than to
monkeypatch with an optional option that doesn't even need to be
specified for the common case.

This extension does not depend on anything else within this package, and
requires no configuration, so it can be used directly in any Sphinx
documentation packages.

Unit tests pass.

Manually tested with our Review Board documentation, both with manual
sources and source scanning, and saw that the resulting docs looked correct
on standard and high DPIs, with srcset propery filled in.

Summary ID
Add a Sphinx extension for working with srcsets for images.
Sphinx and docutils lack any ability to work with modern `<img srcset>` attributes, making it difficult to work with responsive/high-DPI images. We've historically provided a ``retina_images`` extension that made use of a legacy JavaScript library for swapping images at runtime based on data attributes, but we don't even ship this anymore on our sites. This change introduces a new extension that gives us a nice way of using modern srcsets. It extends the existing ``image`` directive to take an optional ``sources`` option. If provided, this will determine the images that will be collected in the resulting documentation and provided as a ``srcset=``. This looks like: ```restructuredtext .. image:: path/to/file.png :sources: 2x path/to/file@2x.png 3x path/to/file@3x.png ... ``` The structure is a bit different from the native value for ``<img srcset>``. Descriptors (e.g., ``2x``) go first, commas aren't required if splitting across multiple lines, and ``1x`` is inferred from the main image. This is actually entirely optional. If any suitable files exist alongside the main referenced file, they'll be found and used to build up the srcset. So the above ``file@2x.png`` and ``file@3x.png`` don't even need to be specified. They'll be directly scanned and added. This makes this extension a drop-in option for codebases without needing to rely on the custom option. The reason we're modifying ``image`` to begin with, rather than adding a new directive, is in part to faciliate a drop-in solution that can still render images without the use of the extension (such as when viewed on GitHub), but also because the image machinery in both docutils and Sphinx is baked in and complicated. It's far more error-prone to introduce something new that replicates all that logic than to monkeypatch with an optional option that doesn't even need to be specified for the common case. This extension does not depend on anything else within this package, and requires no configuration, so it can be used directly in any Sphinx documentation packages.
6db2956567a8620f8b60ff9c6e60f859186a4c63
Description From Last Updated

'sphinx.environment.collectors.EnvironmentCollector' imported but unused Column: 1 Error code: F401

reviewbotreviewbot

local variable 'builder_name' is assigned to but never used Column: 5 Error code: F841

reviewbotreviewbot

continuation line unaligned for hanging indent Column: 32 Error code: E131

reviewbotreviewbot

'six' imported but unused Column: 1 Error code: F401

reviewbotreviewbot

too many blank lines (2) Column: 9 Error code: E303

reviewbotreviewbot

Mind fixing the U+2019 apostrophe in here while you're at it?

daviddavid
Checks run (1 failed, 1 succeeded)
flake8 failed.
JSHint passed.

flake8

chipx86
david
  1. 
      
  2. docs/index.rst (Diff revision 2)
     
     
    Show all issues

    Mind fixing the U+2019 apostrophe in here while you're at it?

  3. 
      
chipx86
david
  1. Ship It!
  2. 
      
chipx86
Review request changed
Status:
Completed
Change Summary:
Pushed to master (d866347)