matplotlib.sphinxext.plot_directive#

在Sphinx文档中包含Matplotlib绘图的指令#

这是一个Sphinx扩展，提供了一个reStructuredText指令 .. plot:: 用于在Sphinx文档中包含绘图。

在HTML输出中，.. plot:: 将包含一个.png文件，并链接到高分辨率的.png和.pdf文件。在LaTeX输出中，它将包含一个.pdf文件。

绘图内容可以通过以下三种方式之一进行定义

  1. **源文件路径** 作为指令的参数

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

    当给定源文件路径时，指令的内容可以（可选地）包含绘图的标题

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

   The plot caption.

    此外，可以在导入模块后立即指定要调用的函数名称（不带参数）

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

  2. 作为**内联内容**包含到指令中

    .. plot::

   import matplotlib.pyplot as plt
   plt.plot([1, 2, 3], [4, 5, 6])
   plt.title("A plotting exammple")

  3. 使用**doctest**语法

    .. plot::

   A plotting example:
   >>> import matplotlib.pyplot as plt
   >>> plt.plot([1, 2, 3], [4, 5, 6])

选项#

.. plot:: 指令支持以下选项

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

输入格式。如果未设置，将自动检测格式。

:include-source:bool

是否显示源代码。可以使用 conf.py 中的 plot_include_source 变量来更改默认值（其自身默认为False）。

:show-source-link:bool

是否在HTML中显示源代码链接。可以使用 conf.py 中的 plot_html_show_source_link 变量来更改默认值（其自身默认为True）。

:context:bool or str

如果提供此选项，代码将在指定了 :context: 选项的所有先前绘图指令的上下文中运行。这仅适用于内联代码绘图指令，不适用于从文件运行的指令。如果指定了 :context: reset 选项，此绘图和未来绘图的上下文将被重置，并且在运行代码之前会关闭先前的图形。:context: close-figs 保持上下文，但在运行代码之前关闭先前的图形。

:nofigs:bool

如果指定此选项，代码块将运行，但不会插入任何图形。这通常与 :context: 选项结合使用时很有用。

:caption:str

如果指定此选项，其参数将用作图形的标题。当从文件生成绘图时，此选项会覆盖内容中给出的标题。

此外，此指令支持 图像指令 的所有选项，除了 :target:（因为绘图会添加自己的目标）。这些选项包括 :alt:、:height:、:width:、:scale:、:align: 和 :class:。

配置选项#

绘图指令具有以下配置选项

plot_include_source

include-source 选项的默认值（默认值：False）。

plot_html_show_source_link

是否在HTML中显示源代码链接（默认值：True）。

plot_pre_code

在每次绘图之前应执行的代码。如果为None（默认值），它将默认为包含以下内容的字符串

import numpy as np
from matplotlib import pyplot as plt
plot_basedir

基本目录，plot:: 文件名相对于此目录。如果为None或为空（默认值），文件名将相对于包含指令的文件所在的目录。

plot_formats

要生成的文件格式（默认值：['png', 'hires.png', 'pdf']）。元组或字符串列表

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

用于确定文件格式和DPI。对于省略了DPI的条目，将选择合理的默认值。当通过命令行经由 sphinx_build 传递时，列表应以 suffix:dpi,suffix:dpi, ... 的形式传递。

plot_html_show_formats

是否在HTML中显示文件链接（默认值：True）。

plot_rcparams

一个字典，包含应在每次绘图前应用的任何非标准rcParams（默认值：{}）。

plot_apply_rcparams

默认情况下，当绘图指令中未使用 :context: 选项时，rcParams 会被应用。如果设置了此配置选项，它将覆盖此行为，并在每次绘图前应用 rcParams。

plot_working_directory

默认情况下，工作目录将更改为示例所在的目录，以便代码（如果有）可以访问其数据文件。同时其路径将被添加到 sys.path 中，以便它可以导入其旁边的任何辅助模块。此配置选项可用于指定一个中心目录（也添加到 sys.path 中），所有代码的数据文件和辅助模块都位于该目录中。

plot_template

提供用于准备reStructuredText的自定义模板。

plot_srcset

允许 srcset 图像选项用于响应式图像分辨率。一个字符串列表，包含乘数因子后跟一个“x”。例如 ["2.0x", "1.5x"]。“2.0x” 将创建一个 png，其分辨率是 plot_formats 中默认“png”分辨率的两倍。如果指定了 plot_srcset，绘图指令将在生成的中间 rst 文件中使用 matplotlib.sphinxext.figmpl_directive（而不是通常的 figure 指令）。plot_srcset 选项与 singlehtml 构建不兼容，并且会引发错误。

工作原理说明#

绘图指令会运行给定代码，无论是在源文件中还是在指令下的代码。创建的图形（如果有）将保存到 sphinx 构建目录中名为 plot_directive 的子目录下。然后，它会创建一个中间 rst 文件，该文件调用一个 .. figure: 指令（如果正在使用 plot_srcset，则为 .. figmpl:: 指令），并链接到 plot_directive 目录中的 *.png 文件。这些转换可以通过更改 plot_template 进行自定义。请参阅 matplotlib.sphinxext.plot_directive 的源代码，以了解 TEMPLATE 和 TEMPLATE_SRCSET 中定义的模板。

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

.. plot:: 指令，如模块的文档字符串中所述。

final_argument_whitespace = False#

最后一个参数是否可以包含空格？

has_content = True#

指令是否可以包含内容？

option_spec = {'align': <function Image.align>, 'alt': <function unchanged>, 'caption': <function unchanged>, 'class': <function class_option>, 'context': <function _option_context>, 'format': <function _option_format>, 'height': <function length_or_unitless>, 'include-source': <function _option_boolean>, 'nofigs': <function flag>, 'scale': <function nonnegative_int>, 'show-source-link': <function _option_boolean>, 'width': <function length_or_percentage_or_unitless>}#

选项名称到验证函数的映射。

optional_arguments = 2#

必需参数后的可选参数数量。

required_arguments = 0#

必需指令参数的数量。

run()[source]#

运行绘图指令。

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

为了使绘图可引用，我们需要将引用从“htmlonly”（或“latexonly”）节点移动到实际的图形节点本身。

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

返回 derived 相对于 original 或使用 RST include 指令（includes）包含在其内的任何 RST 文件是否已过期。derived 和 original 都是完整路径，而 includes 可选地是一个完整路径列表，这些路径可能已包含在 original 中。

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]#

运行 pyplot 脚本并将图像保存到 output_dir 中。

将图像保存到 output_dir 下，文件名派生自 output_base

在此页