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 example")

  3. 使用 doctest 语法

    .. plot::

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

选项#

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

:filename-prefix:str

输出图像和脚本文件的基本名称（不含扩展名）。默认使用与输入脚本相同的名称，如果未提供脚本，则使用 RST 文档名称。每个 plot 指令的 filename-prefix 必须是唯一的。

: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 或 str

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

:nofigs:bool

如果指定，代码块将运行，但不插入任何图形。这通常与 :context: 选项一起使用。

:caption:str

如果指定，该选项的参数将用作图形的说明文字。当从文件生成绘图时，这会覆盖内容中给出的说明文字。

:code-caption:str

如果指定，该选项的参数将用作代码块的说明文字（当使用 :include-source: 时）。这作为 :caption: 选项被添加到 .. code-block:: 指令中。

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

配置选项#

plot 指令具有以下配置选项

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

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

plot_working_directory

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

plot_template

提供用于准备重组文本 (restructured text) 的自定义模板。

plot_srcset

允许针对响应式图像分辨率使用 srcset 图像选项。包含乘数因子后跟 "x" 的字符串列表。例如 ["2.0x", "1.5x"]。"2.0x" 将创建一个分辨率为 plot_formats 中默认 "png" 分辨率乘以 2 的 png 文件。如果指定了 plot_srcset，plot 指令将在生成的中间 rst 文件中使用 matplotlib.sphinxext.figmpl_directive（而不是通常的 figure 指令）。plot_srcset 选项与 singlehtml 构建不兼容，否则会报错。

工作原理说明#

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

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

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

final_argument_whitespace = False#

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

has_content = True#

指令是否可以包含内容？

option_spec = {'align': <function Image.align>, 'alt': <function unchanged>, 'caption': <function unchanged>, 'class': <function class_option>, 'code-caption': <function unchanged>, 'context': <function _option_context>, 'filename-prefix': <function unchanged>, '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()[源代码]#

运行 plot 指令。

exception matplotlib.sphinxext.plot_directive.PlotError[源代码]#
matplotlib.sphinxext.plot_directive.mark_plot_labels(app, document)[源代码]#

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

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

返回 derived 相对于 original 或使用 RST include 指令包含在其中的任何 RST 文件 (includes) 是否已过期。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)[源代码]#

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

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