Add a Sphinx extension to copy over Retina images.

Review Request #5511 — Created Feb. 20, 2014 and submitted

Review Board

Sphinx only actually copies over images that are used in documents. This
means that while we can dump @2x copies of images into _static, they
won't be used.

This extension hooks into the environment generation and html page
collection events, looking for @2x equivalents for all images that are
in use. It then adds them to the list of images set to be copied into

Built the docs and saw the Retina images copied over, which successfully
loaded on the page.

Description From Last Updated

This could be os.path


Do we want to use six here?

  2. docs/releasenotes/_ext/ (Diff revision 1)

    This could be os.path

    1. import os.path
      >>> help(os.path)

      Instead of importing this module directly, import os and refer to
      this module as os.path.  The "os.path" name is an alias for this
      module on Posix systems; on other systems (e.g. Mac, Windows),
      os.path provides the same operations in a manner specific to that
      platform, and is an alias to another module (e.g. macpath, ntpath).
    2. Should we be changing all our imports of this?

    3. Probably. I don't think it's harmful to import it (wish they said why to import like this exactly), and we haven't hit issues from it, but going forward, we should probably avoid importing os.path directly.

  3. docs/releasenotes/_ext/ (Diff revision 1)

    Do we want to use six here?

    1. I did at first, but this module is useful and it's something I want to put out there. Nobody seems to have one for this.

      Sphinx itself doesn't use six, and requiring Django for this module seems silly. I'm not sure what Sphinx is doing (2to3 maybe?) but they're using iteritems() everywhere. For now, I want to stay consistent with that.

      The official docs are generated on a known environment of Python 2.6, so for the moment, I'm not concerned about not being Python 3-compatible here.

  1. Ship It!

Review request changed

Status: Closed (submitted)