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 или str: Если задано, код будет выполняться в контексте всех предыдущих директив графика, для которых был указан параметр :context:. Это относится только к директивам встроенного кода, а не к тем, которые выполняются из файлов. Если указан параметр :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 применяются, когда параметр :context: не используется в директиве plot. Если задано, этот параметр конфигурации переопределяет это поведение и применяет rcParams перед каждым графиком.

plot_working_directory

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

plot_template

Предоставляет настраиваемый шаблон для подготовки restructured text.

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

exceptionmatplotlib.sphinxext.plot_directive.PlotError[source]

END_OF_DOCUMENT_MARKER

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-файлов, включённых в него с помощью директивы RST include (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)[source]

Выполните скрипт pyplot и сохраните изображения в output_dir.

Сохраните изображения в output_dir с именами файлов, полученными из output_base