matplotlib.sphinxext.plot_directive

Директива для включения графика Matplotlib в документ Sphinx

Это расширение Sphinx предоставляет директиву reStructuredText .. plot:: для включения графика в документ Sphinx.

В выводе HTML .. plot:: включит файл .png со ссылкой на .png высокого разрешения и .pdf. В выводе 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:bool: Показывать ли исходный код. Значение по умолчанию можно изменить с помощью переменной plot_include_source в conf.py (по умолчанию она имеет значение False).
:show-source-link:bool: Показывать ли ссылку на исходный код в HTML. Значение по умолчанию можно изменить с помощью переменной plot_html_show_source_link в conf.py (по умолчанию она имеет значение True).
:context:bool or str: Если задан этот параметр, код будет выполняться в контексте всех предыдущих директив plot, для которых был указан параметр :context:. Это относится только к директивам plot со встроенным кодом, но не к директивам, запускаемым из файлов. Если указан параметр :context: reset, контекст сбрасывается для этой и последующих визуализаций, а предыдущие рисунки закрываются до запуска кода. :context: close-figs сохраняет контекст, но закрывает предыдущие рисунки перед запуском кода.
:nofigs:bool: Если этот параметр указан, блок кода будет выполнен, но рисунки вставлены не будут. Обычно это полезно в сочетании с параметром :context:.
:caption:str: Если этот параметр указан, его аргумент будет использоваться в качестве подписи к рисунку. Если график создаётся из файла, эта подпись заменяет подпись, заданную в содержимом.

Кроме того, эта директива поддерживает все параметры директивы image, кроме :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

По умолчанию rcParams применяются, если в директиве plot не используется параметр :context:. Если задано значение этого параметра конфигурации, оно переопределяет такое поведение, и rcParams применяются перед каждым графиком.

plot_working_directory

По умолчанию рабочий каталог меняется на каталог примера, чтобы код мог обращаться к файлам данных, если они есть. Кроме того, его путь добавляется в sys.path, чтобы можно было импортировать вспомогательные модули, находящиеся рядом с ним. Этот параметр конфигурации позволяет указать общий каталог (также добавляемый в sys.path), где хранятся файлы данных и вспомогательные модули для всего кода.

plot_template

Задаёт пользовательский шаблон для подготовки reStructuredText.

plot_srcset

Разрешает параметр изображения srcset для адаптивных разрешений изображений. Список строк с множителями, за которыми следует «x», например ["2.0x", "1.5x"]. «2.0x» создаст png с разрешением по умолчанию «png» из plot_formats, умноженным на 2. Если задан plot_srcset, директива plot использует matplotlib.sphinxext.figmpl_directive (вместо обычной директивы figure) в промежуточном файле rst, который создаётся. Параметр plot_srcset несовместим со сборками singlehtml; в этом случае будет выдана ошибка.

Принцип работы

Директива plot выполняет переданный ей код — либо из исходного файла, либо из блока кода под директивой. Созданный рисунок (если он есть) сохраняется в каталоге сборки Sphinx во вложенном каталоге с именем plot_directive. Затем создаётся промежуточный файл rst, который вызывает директиву .. figure: (или директиву .. figmpl::, если используется plot_srcset) и содержит ссылки на файлы *.png в каталоге plot_directive. Эти преобразования можно настроить, изменив plot_template. См. исходный код matplotlib.sphinxext.plot_directive, чтобы ознакомиться с шаблонами, определёнными в TEMPLATE и TEMPLATE_SRCSET.

classmatplotlib.sphinxext.plot_directive.PlotDirective(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)[исходный код]

Директива .. plot::, описанная в docstring модуля.

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()[исходный код]: Выполняет директиву plot.

exceptionmatplotlib.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.