From 0d9e6c167339e8b9f6dfd00bc85b700c08716cb8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9rome=20Eertmans?= Date: Fri, 9 Jun 2023 16:41:57 +0200 Subject: [PATCH 1/5] feat(plot_directive): add RST directory option Hello! After trying to set up my own documentation, I had trouble making the `plot_directive` work with the `autodoc2` extension. `autodoc2` is unlike `sphinx.ext.autodoc` because it automatically generates all RST files, at a place that is not the same where we would usually call `autodoc`'s directives. To cope with this problem, I had to implement my own Sphinx directive, based on yours. This may not be the perfect solution, but it works fine. Feel free to suggest any change :-) If you want to see a live example of this, here is the repo I developed the solution for: https://github.com/jeertmans/DiffeRT2d --- lib/matplotlib/sphinxext/plot_directive.py | 25 +++++++++++++++++++++- 1 file changed, 24 insertions(+), 1 deletion(-) diff --git a/lib/matplotlib/sphinxext/plot_directive.py b/lib/matplotlib/sphinxext/plot_directive.py index 45ca91f8b2ee..a8abd0963220 100644 --- a/lib/matplotlib/sphinxext/plot_directive.py +++ b/lib/matplotlib/sphinxext/plot_directive.py @@ -150,6 +150,24 @@ directive) in the intermediary rst file that is generated. The plot_srcset option is incompatible with *singlehtml* builds, and an error will be raised. + + plot_rst_directory + By default, the directory for RST files is automatically determined + from the name of the Python file. This works fine with, e.g., the + ``sphinx.ext.autodoc`` extension. However, you may need to modify the + path if RST files are generated in another directory. This is the + case if you use the ``autodoc2`` extension. + + For it to work, you need to set the ``plot_rst_directory`` option to: + + .. code:: python + + plot_rst_directory = "source/apidocs//" + + .. node:: + + This currently only support one directory, and can cause potential + problems if you have multiple packages documented with ``autodoc2``. Notes on how it works --------------------- @@ -307,6 +325,7 @@ def setup(app): app.add_config_value('plot_working_directory', None, True) app.add_config_value('plot_template', None, True) app.add_config_value('plot_srcset', [], True) + app.add_config_value('plot_rst_directory', None, True) app.connect('doctree-read', mark_plot_labels) app.add_css_file('plot_directive.css') app.connect('build-finished', _copy_css_file) @@ -746,7 +765,11 @@ def run(arguments, content, options, state_machine, state, lineno): context_opt = None if not keep_context else options['context'] rst_file = document.attributes['source'] - rst_dir = os.path.dirname(rst_file) + + if not config.plot_rst_directory: + rst_dir = os.path.dirname(rst_file) + else: + rst_dir = config.plot_rst_directory if len(arguments): if not config.plot_basedir: From fb04730e2c03c0a2018da59243c031e40ac701b5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9rome=20Eertmans?= Date: Fri, 9 Jun 2023 16:54:43 +0200 Subject: [PATCH 2/5] chore(lint): remove whitespaces --- lib/matplotlib/sphinxext/plot_directive.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/lib/matplotlib/sphinxext/plot_directive.py b/lib/matplotlib/sphinxext/plot_directive.py index a8abd0963220..a0b7cce08f24 100644 --- a/lib/matplotlib/sphinxext/plot_directive.py +++ b/lib/matplotlib/sphinxext/plot_directive.py @@ -150,7 +150,7 @@ directive) in the intermediary rst file that is generated. The plot_srcset option is incompatible with *singlehtml* builds, and an error will be raised. - + plot_rst_directory By default, the directory for RST files is automatically determined from the name of the Python file. This works fine with, e.g., the @@ -765,7 +765,7 @@ def run(arguments, content, options, state_machine, state, lineno): context_opt = None if not keep_context else options['context'] rst_file = document.attributes['source'] - + if not config.plot_rst_directory: rst_dir = os.path.dirname(rst_file) else: From afe63c8181471ba51f62cca8f1128571a4733f2f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9rome=20Eertmans?= Date: Fri, 9 Jun 2023 21:31:48 +0200 Subject: [PATCH 3/5] Update lib/matplotlib/sphinxext/plot_directive.py Co-authored-by: Thomas A Caswell --- 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 a0b7cce08f24..c4009737f897 100644 --- a/lib/matplotlib/sphinxext/plot_directive.py +++ b/lib/matplotlib/sphinxext/plot_directive.py @@ -164,7 +164,7 @@ plot_rst_directory = "source/apidocs//" - .. node:: + .. note:: This currently only support one directory, and can cause potential problems if you have multiple packages documented with ``autodoc2``. From 9c99e19bcb00caec471135c00a85646c2f29dc3f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9rome=20Eertmans?= Date: Fri, 9 Jun 2023 21:33:32 +0200 Subject: [PATCH 4/5] Update lib/matplotlib/sphinxext/plot_directive.py Co-authored-by: Thomas A Caswell --- lib/matplotlib/sphinxext/plot_directive.py | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/lib/matplotlib/sphinxext/plot_directive.py b/lib/matplotlib/sphinxext/plot_directive.py index c4009737f897..8aa0c84d51e6 100644 --- a/lib/matplotlib/sphinxext/plot_directive.py +++ b/lib/matplotlib/sphinxext/plot_directive.py @@ -158,7 +158,8 @@ path if RST files are generated in another directory. This is the case if you use the ``autodoc2`` extension. - For it to work, you need to set the ``plot_rst_directory`` option to: + For it to work, you need to set the ``plot_rst_directory`` option + in ``conf.py``: .. code:: python From 7a9bbadfc8d0186e03d79cddbf1a567bdf4e1d03 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9rome=20Eertmans?= Date: Tue, 20 Jun 2023 10:22:01 +0200 Subject: [PATCH 5/5] Update lib/matplotlib/sphinxext/plot_directive.py MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Melissa Weber Mendonça --- 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 8aa0c84d51e6..2f3630ffe78f 100644 --- a/lib/matplotlib/sphinxext/plot_directive.py +++ b/lib/matplotlib/sphinxext/plot_directive.py @@ -167,7 +167,7 @@ .. note:: - This currently only support one directory, and can cause potential + This currently only supports one directory, and can cause potential problems if you have multiple packages documented with ``autodoc2``. Notes on how it works