Reintroduce examples.directory rc parameter

The main reason is that in Debian we store sample_data in a directory outside
the Python modules location.  This way we're able to specify that directory in a
more appropriate way, also to allow examples to work during package building (in
particular for the documentation part).

The code introduced is a partial revert of 6c5e961 (with very tiny changes).

Author: sandrotosi

lib/matplotlib/__init__.py

@@ -823,6 +823,20 @@ def rc_params_from_file(fname, fail_on_error=False):
 # this is the instance used by the matplotlib classes
 rcParams = rc_params()
 
+if rcParams['examples.directory']:
+    # paths that are intended to be relative to matplotlib_fname()
+    # are allowed for the examples.directory parameter.
+    # However, we will need to fully qualify the path because
+    # Sphinx requires absolute paths.
+    if not os.path.isabs(rcParams['examples.directory']):
+        _basedir, _fname = os.path.split(matplotlib_fname())
+        # Sometimes matplotlib_fname() can return relative paths,
+        # Also, using realpath() guarentees that Sphinx will use
+        # the same path that matplotlib sees (in case of weird symlinks).
+        _basedir = os.path.realpath(_basedir)
+        _fullpath = os.path.join(_basedir, rcParams['examples.directory'])
+        rcParams['examples.directory'] = _fullpath
+
 rcParamsOrig = rcParams.copy()
 
 rcParamsDefault = RcParams([ (key, default) for key, (default, converter) in \

lib/matplotlib/cbook.py

@@ -21,6 +21,7 @@
 import warnings
 from weakref import ref, WeakKeyDictionary
 
+import matplotlib
 
 import numpy as np
 import numpy.ma as ma
@@ -570,9 +571,17 @@ def get_sample_data(fname, asfileobj=True):
     `mpl-data/sample_data` directory.  If *asfileobj* is `True`
     return a file object, otherwise just a file path.
 
+    Set the rc parameter examples.directory to the directory where we should
+    look, if sample_data files are stored in a location different than
+    default (which is 'mpl-data/sample_data` at the same level of 'matplotlib`
+    Python module files).
+
     If the filename ends in .gz, the file is implicitly ungzipped.
     """
-    root = os.path.join(os.path.dirname(__file__), "mpl-data", "sample_data")
+    if matplotlib.rcParams['examples.directory']:
+        root = matplotlib.rcParams['examples.directory']
+    else:
+        root = os.path.join(os.path.dirname(__file__), "mpl-data", "sample_data")
     path = os.path.join(root, fname)
 
     if asfileobj:

lib/matplotlib/rcsetup.py

@@ -616,6 +616,9 @@ def __call__(self, s):
     'keymap.xscale' : [['k', 'L'], validate_stringlist],
     'keymap.all_axes' : ['a', validate_stringlist],
 
+    # sample data
+    'examples.directory' : ['', str],
+
     # Animation settings
     'animation.writer' : ['ffmpeg', validate_movie_writer],
     'animation.codec' : ['mpeg4', str],

matplotlibrc.template

@@ -423,6 +423,9 @@ text.hinting_factor : 8 # Specifies the amount of softness for hinting in the
 #keymap.xscale : L, k                # toggle scaling of x-axes ('log'/'linear')
 #keymap.all_axes : a                 # enable all axes
 
+# Control location of examples data files
+#examples.directory : ''   # directory to look in for custom installation
+
 ###ANIMATION settings
 #animation.writer : ffmpeg         # MovieWriter 'backend' to use
 #animation.codec : mp4             # Codec to use for writing movie