matplotlib.sphinxext.plot_directive#
用于在Sphinx文档中包含Matplotlib图表的指令#
这是一个提供 reStructuredText 指令 .. plot:: 的 Sphinx 扩展，用于在 Sphinx 文档中包含图表。
在HTML输出中，.. plot:: 将包含一个带有高分辨率 .png 和 .pdf 链接的 .png 文件。在LaTeX输出中，它将包含一个 .pdf 文件。
绘图内容可以通过以下三种方式之一定义：
一个源文件的路径 作为指令的参数:
.. plot:: path/to/plot.py
当给定源文件的路径时，指令的内容可以选择包含图表的标题:
.. plot:: path/to/plot.py The plot caption.
此外，可以在导入模块后立即指定要调用的函数名称（不带参数）:
.. plot:: path/to/plot.py plot_function1
作为指令的 内联内容 包含:
.. plot:: import matplotlib.pyplot as plt plt.plot([1, 2, 3], [4, 5, 6]) plt.title("A plotting exammple")
使用 doctest 语法:
.. plot:: A plotting example: >>> import matplotlib.pyplot as plt >>> plt.plot([1, 2, 3], [4, 5, 6])
选项#
.. plot:: 指令支持以下选项：
:format:{'python', 'doctest'}输入的格式。如果未设置，格式将自动检测。
:include-source:布尔值是否显示源代码。默认值可以通过
conf.py中的plot_include_source变量更改（该变量本身默认为 False）。:show-source-link:布尔值是否在HTML中显示指向源代码的链接。可以通过
conf.py中的plot_html_show_source_link变量更改默认设置（该变量本身默认为 True）。:context:布尔值或字符串如果提供，代码将在所有之前指定了
:context:选项的绘图指令的上下文中运行。这仅适用于内联代码绘图指令，不适用于从文件运行的指令。如果指定了:context: reset选项，上下文将为此及未来的绘图重置，并且在运行代码之前关闭之前的图形。:context: close-figs保持上下文，但在运行代码之前关闭之前的图形。:nofigs:布尔值如果指定，代码块将被运行，但不会插入任何图形。这通常与
:context:选项一起使用。:caption:str如果指定，选项的参数将用作图形的标题。当图形从文件生成时，这将覆盖内容中给出的标题。
此外，此指令支持 图像指令 的所有选项，除了 :target:``（因为绘图将添加自己的目标）。这些包括 ``:alt:、:height:、:width:、:scale:、:align: 和 :class:。
配置选项#
绘图指令具有以下配置选项：
plot_include_sourceinclude-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提供一个用于准备 restructured text 的自定义模板。
- plot_srcset
允许使用srcset图像选项来实现响应式图像分辨率。字符串列表，包含乘法因子后跟一个“x”。例如：["2.0x", "1.5x"]。"2.0x"将创建一个png图像，其分辨率为plot_formats中的默认“png”分辨率的两倍。如果指定了plot_srcset，plot指令将在生成的中间rst文件中使用:doc:`/api/sphinxext_figmpl_directive_api`（而不是通常的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>, '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#
所需指令参数的数量。
- matplotlib.sphinxext.plot_directive.mark_plot_labels(app, document)[源代码][源代码]#
为了使图表可引用，我们需要将引用从“htmlonly”（或“latexonly”）节点移动到实际的图表节点本身。