Summary

Add a Sphinx extension to copy over Retina images.

Review Request #5511 — Created Feb. 20, 2014 and submitted Feb. 20, 2014, 2:13 p.m.

Information

Owner

chipx86

Repository

Review Board

Branch

release-2.0.x

Bugs

Depends On

Commit

ccb31ce...

Reviewers

Groups

reviewboard

People

Description

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

Testing Done

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

Issues

Description	From	Last Updated
This could be os.path	david	Feb. 20, 2014, 1:26 p.m.
Do we want to use six here?	david	Feb. 20, 2014, 1:32 p.m.

docs/releasenotes/_ext/retina_images.py (Diff revision 1)

The issue has been dropped. Show all issues

This could be os.path

chipx86 Feb. 20, 2014, 1:32 p.m.










import os.path

    >>> help(os.path)



DESCRIPTION
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).

david Feb. 20, 2014, 1:34 p.m.

Should we be changing all our imports of this?

chipx86 Feb. 20, 2014, 1:36 p.m.

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.

docs/releasenotes/_ext/retina_images.py (Diff revision 1)

The issue has been dropped. Show all issues

Do we want to use six here?

chipx86 Feb. 20, 2014, 1:32 p.m.

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.

Ship it!

```
Ship It!
```

Status:: Completed