Can you add a few sentences to whats_new.rst (you might need to add an 'Examples' section) and sort out if this auto-magically gets added to the gallery (and if not add it?)

@tacaswell I just looked through whats_new.rst and it appears to be highlights for the next release. It seems like the CHANGELOG would be a better place to report this example. I also don't think that this example really belongs in the gallery, since it isn't showing off any cool abilities. On the other hand, all the other examples are there, so I will see if it automagically gets added.

I agree, this isn't a whats_new.rst item. CHANGELOG makes more sense.

On Tue, Apr 22, 2014 at 9:14 AM, Benjamin Reedlunn <notifications@github.com

wrote:

@tacaswell https://github.com/tacaswell I just looked through
whats_new.rst and it appears to be highlights for the next release. It
seems like the CHANGELOG would be a better place to report this example.
I also don't think that this example really belongs in the gallery, since
it isn't showing off any cool abilities. On the other hand, all the other
examples are there, so I will see if it automagically gets added.

—
Reply to this email directly or view it on GitHubhttps://github.com//pull/2995#issuecomment-41037483
.

Hmmm. Well, I am glad tcaswell suggested I check if this example gets added to the gallery. When I build the documentation, the example does get added to the gallery, but only the pdf, and it doesn't look right. As you can see below, the image that is titled "saved as a pdf" now looks like the image titled "saved as a png".

The same goes for the examples documentation: only one image file, and it looks like the "saved as a png", even though it is titled "saved as a pdf". Meanwhile, in /matplotlib-root/examples/images_contours_and_fields the two files were recreated, the pdf and the png, and they both look right.

I am guessing that the documentation build process just takes the figure window at the end of the example script, and creates a png. This is not what I want. I want it to save the pdf file and then convert the pdf to a png afterward. Is there a way to do this?

@mdboom Can you take a look at this? I know very little about the sphinx plot directives.

The simple solution might be to just use two figure objects.

Using two figure objects will give me two images, but the "saved as pdf" will look exactly like the "saved as png", which defeats the entire point of the example.

It would be nice if the documentation build process would accommodate saving as vector graphics file before creating a png, but here is a work around. I can save the file as a svg, convert the svg to a png, load the png into a matplotlib figure window, and then the documentation build process should take care of the rest. The issue I see with this approach is I have to import cairo and import rsvg to convert the svg to a png. Is that ok? Can I assume that the build system has these python packages on it's PYTHONPATH?

I don't think we would want the documentation build process to have these two additional dependencies, but @mdboom could provide more insight.

Why not add the "saved as pdf" image as a static image rather than an
auto-generated one? The entire purpose of the image is for documentation
rather than demoing code, so I would be fine with that.

On Wed, Apr 23, 2014 at 10:48 PM, Eric Firing notifications@github.comwrote:

I don't think we would want the documentation build process to have these
two additional dependencies, but @mdboom https://github.com/mdboomcould provide more insight.

—
Reply to this email directly or view it on GitHubhttps://github.com//pull/2995#issuecomment-41237692
.

WeatherGod's suggestion seems like a reasonable solution. The issue I see with using a static image is 'Nearest_vs_none-pdf.png' will be out of date if anyone in the future changes one of the functions I used to create 'Nearest_vs_none-pdf.png'. If everyone is ok with that, then I can change the end of the example script to be:

#Label the figure
txt = fig1.text(0.452, 0.95, 'Saved as a PNG', fontsize = 18)

#If you were going to run this example on your local machine, you 
#would save the figure as a PNG, save the same figure as a PDF, and 
#then compare them.  The following code would suffice.
#plt.savefig('Nearest_vs_none-png.png', bbox_inches = 'tight')
#txt.set_text('Saved as a PDF')
#plt.savefig('Nearest_vs_none-pdf.pdf', bbox_inches = 'tight')

#Here, however, we need to display the PDF on a webpage, which means
#the PDF must be converted into an image.  For the purposes of this 
#example, the 'Nearest_vs_none-pdf.pdf' has been pre-converted into 
#'Nearest_vs_none-pdf.png' at 80 dpi. We simply need to load and
#display it.
pdf_im_path = cbook.get_sample_data('Nearest_vs_none-pdf.png')
pdf_im = plt.imread(pdf_im_path)
fig2 = plt.figure(figsize = [8.0, 7.5])
plt.figimage(pdf_im)

plt.show()

Changing any of the relevant functions here would be a major API break so I would not worry about that too much.

When building the documentation, is there some way to only rebuild whatever has changed? It takes 20-30 minutes each time on my old laptop.

Ok. I have updated the CHANGELOG and confirmed that the documentation builds correctly. The example html page looks good, and the images get added to the gallery.

My pull request is ready for review.

Merged.

Thanks for the contribution!