In general I'd say that the procedure could be:

1. Try to reduce margins (subplots_adjust(..))
2. See if a shrinking the figure in width makes sense
3. As a final step reduce dpi until it fits.

What shouldn't happen though is that like in the case of the colormap reference the text becomes unreadable.

-1 on subplots_adjust, though that example already uses it. That example was actually what got me going on making text elements be part of constrained_layout and tight layout.

-2 on changing the dpi, just because we don't want a bunch of dpi adjustements in the examples.

I think 14-pt font in the example above is probably way overkill for what is being labelled. Most journals are OK with down to 8-pt, so I imagine 10 pt would be fine. I don't have the PR on this machine, but I had that example much smaller and it looked fine.

The bachelor degree example was added in version 1.5 where the default screen dpi was 80 indeed. So to keep it close to the original author's intend, one could simply set the dpi back to 80.

Telling users to change the dpi of a figure when they really want to change the size is wrong in my opinion. I appreciate that the (default) size of the figure in html is set by the number of pixels, but...

Actually, it would be nice if sphinx-gallery set the image width property in the html based on the value of figwidth.

I really don't know where that idea that scaling an image via the dpi is wrong would originate from. A reference for that would be helpful. One may argue that it is undesired for whatever objective reason in this case. (Although I personally wouldn't know of any.)

Sphinx-gallery has no control over the html. It creates rst files. It could however scale the image itself, or set the width via the rst :scale:. But it currently does this only in case you have several output figures. (Also quality is not really good if you let the browser scale the image.)

Note that it would be possible to add a css rule to shrink images in the browser:

div.body div.section img.align-center {
    max-width: 900px;
}

As said, the quality would not be great, but it may be the least invasive concerning actual example code.

This looks a lot like something we ran into with the pysurfer docs after switching over to sphinx-gallery: nipy/PySurfer#225

Ok so looks like this is in SG master?

Seems this merged in sphinx-gallery/sphinx-gallery#210, but not released yet.

The idea is essentially the same as the above css, just that they now have their own class for the images.

I really don't know where that idea that scaling an image via the dpi is wrong would originate from. A reference for that would be helpful. One may argue that it is undesired for whatever objective reason in this case. (Although I personally wouldn't know of any.)

We have two knobs on the output size in pixels (the size in inches and the dpi). It is better to tune the size in inches as it won't make the plots fuzzy.

It is better to tune the size in inches as it won't make the plots fuzzy.

As long as there is no way to scale the elements in the plot, i.e. have a "base size" and relative size units for all quantities used for setting a size, using the size in inches to scale a matplotlib figure is purely theoretical. In practice you would never go through all 200 elements of your plot and change their size to scale a plot. This is a design flaw of matplotlib, but it is like it is and one can work around it using dpi. So why advise people differently?

As a quick workaround and hard limit the CSS max-width is good.

Nevertheless, we should try to generate doc images in a size so that they don't get scaled. However, this would be a case by case effort. Approximately 38 images will be affected (regexp search figsize=\(\d{2}). Some images can be made smaller without messing them up severely. Others - like the one linked above would need additional adjustment of text sizes.

Size in inches, points, and other physical units is how most typography and graphics layout is done. Microsoft Word, Illustrator, etc all have the little ruler on the side in inches because you are usually working to make your graphics a certain size. For journal articles, the tradition has either been one column (about 3") or two-column (~6.5") in width, and something less than 8.5" or so in height.

You can always tell the first-time report writers in an undergraduate class by the ones who take the graphic they made in Matlab or Excel and then stretch/shrink it to the size that fits the page in Word; fonts become tiny and unreadable, line widths change, and in really egregious cases the aspect ratio changes. If they had laid it out at their intended size while composing the figure, they would have had a much better final-looking product.

In practice you would never go through all 200 elements of your plot and change their size to scale a plot. This is a design flaw of matplotlib,

I don't quite understand this statement. If I'm looking at a jpg, most jpg viewers have zoom tools, and I can make it any size I want. If it must be a fixed number of pixels wide, I'd just resample a high-res jpeg with something that does good anti-aliasing on the fully composed image (unlike the native piecemeal native anti-aliasing) like many GUI-based image manipulation tools, or imagemagick.

In this case, a small shrink is probably fine; I do that all the time when I'm preparing for publication, but I do it in the word-processing package, not matplotlib. I just don't think user-facing documentation should have calls to twiddle the dpi.

The question is: Is this worth fixing before sphinx v0.1.14 is released?
Pro: We don't know when that will eventually happen. (in a recent comment 5 days ago it says "We are still not ready with a release [...]".)
Contra: Unecessary work in the long term, and it would obscure those images where some tweaking is needed.

I think its worth fixing in general. The example above is comically large, for no good reason that I can discern. 14-pt fonts for labelling on a figure that can be 9" wide is pretty extreme, and shrinking down to 11-pt makes everything fit on a 9" figure w/o a problem. To me 9" is still comically large, but at least it will fit.

https://gist.github.com/jklymak/49f9e53ac6dc7cd7812af59b70a5e38a

Not sure if all the cases have been fixed by now, or if the gallery got smarter, but I don't observe the behavior anymore.

It's both. Some examples got fixed and mostly it's the new Sphinx gallery version being used by default, which uses a max-width in the CSS. Of course those would appear a bit blurry. So in case someone stumbles upon one of those, it would still make sense to restrict the size to 900pixels.