10000 Add an output-base-name option to the Sphinx plot directive · matplotlib/matplotlib@615017a · GitHub
[go: up one dir, main page]
Skip to content

Commit 615017a

Browse files
asmeurerasmeurer
committed
Add an output-base-name option to the Sphinx plot directive
This allows specifying the output base name of the generated image files. The name can include '{counter}', which is automatically string formatted to an incrementing counter. The default if it is not specified is left intact as the current behavior, which is to use the base name of the provided script or the RST document. This is required to use the plot directive with MyST, because the directive is broken with MyST (an issue I don't want to fix), requiring the use of eval-rst. But the way eval-rst works, the incrementing counter is not maintained across different eval-rst directives, meaning if you try to include multiple of them in the same document, the images will overwrite each other. This allows you to manually work around this with something like ```{eval-rst} .. plot:: :output-base-name: plot-1 ... ``` ```{eval-rst} .. plot:: :output-base-name: plot-2 ... ``` Aside from this, it's generally useful to be able to specify the image name used for a plot, as a more informative name can be used rather than just '<document-name>-1.png'.
1 parent ce15014 commit 615017a

File tree

1 file changed

+24
-2
lines changed

1 file changed

+24
-2
lines changed

‎lib/matplotlib/sphinxext/plot_directive.py

Lines changed: 24 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -47,6 +47,15 @@
4747
4848
The ``.. plot::`` directive supports the following options:
4949
50+
``:output-base-name:`` : str
51+
The base name (without the extension) of the outputted image files. The
52+
default is to use the same name as the input script, or the name of
53+
the RST document if no script is provided. The string can include the
54+
format ``{counter}`` to use an incremented counter. For example,
55+
``'plot-{counter}'`` will create files like ``plot-1.png``, ``plot-2.png``,
56+
and so on. If the ``{counter}`` is not provided, two plots with the same
57+
output-base-name may overwrite each other.
58+
5059
``:format:`` : {'python', 'doctest'}
5160
The format of the input. If unset, the format is auto-detected.
5261
@@ -88,6 +97,10 @@
8897
8998
The plot directive has the following configuration options:
9099
100+
plot_output_base_name
101+
Default value for the output-base-name option (default is to use the name
102+
of the input script, or the name of the RST file if no script is provided)
103+
91104
plot_include_source
92105
Default value for the include-source option (default: False).
93106
@@ -265,6 +278,7 @@ class PlotDirective(Directive):
265278
'scale': directives.nonnegative_int,
266279
'align': Image.align,
267280
'class': directives.class_option,
281+
'output-base-name': directives.unchanged,
268282
'include-source': _option_boolean,
269283
'show-source-link': _option_boolean,
270284
'format': _option_format,
@@ -299,6 +313,7 @@ def setup(app):
299313
app.add_config_value('plot_pre_code', None, True)
300314
app.add_config_value('plot_include_source', False, True)
301315
app.add_config_value('plot_html_show_source_link', True, True)
316+
app.add_config_value('plot_output_base_name', None, True)
302317
app.add_config_value('plot_formats', ['png', 'hires.png', 'pdf'], True)
303318
app.add_config_value('plot_basedir', None, True)
304319
app.add_config_value('plot_html_show_formats', True, True)
@@ -734,6 +749,7 @@ def run(arguments, content, options, state_machine, state, lineno):
734749

735750
options.setdefault('include-source', config.plot_include_source)
736751
options.setdefault('show-source-link', config.plot_html_show_source_link)
752+
options.setdefault('output-base-name', config.plot_output_base_name)
737753

738754
if 'class' in options:
739755
# classes are parsed into a list of string, and output by simply
@@ -775,14 +791,20 @@ def run(arguments, content, options, state_machine, state, lineno):
775791
function_name = None
776792

777793
code = Path(source_file_name).read_text(encoding='utf-8')
778-
output_base = os.path.basename(source_file_name)
794+
if options['output-base-name']:
795+
output_base = options['output-base-name']
796+
else:
797+
output_base = os.path.basename(source_file_name)
779798
else:
780799
source_file_name = rst_file
781800
code = textwrap.dedent("\n".join(map(str, content)))
782801
counter = document.attributes.get('_plot_counter', 0) + 1
783802
document.attributes['_plot_counter'] = counter
784803
base, ext = os.path.splitext(os.path.basename(source_file_name))
785-
output_base = '%s-%d.py' % (base, counter)
804+
if options['output-base-name']:
805+
output_base = options['output-base-name'].format(counter=counter)
806+
else:
807+
output_base = '%s-%d.py' % (base, counter)
786808
function_name = None
787809
caption = options.get('caption', '')
788810

0 commit comments

Comments
 (0)
0