Hinzufügen oder Bearbeiten von Tutorials als Jupyter Notebooks#

Im Ordner doc/source/ des SciPy-Repositorys finden Sie einige Dokumente im MyST Markdown-Format. Der Inhalt dieser Dateien wird ausgeführt, wenn die SciPy-Dokumentation erstellt wird (lokal oder in der CI), und alle durch die Ausführung generierten Ausgaben werden in den endgültigen HTML-Dateien gerendert. Darüber hinaus können sie auf der Website der SciPy-Dokumentation mithilfe der Erweiterung jupyterlite-sphinx interaktiv gestaltet werden.

Wenn Sie ein Dokument im Jupyter-Notebook-Format (eine .ipynb-Datei) haben und es als Teil der SciPy-Dokumentation einreichen möchten, gibt es zwei Möglichkeiten: Sie können es in eine MyST-Markdown-Datei konvertieren und nur mit einer .md-Datei arbeiten, oder Sie können Ihre .ipynb-Datei mit einer .md-Datei koppeln und mit beiden arbeiten. Beachten Sie, dass .ipynb-Dateien *nicht* in der SciPy-Dokumentation eingereicht werden sollten.

In diesem Dokument behandeln wir die Konvertierung in eine MyST-Markdown-Datei. Weitere Informationen zu MyST-NB, Jupytext und der Kopplung von Notebooks finden Sie auch im Tutorial zur Kopplung auf NumPy Tutorials. Für noch mehr Informationen konsultieren Sie bitte die MyST-NB-Dokumentation.

Wie man eine `.ipynb`-Datei in eine `.md`-Datei konvertiert#

Wenn Sie die .ipynb-Datei nicht beibehalten müssen und nur mit MyST Markdown arbeiten möchten, befolgen Sie die nachstehenden Schritte.

Installieren Sie das jupytext-Tool, indem Sie pip install jupytext oder conda install jupytext -c conda-forge verwenden;
Führen Sie in Ihrem Terminal jupytext notebook.ipynb --to myst aus, wobei notebook.ipynb durch die zu konvertierende Datei ersetzt werden sollte.

Die resultierende .md-Datei (im MyST-Markdown-Format) sollte nun eine Präambel ähnlich der unten stehenden enthalten, die angibt, dass ihr Inhalt bei der Erstellung der SciPy-Dokumentation ausgeführt wird.

---
jupytext:
   text_representation:
      extension: .md
      format_name: myst
      format_version: 0.13
      jupytext_version: 1.14.0
kernelspec:
   display_name: Python 3 (ipykernel)
   language: python
   name: python3
---

Diese Präambel müssen Sie nicht bearbeiten, da sie automatisch generiert wird.

Links, Formatierung und Bilder#

Beim Konvertieren eines Notebooks in eine MyST-Markdown-Datei müssen Sie möglicherweise einige Inhalte an die MyST-Markdown-Syntax anpassen.

Externe Links: MyST Markdown verwendet die Standard-Markdown-Syntax für Links. Zum Beispiel: [Linktext](https://www.example.com).
Interne Links: Für interne Querverweise, wie Links zu SciPy-Klassen oder -Funktionen, sowie für Intersphinx-Links können Sie die folgende Syntax verwenden: {Rolle}`Linktext <Referenz>`, wobei Rolle ref, class, func oder jede andere Rolle sein kann, die Sie mit reST verwenden würden. Um beispielsweise auf die Funktion scipy.stats.bartlett zu verlinken, verwenden Sie {func}`scipy.stats.bartlett`.
Formatierung: MyST Markdown unterstützt die Standard-Markdown-Formatierung wie Fettdruck, Kursivschrift und Codeblöcke. Um Text fett zu machen, können Sie beispielsweise doppelte Sternchen verwenden: **Fettdruck**. Um Text als Monospace/Code zu formatieren, können Sie *einfache* Backticks verwenden: `Code`.
Bilder: Wenn Ihr Notebook statische Bilder enthält, können Sie diese mit der folgenden Syntax in die MyST-Markdown-Datei einfügen: ![Alternativtext](Pfad/zum/Bild.png). Bilder werden normalerweise im selben Ordner wie die MyST-Markdown-Datei gespeichert, Sie können aber auch relative Pfade verwenden, um auf Bilder in anderen Ordnern zu verweisen. Beachten Sie, dass Ausgaben ausgeführter Zellen nicht in die Versionskontrolle aufgenommen werden sollten, da sie automatisch generiert werden, wenn das Notebook während der Erstellung der SciPy-Dokumentation ausgeführt wird.
Verlinkung zu MyST-Markdown-Seiten: MyST Markdown unterstützt das Hinzufügen von Link-Ankern, die verwendet werden können, um von anderen Dokumenten auf bestimmte Seiten oder Dokumentabschnitte zu verlinken. Um einen Anker zu einer Seite hinzuzufügen, fügen Sie (ankername)= an der gewünschten Stelle im zu referenzierenden Dokument hinzu. Von anderen Markdown-Seiten können Sie mit der folgenden Syntax auf diesen Anker verlinken: {ref}`ankername`. Von anderen reST-Seiten können Sie mit der folgenden Syntax auf diesen Anker verlinken: :ref:`ankername`.

Das Notebook interaktiv gestalten#

Wenn Sie die Interaktivität für Ihr Notebook aktivieren möchten, wenn es auf der Website der SciPy-Dokumentation gerendert wird, müssen Sie den folgenden Ausschnitt am Anfang der Markdown-Datei hinzufügen

```{eval-rst}
.. notebooklite:: <filename>.md
   :new_tab: True
```

wobei <Dateiname>.md durch den Namen der Datei ersetzt werden sollte, mit der Sie arbeiten. Dies erstellt eine Schaltfläche, die es Benutzern ermöglicht, das Notebook in einem neuen Tab zu öffnen und damit zu interagieren. Sehen Sie Bartlett's Test auf gleiche Varianzen (und dessen Quelle) als Beispiel.

Hinweis

Der Einfachheit halber möchten wir nicht, dass bestimmte Notebook-Zellen in der gerenderten Dokumentation sichtbar sind. Wir können sie ausblenden, indem wir "jupyterlite_sphinx_strip" zu den Tags im Metadatenbereich der entsprechenden Zelle hinzufügen. Um dies in der Markdown-Datei zu tun, fügen Sie den folgenden Ausschnitt direkt vor der Zelle ein, die Sie ausblenden möchten

+++ {"tags": ["jupyterlite_sphinx_strip"]}

Beachten Sie, dass die +++ Notation paarweise vorkommen sollte und die auszublendende Zelle umschließt.

Besuchen Sie die Dokumentation der NotebookLite-Direktive für weitere Details und Optionen.

Öffnen von MyST-Markdown-Dateien in der Jupyter-Notebook-Anwendung#

Wenn Sie das jupytext-Tool installiert haben, können Sie MyST-Markdown-.md-Dateien in der Jupyter-Notebook-Anwendung öffnen und ausführen, genau wie Sie es mit einer .ipynb-Datei tun würden.

Konvertierung von `.rst`-Dateien in MyST Markdown#

Um eine reStructuredText (.rst)-Datei in MyST Markdown (.md) zu konvertieren, können Sie die oben genannten Formatierungsanweisungen befolgen. Sie können auch Tools wie RST-to-MyST verwenden, um die Konvertierung zu automatisieren, aber bitte beachten Sie, dass möglicherweise eine Überprüfung erforderlich ist, um sicherzustellen, dass die Konvertierung korrekt ist. Insbesondere einige reStructuredText-Direktiven müssen möglicherweise in die {eval-rst} MyST-Direktive wie folgt eingekapselt werden.

Some Markdown here

```{eval-rst}
.. some_rest_directive_here::
  :some_option: some_value
```

Some more Markdown here