Skip to content

feat(plot_directive): add RST directory option #26099

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 7 commits into
base: main
Choose a base branch
from
+25 −1
Open

feat(plot_directive): add RST directory option #26099

Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
0d9e6c1
feat(plot_directive): add RST directory option
jeertmans Jun 9, 2023
fb04730
chore(lint): remove whitespaces
jeertmans Jun 9, 2023
afe63c8
Update lib/matplotlib/sphinxext/plot_directive.py
jeertmans Jun 9, 2023
9c99e19
Update lib/matplotlib/sphinxext/plot_directive.py
jeertmans Jun 9, 2023
7a9bbad
Update lib/matplotlib/sphinxext/plot_directive.py
jeertmans Jun 20, 2023
ed04772
Merge branch 'matplotlib:main' into patch-1
jeertmans Jan 28, 2025
210149c
Merge branch 'matplotlib:main' into patch-1
jeertmans Apr 7, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
26 changes: 25 additions & 1 deletion lib/matplotlib/sphinxext/plot_directive.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -151,6 +151,25 @@
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
in ``conf.py``:

.. code:: python

plot_rst_directory = "source/apidocs/<your_package>/"
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is there a way we can explain the folder situation here? Is this guaranteed to be always under the API docs source dir? I'm thinking of a potential mix between api and narrative docs and where the plots would live for this intermediate state.


.. note::

This currently only supports one directory, and can cause potential
problems if you have multiple packages documented with ``autodoc2``.

Notes on how it works
---------------------

Expand Down Expand Up @@ -307,6 +326,7 @@
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)
Expand Down Expand Up @@ -746,7 +766,11 @@
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

Check warning on line 773 in lib/matplotlib/sphinxext/plot_directive.py

View check run for this annotation

Codecov / codecov/patch

lib/matplotlib/sphinxext/plot_directive.py#L773 

Added line #L773 was not covered by tests

if len(arguments):
if not config.plot_basedir:
Expand Down
Loading