matplotlib.sphinxext.plot_directive#

A directive for including a Matplotlib plot in a Sphinx document#

This is a Sphinx extension providing a reStructuredText directive..plot:: for including a plot in a Sphinx document.

In HTML output,..plot:: will include a .png file with a linkto a high-res .png and .pdf. In LaTeX output, it will include a .pdf.

The plot content may be defined in one of three ways:

  1. A path to a source file as the argument to the directive:

    ..plot::path/to/plot.py

    When a path to a source file is given, the content of thedirective may optionally contain a caption for the plot:

    ..plot::path/to/plot.pyTheplotcaption.

    Additionally, one may specify the name of a function to call (withno arguments) immediately after importing the module:

    ..plot::path/to/plot.pyplot_function1

  2. Included asinline content to the directive:

    ..plot::importmatplotlib.pyplotaspltplt.plot([1,2,3],[4,5,6])plt.title("A plotting example")

  3. Usingdoctest syntax:

    ..plot::Aplottingexample:>>>importmatplotlib.pyplotasplt>>>plt.plot([1,2,3],[4,5,6])

Options#

The..plot:: directive supports the following options:

:format:{'python', 'doctest'}

The format of the input. If unset, the format is auto-detected.

:include-source:bool

Whether to display the source code. The default can be changed usingtheplot_include_source variable inconf.py (which itselfdefaults to False).

:show-source-link:bool

Whether to show a link to the source in HTML. The default can bechanged using theplot_html_show_source_link variable inconf.py (which itself defaults to True).

:context:bool or str

If provided, the code will be run in the context of all previous plotdirectives for which the:context: option was specified. This onlyapplies to inline code plot directives, not those run from files. Ifthe:context:reset option is specified, the context is resetfor this and future plots, and previous figures are closed prior torunning the code.:context:close-figs keeps the context but closesprevious figures before running the code.

:nofigs:bool

If specified, the code block will be run, but no figures will beinserted. This is usually useful with the:context: option.

:caption:str

If specified, the option's argument will be used as a caption for thefigure. This overwrites the caption given in the content, when the plotis generated from a file.

Additionally, this directive supports all the options of theimage directive,except for:target: (since plot will add its own target). These include:alt:,:height:,:width:,:scale:,:align: and:class:.

Configuration options#

The plot directive has the following configuration options:

plot_include_source

Default value for the include-source option (default: False).

plot_html_show_source_link

Whether to show a link to the source in HTML (default: True).

plot_pre_code

Code that should be executed before each plot. If None (the default),it will default to a string containing:

importnumpyasnpfrommatplotlibimportpyplotasplt
plot_basedir

Base directory, to whichplot:: file names are relative to.If None or empty (the default), file names are relative to thedirectory where the file containing the directive is.

plot_formats

File formats to generate (default: ['png', 'hires.png', 'pdf']).List of tuples or strings:

[(suffix,dpi),suffix,...]

that determine the file format and the DPI. For entries whoseDPI was omitted, sensible defaults are chosen. When passing fromthe command line through sphinx_build the list should be passed assuffix:dpi,suffix:dpi, ...

plot_html_show_formats

Whether to show links to the files in HTML (default: True).

plot_rcparams

A dictionary containing any non-standard rcParams that shouldbe applied before each plot (default: {}).

plot_apply_rcparams

By default, rcParams are applied when:context: option is not usedin a plot directive. If set, this configuration option overrides thisbehavior and applies rcParams before each plot.

plot_working_directory

By default, the working directory will be changed to the directory ofthe example, so the code can get at its data files, if any. Also itspath will be added tosys.path so it can import any helper modulessitting beside it. This configuration option can be used to specifya central directory (also added tosys.path) where data files andhelper modules for all code are located.

plot_template

Provide a customized template for preparing restructured text.

plot_srcset

Allow the srcset image option for responsive image resolutions. List ofstrings with the multiplicative factors followed by an "x".e.g. ["2.0x", "1.5x"]. "2.0x" will create a png with the default "png"resolution from plot_formats, multiplied by 2. If plot_srcset isspecified, the plot directive uses thematplotlib.sphinxext.figmpl_directive (instead of the usual figuredirective) in the intermediary rst file that is generated.The plot_srcset option is incompatible withsinglehtml builds, and anerror will be raised.

Notes on how it works#

The plot directive runs the code it is given, either in the source file or thecode under the directive. The figure created (if any) is saved in the sphinxbuild directory under a subdirectory namedplot_directive. It then createsan intermediate rst file that calls a..figure: directive (or..figmpl:: directive ifplot_srcset is being used) and has links tothe*.png files in theplot_directive directory. These translations canbe customized by changing theplot_template. See the source ofmatplotlib.sphinxext.plot_directive for the templates defined inTEMPLATEandTEMPLATE_SRCSET.

classmatplotlib.sphinxext.plot_directive.PlotDirective(name,arguments,options,content,lineno,content_offset,block_text,state,state_machine)[source]#

The..plot:: directive, as documented in the module's docstring.

final_argument_whitespace=False#

May the final argument contain whitespace?

has_content=True#

May the directive have content?

option_spec={'align':<functionImage.align>,'alt':<functionunchanged>,'caption':<functionunchanged>,'class':<functionclass_option>,'context':<function_option_context>,'format':<function_option_format>,'height':<functionlength_or_unitless>,'include-source':<function_option_boolean>,'nofigs':<functionflag>,'scale':<functionnonnegative_int>,'show-source-link':<function_option_boolean>,'width':<functionlength_or_percentage_or_unitless>}#

Mapping of option names to validator functions.

optional_arguments=2#

Number of optional arguments after the required arguments.

required_arguments=0#

Number of required directive arguments.

run()[source]#

Run the plot directive.

exceptionmatplotlib.sphinxext.plot_directive.PlotError[source]#
matplotlib.sphinxext.plot_directive.mark_plot_labels(app,document)[source]#

To make plots referenceable, we need to move the reference from the"htmlonly" (or "latexonly") node to the actual figure node itself.

matplotlib.sphinxext.plot_directive.out_of_date(original,derived,includes=None)[source]#

Return whetherderived is out-of-date relative tooriginal or any ofthe RST files included in it using the RST include directive (includes).derived andoriginal are full paths, andincludes is optionally alist of full paths which may have been included in theoriginal.

matplotlib.sphinxext.plot_directive.render_figures(code,code_path,output_dir,output_base,context,function_name,config,context_reset=False,close_figs=False,code_includes=None)[source]#

Run a pyplot script and save the images inoutput_dir.

Save the images underoutput_dir with file names derived fromoutput_base