nbsphinx
¶
nbsphinx ist eine Sphinx-Erweiterung, die einen Parser für *.ipynb
-Dateien
bereitstellt: Jupyter Notebook-Code-Zellen werden sowohl in der HTML- wie auch
in der LaTeX-Ausgabe angezeigt. Notebooks ohne gespeicherte Ausgabezellen werden
automatisch während des Sphinx-Build-Prozesses erstellt.
Installation¶
$ pipenv install sphinx nbsphinx
Requirements¶
Konfiguration¶
Sphinx konfigurieren¶
Erstellen einer Dokumentation mit Sphinx:
$ pipenv run python -m sphinx.cmd.quickstart
Danach befindet sich im neu erstellten Verzeichnis die Sphinx-Konfigurationsdatei
conf.py
. In dieser wirdnbsphinx
als Erweiterung hinzugefügt und generierte Notebooks ausgeschlossen:extensions = [ "...", "nbsphinx", ] ... exclude_patterns = [ "...", "**/.ipynb_checkpoints", ]
Ein Beispiel findet ihr in der
/conf.py
-Datei dieses Jupyter-Tutorials.
Ihr könnt noch weitere Konfigurationen für nbsphinx
vornehmen.
- Timeout
In der Standardeinstellung von
nbsphinx
ist der Timeout für eine Zelle auf 30 Sekunden eingestellt. Ihr könnt dies für euer Sphinx-Projekt in derconf.py
-Datei ändern mitnbsphinx_timeout = 60
.Alternativ könnt ihr dies auch für einzelne Code-Zellen in den Metadaten der Code-Zelle angeben:
{ "cells": [ { "cell_type": "markdown", "nbsphinx": { "timeout": 60 }, } ], }
Soll das Timeout deaktiviert werden, kann
-1
angegeben werden.- Benutzerdefinierte Formate
Bibliotheken wie z.B. jupytext speichern Notebooks in anderen Formaten ab, z.B. als R-Markdown mit dem Suffix
Rmd
. Damit diese vonnbsphinx
ebenfalls ausgeführt werden können, können in der Sphinx-Konfigurationsdateiconf.py
mitnbsphinx_custom_formats
weitere Formate angegeben werden, z.B.import jupytext nbsphinx_custom_formats = { ".Rmd": lambda s: jupytext.reads(s, ".Rmd"), }
Zellen konfigurieren¶
- Zelle nicht anzeigen
{ "cells": [ { "cell_type": "markdown", "metadata": { "nbsphinx": "hidden" }, } ], }
nbsphinx-toctree
Mit dieser Anweisung könnt ihr innerhalb einer Notebook-Zelle von Sphinx ein Inhaltsverzeichnis erstellen lassen, z.B.
{ "cells": [ { "cell_type": "markdown", "metadata": { "nbsphinx-toctree": { "maxdepth": 2 } "source": [ "Der folgende Titel wird als ``toctree caption`` gerendert.\n", "\n", "## Inhalt\n", "\n", "[Ein Notebook](ein-notebook.ipynb)\n", "\n", "[Ein externer HTML-Link](https://jupyter-tutorial.readthedocs.io/)\n", ] }, } ], }
Weitere Optionen findet ihr in der
Sphinx-Dokumentation
.
Build¶
Nun könnt ihr im Inhaltsverzeichnis eurer
index.rst
-Datei eure*.ipynb
-Datei hinzufügen, siehe z.B. jupyter-tutorial/notebook/testing/index.rst.Schließlich könnt ihr die Seiten generieren, z.B. HTML mit
$ pipenv run python -m sphinx SOURCE_DIR BUILD_DIR
oder$ pipenv run python -m sphinx SOURCE_DIR BUILD_DIR -j NUMBER_OF_PROCESSES
.wobei
-j
die Zahl der Prozesse angibt, die parallel ausgeführt werden sollen.Wenn ihr eine LaTeX-Datei erzeugen wollt, könnt ihr dies mit
$ pipenv run python -m sphinx SOURCE_DIR BUILD_DIR -b latex}
.Alternativ könnt ihr euch mit
sphinx-autobuild
die Dokumentation auch automatisch generieren lassen. Es kann installiert werden mit$ pipenv run python -m pip install sphinx-autobuild
Anschließend kann die automatische Erstellung gestartet werden mit
$ pipenv run python -m sphinx_autobuild SOURCE_DIR BUILD_DIR
.Dadurch wird ein lokaler Webserver gestartet, der die generierten HTML-Seiten unter
http://localhost:8000/
bereitstellt. Und jedes Mal, wenn ihr Änderungen in der Sphinx-Dokumentation speichert, werden die entsprechenden HTML-Seiten neu generiert und die Browseransicht aktualisiert.Ihr könnt dies auch nutzen, um die LaTeX-Ausgabe automatisch zu erstellen:
$ pipenv run python -m sphinx_autobuild SOURCE_DIR BUILD_DIR -b latex
.Eine andere Alternative ist die Publikation auf readthedocs.org.
Hierfür müsst ihr zunächst ein Konto unter https://about.readthedocs.com erstellen und dann euer GitLab-, Github- oder Bitbucket-Konto verbinden.
Markdown-Zellen¶
- Gleichungen
Gleichungen können inline zwischen
$
-Zeichen angegeben werden, z.B.$\text{e}^{i\pi} = -1$
Und auch zeilenweise können Gleichungen ausgedrückt werden z.B.
\begin{equation} \int\limits_{-\infty}^\infty f(x) \delta(x - x_0) dx = f(x_0) \end{equation}
Siehe auch
- Zitate
nbsphinx
unterstützt dieselbe Syntax für Zitate wie nbconvert:<cite data-cite="kluyver2016jupyter">Kluyver et al. (2016)</cite>
- Alarmierungsboxen
<div class="alert alert-block alert-info"> **Note** This is a notice! </div> <div class="alert alert-block alert-success"> **Success** This is a success notice! </div> <div class="alert alert-block alert-warning"> **Warning** This is a warning! </div> <div class="alert alert-block alert-danger"> **Danger** This is a danger notice!
- Links zu anderen Notebooks
a link to a notebook in a subdirectory](subdir/notebook-in-a-subdir.ipynb)
- Links zu
*.rst
-Dateien [reStructuredText file](rst-file.rst)
- Links zu lokalen Dateien
[Pipfile](Pipfile)
Code-Zellen¶
- Javascript
Für das generierte HTML kann Javascript verwendet werden, z.B.:
%%javascript var text = document.createTextNode("Hello, I was generated with JavaScript!"); // Content appended to "element" will be visible in the output area: element.appendChild(text);
Galerien¶
nbsphinx bietet Unterstützung für die Erstellung von Thumbnail-Galerien aus einer Liste von Jupyter-Notebooks. Diese Funktionalität basiert auf Sphinx-Gallery und erweitert diese, um mit Jupyter-Notebooks statt mit Python-Skripten zu arbeiten.
Sphinx-Gallery unterstützt auch direkt Matplotlib, seaborn und Mayavi.
Installation¶
Sphinx-Gallery lässt sich für Sphinx ≥ 1.8.3 installieren mit
$ pipenv install sphinx-gallery
Konfiguration¶
Damit Sphinx-Gallery genutzt werden kann, muss sie zudem noch in die conf.py
eingetragen werden:
extensions = [
"nbsphinx",
"sphinx_gallery.load_style",
]
Anschließend könnt ihr Sphinx-Gallery auf zwei verschiedene Arten nutzen:
Mit der reStructuredText-Direktive
.. nbgallery::
.Siehe auch
In einem Jupyter-Notizbuch, indem ein
nbsphinx-gallery
-Tag zu den Metadaten einer Zelle hinzugefügt wird:{ "tags": [ "nbsphinx-gallery" ] }