From 78f423a8670d8d6a37ca718f15d467cab0a7ebfc Mon Sep 17 00:00:00 2001 From: Amir Mohammadi <183.amir@gmail.com> Date: Tue, 9 Oct 2018 10:48:11 +0200 Subject: [PATCH 1/8] sphinx plot directive: sources relative to rst file According to the documentation when plot_basedir is empty or None. The source-code files are found relative to the document that contains them. However, this was not true in the actual implementation. Fixes #10350 --- lib/matplotlib/sphinxext/plot_directive.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/lib/matplotlib/sphinxext/plot_directive.py b/lib/matplotlib/sphinxext/plot_directive.py index 1ab5aa5e17dd..fc6e48505220 100644 --- a/lib/matplotlib/sphinxext/plot_directive.py +++ b/lib/matplotlib/sphinxext/plot_directive.py @@ -666,7 +666,7 @@ def run(arguments, content, options, state_machine, state, lineno): if len(arguments): if not config.plot_basedir: - source_file_name = os.path.join(setup.app.builder.srcdir, + source_file_name = os.path.join(rst_dir, directives.uri(arguments[0])) else: source_file_name = os.path.join(setup.confdir, config.plot_basedir, From fa66c4905de27ac46929e62d976a3e914c477ce4 Mon Sep 17 00:00:00 2001 From: Amir MOHAMMADI Date: Tue, 9 Oct 2018 12:41:19 +0200 Subject: [PATCH 2/8] sphinx plot directive: account for absolute paths Absolute paths are found relative plot_basedir which defaults to the source directory. Relative paths are found relative to the document containing them. --- lib/matplotlib/sphinxext/plot_directive.py | 21 ++++++++++++++------- 1 file changed, 14 insertions(+), 7 deletions(-) diff --git a/lib/matplotlib/sphinxext/plot_directive.py b/lib/matplotlib/sphinxext/plot_directive.py index fc6e48505220..95047b5139c8 100644 --- a/lib/matplotlib/sphinxext/plot_directive.py +++ b/lib/matplotlib/sphinxext/plot_directive.py @@ -23,6 +23,10 @@ .. plot:: path/to/plot.py plot_function1 + Relative paths are found relative to the directory of the file containing + the directive. Absolute paths (paths starting with ``/``) are found + relative to ``plot_basedir`` (see Configuration options). + 2. Included as **inline content** to the directive:: .. plot:: @@ -98,8 +102,9 @@ plot_basedir Base directory, to which ``plot::`` file names are relative - to. (If None or empty, file names are relative to the - directory where the file containing the directive is.) + 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. plot_formats File formats to generate. List of tuples or strings:: @@ -665,12 +670,14 @@ def run(arguments, content, options, state_machine, state, lineno): rst_dir = os.path.dirname(rst_file) if len(arguments): - if not config.plot_basedir: - source_file_name = os.path.join(rst_dir, - directives.uri(arguments[0])) + + if arguments[0].startswith('/'): + arguments[0] = arguments[0][1:] + src_dir = config.plot_basedir or setup.app.builder.srcdir else: - source_file_name = os.path.join(setup.confdir, config.plot_basedir, - directives.uri(arguments[0])) + src_dir = rst_dir + + source_file_name = os.path.join(src_dir, directives.uri(arguments[0])) # If there is content, it will be passed as a caption. caption = '\n'.join(content) From b6437ad54fed0c2510437acac02a74d2812726a5 Mon Sep 17 00:00:00 2001 From: Amir MOHAMMADI Date: Tue, 9 Oct 2018 14:08:19 +0200 Subject: [PATCH 3/8] Fix the docs because of changes in the sphinx plot directive --- doc/devel/documenting_mpl.rst | 4 ++-- lib/matplotlib/axes/_axes.py | 6 +++--- lib/matplotlib/collections.py | 2 +- lib/matplotlib/path.py | 2 +- lib/matplotlib/sankey.py | 2 +- lib/mpl_toolkits/mplot3d/axes3d.py | 12 ++++++------ 6 files changed, 14 insertions(+), 14 deletions(-) diff --git a/doc/devel/documenting_mpl.rst b/doc/devel/documenting_mpl.rst index 473e5aa2f7e5..8623f5f9743f 100644 --- a/doc/devel/documenting_mpl.rst +++ b/doc/devel/documenting_mpl.rst @@ -300,7 +300,7 @@ so plots from the examples directory can be included using .. code-block:: rst - .. plot:: gallery/lines_bars_and_markers/simple_plot.py + .. plot:: /gallery/lines_bars_and_markers/simple_plot.py Note that the python script that generates the plot is referred to, rather than any plot that is created. Sphinx-gallery will provide the correct reference @@ -669,7 +669,7 @@ the file :file:`examples/text_labels_and_annotations/legend.py`: Examples -------- - .. plot:: gallery/text_labels_and_annotations/legend.py + .. plot:: /gallery/text_labels_and_annotations/legend.py """ Note that ``examples/text_labels_and_annotations/legend.py`` has been mapped to diff --git a/lib/matplotlib/axes/_axes.py b/lib/matplotlib/axes/_axes.py index affc329f1be0..8b08e6d620ee 100644 --- a/lib/matplotlib/axes/_axes.py +++ b/lib/matplotlib/axes/_axes.py @@ -370,7 +370,7 @@ def legend(self, *args, **kwargs): Examples -------- - .. plot:: gallery/text_labels_and_annotations/legend.py + .. plot:: /gallery/text_labels_and_annotations/legend.py """ handles, labels, extra_args, kwargs = mlegend._parse_legend_args( @@ -1272,7 +1272,7 @@ def eventplot(self, positions, orientation='horizontal', lineoffsets=1, Examples -------- - .. plot:: gallery/lines_bars_and_markers/eventplot_demo.py + .. plot:: /gallery/lines_bars_and_markers/eventplot_demo.py """ self._process_unit_info(xdata=positions, ydata=[lineoffsets, linelengths], @@ -3879,7 +3879,7 @@ def bxp(self, bxpstats, positions=None, widths=None, vert=True, Examples -------- - .. plot:: gallery/statistics/bxp.py + .. plot:: /gallery/statistics/bxp.py """ # lists of artists to be output diff --git a/lib/matplotlib/collections.py b/lib/matplotlib/collections.py index 53df43a41a45..25325b523877 100644 --- a/lib/matplotlib/collections.py +++ b/lib/matplotlib/collections.py @@ -1468,7 +1468,7 @@ def __init__(self, Examples -------- - .. plot:: gallery/lines_bars_and_markers/eventcollection_demo.py + .. plot:: /gallery/lines_bars_and_markers/eventcollection_demo.py """ segment = (lineoffset + linelength / 2., diff --git a/lib/matplotlib/path.py b/lib/matplotlib/path.py index 16b88da093ee..c422cb8f0aaa 100644 --- a/lib/matplotlib/path.py +++ b/lib/matplotlib/path.py @@ -299,7 +299,7 @@ def make_compound_path_from_polys(cls, XY): numsides x 2) numpy array of vertices. Return object is a :class:`Path` - .. plot:: gallery/misc/histogram_path.py + .. plot:: /gallery/misc/histogram_path.py """ diff --git a/lib/matplotlib/sankey.py b/lib/matplotlib/sankey.py index c93f07037ac0..b29d44e6e0df 100644 --- a/lib/matplotlib/sankey.py +++ b/lib/matplotlib/sankey.py @@ -117,7 +117,7 @@ def __init__(self, ax=None, scale=1.0, unit='', format='%G', gap=0.25, **Examples:** - .. plot:: gallery/specialty_plots/sankey_basics.py + .. plot:: /gallery/specialty_plots/sankey_basics.py """ # Check the arguments. if gap < 0: diff --git a/lib/mpl_toolkits/mplot3d/axes3d.py b/lib/mpl_toolkits/mplot3d/axes3d.py index ccf658bbc72d..429b7a4c8b16 100644 --- a/lib/mpl_toolkits/mplot3d/axes3d.py +++ b/lib/mpl_toolkits/mplot3d/axes3d.py @@ -1959,8 +1959,8 @@ def plot_trisurf(self, *args, color=None, norm=None, vmin=None, vmax=None, Examples -------- - .. plot:: gallery/mplot3d/trisurf3d.py - .. plot:: gallery/mplot3d/trisurf3d_2.py + .. plot:: /gallery/mplot3d/trisurf3d.py + .. plot:: /gallery/mplot3d/trisurf3d_2.py .. versionadded:: 1.2.0 This plotting function was added for the v1.2.0 release. @@ -2802,10 +2802,10 @@ def voxels(self, *args, facecolors=None, edgecolors=None, shade=True, Examples -------- - .. plot:: gallery/mplot3d/voxels.py - .. plot:: gallery/mplot3d/voxels_rgb.py - .. plot:: gallery/mplot3d/voxels_torus.py - .. plot:: gallery/mplot3d/voxels_numpy_logo.py + .. plot:: /gallery/mplot3d/voxels.py + .. plot:: /gallery/mplot3d/voxels_rgb.py + .. plot:: /gallery/mplot3d/voxels_torus.py + .. plot:: /gallery/mplot3d/voxels_numpy_logo.py """ # work out which signature we should be using, and use it to parse From 10aa22e6c21fb9af3c226b16775548811592340f Mon Sep 17 00:00:00 2001 From: Amir MOHAMMADI Date: Tue, 9 Oct 2018 14:43:09 +0200 Subject: [PATCH 4/8] sphinx plot directive: api changes --- .../2018-10-09-plot-directive.rst | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) create mode 100644 doc/api/next_api_changes/2018-10-09-plot-directive.rst 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 new file mode 100644 index 000000000000..353cf6021afc --- /dev/null +++ b/doc/api/next_api_changes/2018-10-09-plot-directive.rst @@ -0,0 +1,19 @@ +Changes regarding the Sphinx plot directive +``````````````````````````````````````````` + +Fixed a bug in the Sphinx plot directive (.. plot:: path/to/plot_script.py) +where the source Python file was not being found relative to the directory of +the file containing the directive. In addition, its behavior was changed to +make it more streamlined with other Sphinx commands. + +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). +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. From 2b81c1256c1c71a5e91ad602209ac06ef12b7ecb Mon Sep 17 00:00:00 2001 From: Amir MOHAMMADI Date: Sun, 3 Mar 2019 12:37:32 +0100 Subject: [PATCH 5/8] partly implement the deprecation mechanism --- .../2018-10-09-plot-directive.rst | 16 ++++-- lib/matplotlib/sphinxext/plot_directive.py | 56 ++++++++++++++++--- 2 files changed, 59 insertions(+), 13 deletions(-) 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 index 353cf6021afc..1ed5939ecbff 100644 --- 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 index 95047b5139c8..807ddec7ef5f 100644 --- 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) From 7ceea9e77259d5253ed106ae2c607dc03dcf82fe Mon Sep 17 00:00:00 2001 From: Amir MOHAMMADI Date: Sun, 3 Mar 2019 16:10:51 +0100 Subject: [PATCH 6/8] Change plot_dir_resolve_method to plot_path_resolution_method --- .../2018-10-09-plot-directive.rst | 6 ++--- lib/matplotlib/sphinxext/plot_directive.py | 26 +++++++++---------- 2 files changed, 16 insertions(+), 16 deletions(-) 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 index 1ed5939ecbff..277475e15154 100644 --- a/doc/api/next_api_changes/2018-10-09-plot-directive.rst +++ b/doc/api/next_api_changes/2018-10-09-plot-directive.rst @@ -21,7 +21,7 @@ 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 +``plot_path_resolution_method='old'`` in ``conf.py`` and specify +``plot_path_resolution_method='relative'`` to get the new behavior. The old +behavior will 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 index 807ddec7ef5f..bdaab8f6f3a8 100644 --- a/lib/matplotlib/sphinxext/plot_directive.py +++ b/lib/matplotlib/sphinxext/plot_directive.py @@ -100,26 +100,26 @@ import numpy as np from matplotlib import pyplot as plt - plot_dir_resolve_method + plot_path_resolution_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`` + ``old``. Defaults to ``old`` but the default value will + change to ``relative`` in future versions. The ``old`` method + is deprecated and will be removed in future. See the ``plot_basedir`` for explanation of methods. plot_basedir 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_path_resolution_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. + If ``plot_path_resolution_method`` is ``old``, relative paths are found + relative to ``plot_basedir`` and absolute paths point to files in the + host system. This method is deprecated and will be removed in future. plot_formats File formats to generate. List of tuples or strings:: @@ -687,7 +687,7 @@ def run(arguments, content, options, state_machine, state, lineno): if len(arguments): # if the new method is selected for resolving paths - if config.plot_dir_resolve_method.lower() == 'relative': + if config.plot_path_resolution_method.lower() == 'relative': if arguments[0].startswith('/'): arguments[0] = arguments[0][1:] @@ -703,7 +703,7 @@ def run(arguments, content, options, state_machine, state, lineno): '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 ' + '``plot_path_resolution_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 ' From 58643351b79fe82db31f349dd9630ed488bff4c7 Mon Sep 17 00:00:00 2001 From: Amir MOHAMMADI Date: Sun, 3 Mar 2019 16:13:41 +0100 Subject: [PATCH 7/8] Change conf.py to use the new plot_path_resolution_method relative method --- doc/conf.py | 1 + 1 file changed, 1 insertion(+) diff --git a/doc/conf.py b/doc/conf.py index df7a93b31cdc..a17040bf1fea 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -204,6 +204,7 @@ def _check_dependencies(): # ---------------------------- plot_formats = [('png', 100), ('pdf', 100)] +plot_path_resolution_method = 'relative' # Github extension From 3f29261ee46d6e4aad1b1fde234d3719d4e5c22e Mon Sep 17 00:00:00 2001 From: Amir MOHAMMADI Date: Sun, 3 Mar 2019 16:38:03 +0100 Subject: [PATCH 8/8] Add plot_path_resolution_method as known config values --- lib/matplotlib/sphinxext/plot_directive.py | 1 + 1 file changed, 1 insertion(+) diff --git a/lib/matplotlib/sphinxext/plot_directive.py b/lib/matplotlib/sphinxext/plot_directive.py index bdaab8f6f3a8..c08dd88e98b0 100644 --- a/lib/matplotlib/sphinxext/plot_directive.py +++ b/lib/matplotlib/sphinxext/plot_directive.py @@ -303,6 +303,7 @@ def setup(app): app.add_config_value('plot_html_show_source_link', True, True) app.add_config_value('plot_formats', ['png', 'hires.png', 'pdf'], True) app.add_config_value('plot_basedir', None, True) + app.add_config_value('plot_path_resolution_method', 'old', True) app.add_config_value('plot_html_show_formats', True, True) app.add_config_value('plot_rcparams', {}, True) app.add_config_value('plot_apply_rcparams', False, True)