Example of sphinx image copy

README.rst

This is an example of sphinx image copying problems, which are affecting scikit-learn and perhaps other projects.

This uses an extension to generate and save a matplotlib image. The first time make is typed, everything is fine. Each subsequent time make is typed, a new copy of the image is made in _build/html/_images. In projects like scikit-learn where hundereds of images are generated, this leads to very large builds.

Typing make clean and starting over fixes things, but this is a hack that shouldn't be required, especially on projects where rebuilding the doc from scratch takes a significant amount of time.

Example:

$: make
$: ls _build/html/_images
myplot.png
$: make
$: ls _build/html/_images
myplot1.png myplot.png

conf.py

import sys
import os

# path to extension
sys.path.insert(0, os.path.abspath('.'))

extensions = ['test_ext']

source_suffix = '.rst'

exclude_trees = ['_build']

master_doc = 'index'

index.rst

My Test

.. toctree::
   :maxdepth: 2

   images/index

Makefile

SPHINXBUILD   = sphinx-build
BUILDDIR      = _build
SPHINXOPTS   = -d $(BUILDDIR)/doctrees .

all: html

html:
	$(SPHINXBUILD) -b html $(SPHINXOPTS) $(BUILDDIR)/html
	@echo
	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."

clean:
	rm -rf $(BUILDDIR)
	rm -rf images
	rm -f *~
	rm -f *.pyc

test_ext.py

import os
from os.path import join

import numpy as np
import matplotlib
matplotlib.use('Agg')
import pylab as pl

def generate_plot_rst(app):
    # find the correct directories
    root_dir = app.builder.srcdir
    image_dir = os.path.join(root_dir, 'images')
    image_file = "myplot.png"
    image_fullpath = join(image_dir, image_file)

    # create image directory if it doesn't exist
    if not os.path.exists(image_dir):
        os.makedirs(image_dir)

    # create image png file if it doesn't exist
    if not os.path.exists(image_fullpath):
        x = np.linspace(0, 10, 1000)
        y = np.sin(x)
        pl.plot(x, y)
        pl.savefig(image_fullpath)

    # write the index file which embeds the image
    fhandle = open(join(image_dir, 'index.rst'), 'w')
    fhandle.write("================\n"
                  "Generated figure\n"
                  "================\n\n"
                  ".. image:: %(image_file)s\n"
                  "    :align: center\n\n" % locals())

def setup(app):
    app.connect('builder-inited', generate_plot_rst)
    app.add_config_value('extension_test', True, 'html')