Mathematikunterstützung für HTML-Ausgaben in Sphinx

Hinzugefügt in Version 0.5.

Geändert in Version 1.8: Mathematikunterstützung für Nicht-HTML-Builder ist in sphinx-core integriert. Daher wird die mathbase-Erweiterung nicht mehr benötigt.

Da mathematische Notation nativ von HTML keinerlei Unterstützung erhält, bietet Sphinx mit mehreren Erweiterungen eine Mathematikunterstützung für HTML-Dokumente. Diese verwenden die reStructuredText-Mathematik-Direktive und das Rolle.

sphinx.ext.imgmath – Rendert Mathematik als Bilder

Hinzugefügt in Version 1.4.

Diese Erweiterung rendert Mathematik über LaTeX und dvipng oder dvisvgm in PNG- oder SVG-Bilder. Das bedeutet natürlich, dass der Computer, auf dem die Dokumente erstellt werden, beide Programme verfügbar haben muss.

Es gibt verschiedene Konfigurationswerte, die Sie festlegen können, um zu beeinflussen, wie die Bilder erstellt werden

imgmath_image_format
Typ:
'png' | 'svg'
Standard:
'png'

Das Ausgabeformat des Bildes. Es sollte entweder 'png' oder 'svg' sein. Das Bild wird erzeugt, indem zunächst latex auf die TeX-Mathematik-Markup angewendet wird und dann (abhängig vom angeforderten Format) entweder dvipng oder dvisvgm.

imgmath_use_preview
Typ:
bool
Standard:
False

dvipng und dvisvgm haben beide die Fähigkeit, die "Tiefe" der gerenderten Mathematik aus LaTeX zu erfassen: Ein Inline-Bild sollte diese "Tiefe" in einem vertical-align Stil verwenden, um korrekt mit umgebendem Text ausgerichtet zu werden.

Dieser Mechanismus erfordert das LaTeX-Vorschau-Paket (verfügbar als preview-latex-style unter Ubuntu xenial). Daher ist der Standardwert für diese Option False, aber es wird dringend empfohlen, ihn auf True zu setzen.

Geändert in Version 2.2: Diese Option kann mit dem 'svg' imgmath_image_format verwendet werden.

imgmath_add_tooltips
Typ:
bool
Standard:
True

Wenn falsch, wird der LaTeX-Code nicht als "alt"-Attribut für mathematische Bilder hinzugefügt.

imgmath_font_size
Typ:
int
Standard:
12

Die Schriftgröße (in pt) der angezeigten Mathematik. Dies muss eine positive Ganzzahl sein.

imgmath_latex
Typ:
str
Standard:
'latex'

Der Befehlsname, mit dem LaTeX aufgerufen wird. Möglicherweise müssen Sie diesen auf einen vollständigen Pfad setzen, wenn latex nicht im ausführbaren Suchpfad enthalten ist.

Da diese Einstellung nicht systemübergreifend portierbar ist, ist es normalerweise nicht sinnvoll, sie in conf.py zu setzen; stattdessen ist es besser, sie auf der sphinx-build Kommandozeile über die -D Option anzugeben, wie hier:

sphinx-build -M html -D imgmath_latex=C:\tex\latex.exe . _build

Dieser Wert sollte nur den Pfad zur LaTeX-Ausführbaren Datei enthalten, keine weiteren Argumente; verwenden Sie stattdessen imgmath_latex_args dafür.

Hinweis

Um OpenType-Schriftarten für Mathematik mit unicode-math über eine benutzerdefinierte imgmath_latex_preamble zu verwenden, können Sie imgmath_latex auf 'dvilualatex' setzen, müssen dann aber imgmath_image_format auf 'svg' setzen. Hinweis: Dies wurde nur mit dvisvgm 3.0.3 getestet. Es erhöht die Dauer der Bilderstellung erheblich im Vergleich zur Verwendung von Standard 'latex' mit traditionellen TeX-Mathematikschriften.

Hinweis

Manche schicke LaTeX-Markup (ein Beispiel wurde berichtet, das TikZ verwendete, um Gleichungen mit verschiedenen Verzierungen zu versehen) erfordern mehrere Durchläufe der LaTeX-Ausführbaren. Um dies zu handhaben, setzen Sie diese Konfigurationseinstellung auf 'latexmk' (oder einen vollständigen Pfad dazu), da dieses Perl-Skript zuverlässig dynamisch wählt, wie viele LaTeX-Durchläufe benötigt werden.

Geändert in Version 6.2.0: Die Verwendung von 'xelatex' (oder eines vollständigen Pfads dazu) wird nun unterstützt. Sie müssen dann jedoch '-no-pdf' zur Liste der Befehlsoptionen von imgmath_latex_args hinzufügen. Das 'svg' imgmath_image_format ist erforderlich. Außerdem benötigen Sie möglicherweise die dvisvgm Binärdatei relativ neu (Tests wurden nur mit Version 3.0.3 durchgeführt).

Hinweis

Bezüglich der vorherigen Anmerkung: Die Verwendung von latexmk mit der Option -xelatex wird derzeit nicht unterstützt.

imgmath_latex_args
Typ:
Sequenz[str]
Standard:
()

Zusätzliche Argumente für latex, als Liste.

imgmath_latex_preamble
Typ:
str
Standard:
''

Zusätzlicher LaTeX-Code, der in die Präambel der LaTeX-Dateien eingefügt werden soll, die zur Übersetzung der mathematischen Snippets verwendet werden. Verwenden Sie ihn z.B., um Pakete hinzuzufügen, die die für Mathematik verwendeten Schriftarten modifizieren, wie '\\usepackage{newtxsf}' für serifenlose Schriftarten oder '\\usepackage{fouriernc}' für Serifenschriften. Tatsächlich haben die standardmäßigen LaTeX-Mathematikschriften eher dünne Glyphen, die (in HTML-Ausgabe) oft nicht gut zur Textschriftart passen.

imgmath_dvipng
Typ:
str
Standard:
'dvipng'

Der Befehlsname zum Aufrufen von dvipng. Möglicherweise müssen Sie diesen auf einen vollständigen Pfad setzen, wenn dvipng nicht im ausführbaren Suchpfad enthalten ist. Diese Option wird nur verwendet, wenn imgmath_image_format auf 'png' gesetzt ist.

imgmath_dvipng_args
Typ:
Sequenz[str]
Standard:
('-gamma', '1.5', '-D', '110', '-bg', 'Transparent')

Zusätzliche Argumente für dvipng, als Liste. Der Standardwert macht das Bild etwas dunkler und größer als standardmäßig (dies gleicht teilweise die Dünnheit der Standard-LaTeX-Mathematikschriften aus) und erzeugt PNGs mit transparentem Hintergrund. Diese Option wird nur verwendet, wenn imgmath_image_format 'png' ist.

imgmath_dvisvgm
Typ:
str
Standard:
'dvisvgm'

Der Befehlsname zum Aufrufen von dvisvgm. Möglicherweise müssen Sie diesen auf einen vollständigen Pfad setzen, wenn dvisvgm nicht im ausführbaren Suchpfad enthalten ist. Diese Option wird nur verwendet, wenn imgmath_image_format auf 'svg' gesetzt ist.

imgmath_dvisvgm_args
Typ:
Sequenz[str]
Standard:
('--no-fonts',)

Zusätzliche Argumente für dvisvgm, als Liste. Der Standardwert bedeutet, dass dvisvgm Glyphen als Pfadelemente rendert (siehe dvisvgm FAQ). Diese Option wird nur verwendet, wenn imgmath_image_format 'svg' ist.

imgmath_embed
Typ:
bool
Standard:
False

Wenn wahr, werden LaTeX-Ausgabebilder innerhalb von HTML-Dateien (base64-kodiert) eingebettet und keine separaten PNG/SVG-Dateien auf der Festplatte gespeichert.

Hinzugefügt in Version 5.2.

sphinx.ext.mathjax – Rendert Mathematik über JavaScript

Aufmerksamkeit

Die Standardversion von MathJax änderte sich von Version 2 auf Version 3 in Sphinx 4.0 und von Version 3 auf Version 4 in Sphinx 9.0.

Möglicherweise müssen Sie mathjax_path überschreiben, um eine ältere Version zu laden, oder Ihre Konfigurationsoptionen aktualisieren. Im Allgemeinen sind MathJax v3- und v4-Optionen kompatibel.

Hinzugefügt in Version 1.1.

Diese Erweiterung fügt Mathematik "wie sie ist" in die HTML-Dateien ein. Das JavaScript-Paket MathJax wird dann geladen und wandelt die LaTeX-Markup live im Browser in lesbare Mathematik um.

Da MathJax (und die benötigten Schriftarten) sehr groß sind, ist es nicht in Sphinx enthalten, sondern so eingestellt, dass es automatisch von einer Drittanbieterseite geladen wird.

Aufmerksamkeit

Sie sollten die Mathematik-Direktive und Rolle verwenden und nicht die nativen MathJax $$, \(, etc.

Tipp

MathJax-Konfiguration kann in einer JavaScript-Datei bereitgestellt werden, indem die Option mathjax_config_path verwendet wird. Dies ist nützlich für komplexere Konfigurationen, die schwer nur mit einem Python-Dictionary auszudrücken sind, z. B. JavaScript-Funktionen.

mathjax_path
Typ:
str
Standard:
'https://cdn.jsdelivr.net/npm/mathjax@4/tex-mml-chtml.js'

Der Pfad zur JavaScript-Datei, die in die HTML-Dateien aufgenommen werden soll, um MathJax zu laden.

Der Standard ist die https:// URL, die die JS-Dateien vom jsdelivr Content Delivery Network lädt. Siehe die MathJax Getting Started Seite für Details. Wenn Sie MathJax offline oder ohne Einbindung von Ressourcen von einem Drittanbieter verfügbar haben möchten, müssen Sie es herunterladen und diesen Wert auf einen anderen Pfad setzen.

Der Pfad kann absolut oder relativ sein; wenn er relativ ist, bezieht er sich auf das Verzeichnis _static der erstellten Dokumentation.

Wenn Sie beispielsweise MathJax in den statischen Pfad der Sphinx-Dokumentation legen, wäre dieser Wert MathJax/MathJax.js. Wenn Sie mehr als eine Sphinx-Dokumentationssammlung auf einem Server hosten, ist es ratsam, MathJax an einem gemeinsamen Speicherort zu installieren.

Sie können auch eine vollständige https:// URL angeben, die von der CDN-URL abweicht.

Geändert in Version 4.0: Die Standardversion von MathJax ist nun Version 3. Um MathJax v2 weiter verwenden zu können, müssen Sie es explizit über diese Option laden. Zum Beispiel

mathjax_path = 'https://cdn.jsdelivr.net/npm/mathjax@2/MathJax.js?config=TeX-AMS-MML_HTMLorMML'

Geändert in Version 9.0: Die Standardversion von MathJax ist nun Version 4. Um MathJax v3 weiter verwenden zu können, müssen Sie es explizit über diese Option laden. Zum Beispiel

mathjax_path = 'https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js'
mathjax_options
Typ:
dict[str, Any]
Standard:
{}

Die Optionen für das Script-Tag für MathJax. Sie können zum Beispiel die Integritätsoption mit der folgenden Einstellung festlegen

mathjax_options = {
    'integrity': 'sha384-......',
}

Hinzugefügt in Version 1.8.

Geändert in Version 4.4.1: Ermöglicht die Änderung der Ladeart (async oder defer) von MathJax, wenn der Schlüssel "async" oder "defer" gesetzt ist.

mathjax4_config
Typ:
dict[str, Any] | None
Standard:
None

Die Konfigurationsoptionen für MathJax v4 (welches standardmäßig verwendet wird). Das angegebene Dictionary wird der JavaScript-Variable window.MathJax zugewiesen. Weitere Informationen finden Sie unter Configuring MathJax.

Hilfe bei der Konvertierung Ihrer alten MathJax-Konfiguration in die neue mathjax4_config finden Sie unter Converting your old Configuration to v4.

Hinzugefügt in Version 9.0.

mathjax3_config
Typ:
dict[str, Any] | None
Standard:
None

Die Konfigurationsoptionen für MathJax v3 (das über mathjax_path geladen werden kann). Falls angegeben, wird das Dictionary in ein JSON-Objekt konvertiert und der JavaScript-Variable window.MathJax zugewiesen.

Weitere Informationen finden Sie unter Configuring MathJax.

Hinzugefügt in Version 4.0.

mathjax2_config
Typ:
dict[str, Any] | None
Standard:
None

Die Konfigurationsoptionen für MathJax v2 (das über mathjax_path geladen werden kann). Der Wert wird als Parameter von MathJax.Hub.Config() verwendet. Weitere Informationen finden Sie unter Using in-line configuration options.

Zum Beispiel

mathjax2_config = {
    'extensions': ['tex2jax.js'],
    'jax': ['input/TeX', 'output/HTML-CSS'],
}

Hilfe bei der Konvertierung Ihrer alten MathJax-Konfiguration in die neue mathjax3_config finden Sie unter Converting Your v2 Configuration to v3.

Hinzugefügt in Version 4.0: mathjax_config wurde in mathjax2_config umbenannt.

mathjax_config
Typ:
dict[str, Any] | None
Standard:
None

Alter Name von mathjax2_config.

Hinzugefügt in Version 1.8.

Geändert in Version 4.0: Dies wurde in mathjax2_config umbenannt. mathjax_config wird aus Kompatibilitätsgründen weiterhin unterstützt.

mathjax_config_path
Typ:
str
Standard:
''

Falls angegeben, muss dies der Pfad zu einer JavaScript-Datei (.js) sein (Pfad relativ zum Konfigurationsverzeichnis), die die Konfigurationsoptionen für MathJax enthält. Beispiel

mathjax_config_path = 'mathjax-config.js'

Wichtig

Der Benutzer ist dafür verantwortlich, sicherzustellen, dass die angegebene Datei mit der verwendeten MathJax-Version kompatibel ist.

Weitere Informationen finden Sie unter Configuring MathJax.

Hinzugefügt in Version 9.0.

sphinxcontrib.jsmath – Rendert Mathematik über JavaScript

Diese Erweiterung funktioniert genauso wie die MathJax-Erweiterung, verwendet aber das ältere Paket jsMath. jsMath wird nicht mehr aktiv entwickelt, hat aber den Vorteil, dass die Größe des JavaScript-Pakets viel kleiner ist als bei MathJax.

Hinzugefügt in Version 0.5: Die Erweiterung sphinx.ext.jsmath.

Geändert in Version 2.0: sphinx.ext.jsmath wurde nach sphinxcontrib.jsmath verschoben.

Entfernt in Version 4.0: Der Alias von sphinx.ext.jsmath zu sphinxcontrib.jsmath.

Konfigurationswert

jsmath_path
Typ:
str
Standard:
''

Der Pfad zur JavaScript-Datei, die in die HTML-Dateien aufgenommen werden soll, um JSMath zu laden.

Der Pfad kann absolut oder relativ sein; wenn er relativ ist, bezieht er sich auf das Verzeichnis _static der erstellten Dokumentation.

Wenn Sie beispielsweise jsMath in den statischen Pfad der Sphinx-Dokumentation legen, wäre dieser Wert jsMath/easy/load.js. Wenn Sie mehr als eine Sphinx-Dokumentationssammlung auf einem Server hosten, ist es ratsam, jsMath an einem gemeinsamen Speicherort zu installieren.