matplotlib.sphinxext.plot_directive#

Eine Direktive zur Einbindung eines Matplotlib-Plots in ein Sphinx-Dokument#

Dies ist eine Sphinx-Erweiterung, die eine reStructuredText-Direktive .. plot:: zum Einbinden eines Plots in ein Sphinx-Dokument bereitstellt.

In der HTML-Ausgabe bindet .. plot:: eine .png-Datei mit einem Link zu einer hochauflösenden .png und .pdf ein. In der LaTeX-Ausgabe wird eine .pdf eingebunden.

Der Plot-Inhalt kann auf drei Arten definiert werden:

  1. Ein Pfad zu einer Quelldatei als Argument der Direktive

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

    Wenn ein Pfad zu einer Quelldatei angegeben wird, kann der Inhalt der Direktive optional eine Bildunterschrift für den Plot enthalten.

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

   The plot caption.

    Zusätzlich kann der Name einer Funktion angegeben werden, die nach dem Importieren des Moduls (ohne Argumente) aufgerufen werden soll.

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

  2. Eingebunden als Inline-Inhalt zur Direktive

    .. plot::

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

  3. Unter Verwendung der doctest-Syntax

    .. plot::

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

Optionen#

Die Direktive .. plot:: unterstützt die folgenden Optionen:

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

Das Format der Eingabe. Wenn nicht gesetzt, wird das Format automatisch erkannt.

:include-source:bool

Ob der Quellcode angezeigt werden soll. Der Standardwert kann über die Variable plot_include_source in conf.py geändert werden (Standardwert ist False).

:show-source-link:bool

Ob ein Link zur Quelle in HTML angezeigt werden soll. Der Standardwert kann über die Variable plot_html_show_source_link in conf.py geändert werden (Standardwert ist True).

:context:bool or str

Wenn angegeben, wird der Code im Kontext aller vorherigen Plot-Direktiven ausgeführt, für die die Option :context: angegeben wurde. Dies gilt nur für Inline-Code-Plot-Direktiven, nicht für solche, die aus Dateien ausgeführt werden. Wenn die Option :context: reset angegeben wird, wird der Kontext für diese und zukünftige Plots zurückgesetzt und vorherige Abbildungen werden geschlossen, bevor der Code ausgeführt wird. :context: close-figs behält den Kontext bei, schließt aber vorherige Abbildungen, bevor der Code ausgeführt wird.

:nofigs:bool

Wenn angegeben, wird der Codeblock ausgeführt, aber keine Abbildungen werden eingefügt. Dies ist normalerweise nützlich in Verbindung mit der Option :context:.

:caption:str

Wenn angegeben, wird das Argument der Option als Bildunterschrift für die Abbildung verwendet. Dies überschreibt die im Inhalt angegebene Bildunterschrift, wenn der Plot aus einer Datei generiert wird.

Zusätzlich unterstützt diese Direktive alle Optionen der image directive, außer :target: (da plot seinen eigenen Target hinzufügen wird). Dazu gehören :alt:, :height:, :width:, :scale:, :align: und :class:.

Konfigurationsoptionen#

Die Plot-Direktive hat die folgenden Konfigurationsoptionen:

plot_include_source

Standardwert für die Option include-source (Standard: False).

plot_html_show_source_link

Ob ein Link zur Quelle in HTML angezeigt werden soll (Standard: True).

plot_pre_code

Code, der vor jedem Plot ausgeführt werden soll. Wenn None (Standard), wird er standardmäßig auf einen String gesetzt, der

import numpy as np
from matplotlib import pyplot as plt
plot_basedir

Basisverzeichnis, relativ zu dem die Dateinamen für plot:: sind. Wenn None oder leer (Standard), sind Dateinamen relativ zu dem Verzeichnis, in dem sich die Datei mit der Direktive befindet.

plot_formats

Zu generierende Dateiformate (Standard: ['png', 'hires.png', 'pdf']). Liste von Tupeln oder Strings,

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

die das Dateiformat und die DPI bestimmen. Für Einträge, bei denen die DPI weggelassen wurde, werden sinnvolle Standardwerte gewählt. Bei der Übergabe von der Kommandozeile über sphinx_build sollte die Liste als suffix:dpi,suffix:dpi, ... übergeben werden.

plot_html_show_formats

Ob Links zu den Dateien in HTML angezeigt werden sollen (Standard: True).

plot_rcparams

Ein Dictionary, das nicht standardmäßige rcParams enthält, die vor jedem Plot angewendet werden sollen (Standard: {}).

plot_apply_rcparams

Standardmäßig werden rcParams angewendet, wenn die Option :context: in einer Plot-Direktive nicht verwendet wird. Wenn gesetzt, überschreibt diese Konfigurationsoption dieses Verhalten und wendet rcParams vor jedem Plot an.

plot_working_directory

Standardmäßig wird das Arbeitsverzeichnis in das Verzeichnis des Beispiels geändert, sodass der Code auf seine Datendateien zugreifen kann, falls vorhanden. Außerdem wird sein Pfad zu sys.path hinzugefügt, sodass er alle nebenliegenden Hilfsmodule importieren kann. Diese Konfigurationsoption kann verwendet werden, um ein zentrales Verzeichnis (das ebenfalls zu sys.path hinzugefügt wird) anzugeben, in dem sich Datendateien und Hilfsmodule für den gesamten Code befinden.

plot_template

Bereitstellung einer benutzerdefinierten Vorlage zur Vorbereitung von restructured text.

plot_srcset

Ermöglicht die srcset-Bildoption für reaktionsfähige Bildauflösungen. Liste von Strings mit den multiplikativen Faktoren gefolgt von einem "x". z.B. ["2.0x", "1.5x"]. "2.0x" erstellt ein PNG mit der Standard-"png"-Auflösung aus plot_formats, multipliziert mit 2. Wenn plot_srcset angegeben ist, verwendet die plot-Direktive die matplotlib.sphinxext.figmpl_directive (anstelle der üblichen figure directive) in der generierten rst-Datei. Die Option plot_srcset ist inkompatibel mit singlehtml-Builds, und es wird ein Fehler ausgelöst.

Hinweise zur Funktionsweise#

Die Plot-Direktive führt den ihr übergebenen Code aus, entweder aus der Quelldatei oder den Code unter der Direktive. Die erstellte Abbildung (falls vorhanden) wird im Sphinx-Build-Verzeichnis unter einem Unterverzeichnis namens plot_directive gespeichert. Anschließend wird eine Zwischen-rst-Datei erstellt, die eine .. figure:-Direktive (oder .. figmpl::-Direktive, wenn plot_srcset verwendet wird) aufruft und Links zu den *.png-Dateien im Verzeichnis plot_directive enthält. Diese Übersetzungen können durch Änderung von plot_template angepasst werden. Siehe die Quelle von matplotlib.sphinxext.plot_directive für die in TEMPLATE und TEMPLATE_SRCSET definierten Vorlagen.

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

Die Direktive .. plot::, wie in der Docstring des Moduls dokumentiert.

final_argument_whitespace = False#

Darf das letzte Argument Leerzeichen enthalten?

has_content = True#

Darf die Direktive Inhalt haben?

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

Zuordnung von Optionsnamen zu Validatorfunktionen.

optional_arguments = 2#

Anzahl der optionalen Argumente nach den erforderlichen Argumenten.

required_arguments = 0#

Anzahl der erforderlichen Direktivenargumente.

run()[source]#

Führt die plot-Direktive aus.

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

Damit Plots referenzierbar sind, müssen wir die Referenz von dem "htmlonly" (oder "latexonly") Knoten auf den eigentlichen Abbildungsknoten selbst verschieben.

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

Gibt zurück, ob derived im Vergleich zu original oder einer der in diese enthaltenen RST-Dateien mittels der RST include-Direktive (includes) veraltet ist. derived und original sind vollständige Pfade, und includes ist optional eine Liste von vollständigen Pfaden, die möglicherweise in original enthalten waren.

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

Führt ein pyplot-Skript aus und speichert die Bilder in output_dir.

Speichert die Bilder unter output_dir mit Dateinamen, die von output_base abgeleitet sind.

Auf dieser Seite