partly implement the deprecation mechanism

183amir · 183amir · commit 2b81c1256c1c · 2019-03-03T16:12:17.000+01:00
diff --git a/doc/api/next_api_changes/2018-10-09-plot-directive.rst b/doc/api/next_api_changes/2018-10-09-plot-directive.rst
@@ -10,10 +10,18 @@ Documents that were using this feature may need to adjust the path argument
 given to the plot directive. Two options are available:
 
 1. Use absolute paths to find the file relative the ``plot_basedir`` (which
-   defaults to the directory where conf.py is).
+   defaults to the source directory, where conf.py is).
 2. Use relative paths and the file is found relative to the directory of the
    file containing the directive.
 
-Before this change, relative paths were resolved relative to the source
-directory (where conf.py is) and absolute paths were pointing to files in the
-host system.
+Before this change, relative paths were resolved relative to ``plot_basedir``
+(which defaulted to the source directory) and absolute paths were pointing to
+files in the host system.
+
+Since this will break documentations that were depending on the old behavior,
+there is a deprecation period and a new configuration option is introduced to
+get the old behavior. To get the old behavior specify
+``plot_dir_resolve_method='absolute'`` in ``conf.py`` and specify
+``plot_dir_resolve_method='relative'`` to get the new behavior. The old
+behavior might be removed in future. The users are advised to switch to the new
+behavior and fix the plot directives accordingly.
diff --git a/lib/matplotlib/sphinxext/plot_directive.py b/lib/matplotlib/sphinxext/plot_directive.py
@@ -100,11 +100,26 @@
             import numpy as np
             from matplotlib import pyplot as plt
 
+    plot_dir_resolve_method
+        The method to use for resolving file names that come after the
+        ``plot::`` directive. Two options are available: ``relative`` and
+        ``absolute``. Defaults to ``absolute`` but the default value will
+        change to ``relative`` in future versions. The ``absolute`` method
+        is deprecated and might be removed in future. See the ``plot_basedir``
+        for explanation of methods.
+
     plot_basedir
-        Base directory, to which ``plot::`` file names are relative
-        to. Defaults to the source directory. Only absolute paths are treated
-        relative to this option. Relative paths are found relative to the
-        directory of the file containing the directive.
+        Base directory, to which ``plot::`` file names are relative.
+        Defaults to the source directory.
+
+        If ``plot_dir_resolve_method`` is ``relative``, relative file names are
+        found relative to the directory of the file containing the directive.
+        Absolute file names (paths starting with ``/``) are found relative to
+        ``plot_basedir``.
+
+        If ``plot_dir_resolve_method`` is ``absolute``, all files are found
+        relative to ``plot_basedir`` whether the paths start with ``/`` or not.
+        This method is deprecated and may be removed in future.
 
     plot_formats
         File formats to generate. List of tuples or strings::
@@ -671,13 +686,36 @@ def run(arguments, content, options, state_machine, state, lineno):
 
     if len(arguments):
 
-        if arguments[0].startswith('/'):
-            arguments[0] = arguments[0][1:]
-            src_dir = config.plot_basedir or setup.app.builder.srcdir
+        # if the new method is selected for resolving paths
+        if config.plot_dir_resolve_method.lower() == 'relative':
+
+            if arguments[0].startswith('/'):
+                arguments[0] = arguments[0][1:]
+                src_dir = config.plot_basedir or setup.app.builder.srcdir
+            else:
+                src_dir = rst_dir
+
+            source_file_name = os.path.join(src_dir, directives.uri(arguments[0]))
+
         else:
-            src_dir = rst_dir
 
-        source_file_name = os.path.join(src_dir, directives.uri(arguments[0]))
+            cbook.warn_deprecated(
+                '3.2', message='You are using an old method '
+                'to resolve filenames of the ``.. ::plot`` directive. Please '
+                'switch to the new method by specifying '
+                '``plot_dir_resolve_method=\'relative\'`` in your conf.py '
+                'and fix the filenames accordingly. Please see '
+                'matplotlib/doc/api/next_api_changes/2018-10-09-plot-directive.rst '
+                'for more information. The old method will be removed in '
+                '%(removal)s.', removal='4.0')
+
+            if not config.plot_basedir:
+                source_file_name = os.path.join(
+                    setup.app.builder.srcdir, directives.uri(arguments[0]))
+
+            else:
+                source_file_name = os.path.join(
+                    setup.confdir, config.plot_basedir, directives.uri(arguments[0]))
 
         # If there is content, it will be passed as a caption.
         caption = '\n'.join(content)
