<divid="unreleased-message"> You are reading an old version of the documentation (v2.2.2). For the latest version see <ahref="/stable/">https://matplotlib.org/stable/</a></div>
<spanid="plot-directive-documentation"></span><h1>Plot directive documentation<aclass="headerlink" href="#module-matplotlib.sphinxext.plot_directive" title="Permalink to this headline">¶</a></h1>
<p>A directive for including a matplotlib plot in a Sphinx document.</p>
<p>By default, in HTML output, <codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">plot</span></code> will include a .png file with a
link to a high-res .png and .pdf. In LaTeX output, it will include a
.pdf.</p>
<p>The source code for the plot may be included in one of three ways:</p>
<blockquote>
<div><olclass="arabic">
<li><pclass="first"><strong>A path to a source file</strong> as the argument to the directive:</p>
<dd>If this source file is in a non-UTF8 or non-ASCII encoding,
the encoding must be specified using the <codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">:encoding:</span></code> option.
The encoding will not be inferred using the <codeclass="docutils literal notranslate"><spanclass="pre">-*-</span><spanclass="pre">coding</span><spanclass="pre">-*-</span></code>
metacomment.</dd>
<dt>context <spanclass="classifier-delimiter">:</span><spanclass="classifier">bool or str</span></dt>
<dd>If provided, the code will be run in the context of all
previous plot directives for which the <codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">:context:</span></code> option was
specified. This only applies to inline code plot directives,
not those run from files. If the <codeclass="docutils literal notranslate"><spanclass="pre">:context:</span><spanclass="pre">reset</span></code> option is
specified, the context is reset for this and future plots, and
previous figures are closed prior to running the code.
<codeclass="docutils literal notranslate"><spanclass="pre">:context:close-figs</span></code> keeps the context but closes previous figures
<pclass="last">that determine the file format and the DPI. For entries whose
DPI was omitted, sensible defaults are chosen. When passing from
the command line through sphinx_build the list should be passed as
suffix:dpi,suffix:dpi, ….</p>
</dd>
<dt>plot_html_show_formats</dt>
<dd>Whether to show links to the files in HTML.</dd>
<dt>plot_rcparams</dt>
<dd>A dictionary containing any non-standard rcParams that should
be applied before each plot.</dd>
<dt>plot_apply_rcparams</dt>
<dd>By default, rcParams are applied when <codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">context</span></code> option is not used in
a plot directive. This configuration option overrides this behavior
and applies rcParams before each plot.</dd>
<dt>plot_working_directory</dt>
<dd>By default, the working directory will be changed to the directory of
the example, so the code can get at its data files, if any. Also its
path will be added to <aclass="reference external" href="https://docs.python.org/3/library/sys.html#sys.path" title="(in Python v3.7)"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">sys.path</span></code></a> so it can import any helper modules
sitting beside it. This configuration option can be used to specify
a central directory (also added to <aclass="reference external" href="https://docs.python.org/3/library/sys.html#sys.path" title="(in Python v3.7)"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">sys.path</span></code></a>) where data files and
helper modules for all code are located.</dd>
<dt>plot_template</dt>
<dd>Provide a customized template for preparing restructured text.</dd>
<emclass="property">exception </em><codeclass="descclassname">matplotlib.sphinxext.plot_directive.</code><codeclass="descname">PlotError</code><aclass="reference internal" href="../_modules/matplotlib/sphinxext/plot_directive.html#PlotError"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink" href="#matplotlib.sphinxext.plot_directive.PlotError" title="Permalink to this definition">¶</a></dt>
<codeclass="descclassname">matplotlib.sphinxext.plot_directive.</code><codeclass="descname">mark_plot_labels</code><spanclass="sig-paren">(</span><em>app</em>, <em>document</em><spanclass="sig-paren">)</span><aclass="reference internal" href="../_modules/matplotlib/sphinxext/plot_directive.html#mark_plot_labels"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink" href="#matplotlib.sphinxext.plot_directive.mark_plot_labels" title="Permalink to this definition">¶</a></dt>
<dd><p>To make plots referenceable, we need to move the reference from
the “htmlonly” (or “latexonly”) node to the actual figure node
<codeclass="descclassname">matplotlib.sphinxext.plot_directive.</code><codeclass="descname">out_of_date</code><spanclass="sig-paren">(</span><em>original</em>, <em>derived</em><spanclass="sig-paren">)</span><aclass="reference internal" href="../_modules/matplotlib/sphinxext/plot_directive.html#out_of_date"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink" href="#matplotlib.sphinxext.plot_directive.out_of_date" title="Permalink to this definition">¶</a></dt>
<dd><p>Returns True if derivative is out-of-date wrt original,
<codeclass="descclassname">matplotlib.sphinxext.plot_directive.</code><codeclass="descname">remove_coding</code><spanclass="sig-paren">(</span><em>text</em><spanclass="sig-paren">)</span><aclass="reference internal" href="../_modules/matplotlib/sphinxext/plot_directive.html#remove_coding"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink" href="#matplotlib.sphinxext.plot_directive.remove_coding" title="Permalink to this definition">¶</a></dt>
<dd><p>Remove the coding comment, which six.exec_ doesn’t like.</p>
<codeclass="descclassname">matplotlib.sphinxext.plot_directive.</code><codeclass="descname">split_code_at_show</code><spanclass="sig-paren">(</span><em>text</em><spanclass="sig-paren">)</span><aclass="reference internal" href="../_modules/matplotlib/sphinxext/plot_directive.html#split_code_at_show"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink" href="#matplotlib.sphinxext.plot_directive.split_code_at_show" title="Permalink to this definition">¶</a></dt>
<codeclass="descclassname">matplotlib.sphinxext.plot_directive.</code><codeclass="descname">unescape_doctest</code><spanclass="sig-paren">(</span><em>text</em><spanclass="sig-paren">)</span><aclass="reference internal" href="../_modules/matplotlib/sphinxext/plot_directive.html#unescape_doctest"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink" href="#matplotlib.sphinxext.plot_directive.unescape_doctest" title="Permalink to this definition">¶</a></dt>
<dd><p>Extract code from a piece of text, which contains either Python code