Das nbgenerate-Tool konvertiert HTML- und Markdown-Inhalte und ‐Vorlagen der Google Developers-Website
in Colab-kompatible Jupyter-Notebooks.
Übersicht
Gehen Sie auf der Google Colab-Website so vor:
Mit Colab-Notebooks können Sie ausführbaren Code und Rich Text in einem einzigen Dokument zusammen mit Bildern, HTML, LaTeX und vielem mehr kombinieren.
In Colab kann Python-Code ohne zusätzliche Einrichtung oder Installation in einem Webbrowser geschrieben und ausgeführt werden. Markdown-Inhalte können durch Code unterbrochen werden -Zellen, damit Rich Content im selben Dokument bereitgestellt werden kann. Dadurch wird Colab-Notebooks sind nicht nur eine beliebte Lösung für quantitative Forschung und maschinelles Lernen, sondern auch zum Demonstrieren und Experimentieren mit APIs und Konzepten wie denen, die normalerweise in der Entwicklerdokumentation zu finden sind.
Aus diesem Grund überschneiden sich die in Colab-Notebooks freigegebenen Inhalte häufig mit Inhalten in der Google-Entwicklerdokumentation. Mit dem nbgenerate-Tool müssen Sie das DevSite-Markup nicht mehr manuell mit unterstützenden Colab-Notebooks synchronisieren. Das Tool konvertiert DevSite-HTML und Markdown in das .ipynb-Dateiformat, das von Colab und anderen Jupyter-Notebook-Implementierungen verwendet wird. Dadurch können DevSite-Inhalte verwendet werden als Single Source Of Truth sowohl für Entwicklerdokumente als auch für Colab-Notebooks.
Hintergrundinformationen und technische Details finden Sie im ursprünglichen Designdokument unter nbgenerate-dd.
Grundlegende Nutzung
Wenn Sie Colab-Notebooks für Seiten in Ihrem DevSite-Projekt generieren möchten, müssen Sie vor dem Aufrufen des Befehls nbgenerate eine Datei mit dem Namen _notebooks.yaml hinzufügen.
_notebooks.yaml Ihrem Projekt hinzufügen
Wenn Sie Colab-Notebooks aus Seiten in einem DevSite-Projekt generieren möchten, fügen Sie dem Projektstamm eine Datei namens _notebooks.yaml hinzu (im selben Verzeichnis wie die _project.yaml Ihrer Website). Die Datei sollte einen Eintrag für jede Seite enthalten, die als Colab-Notebook freigegeben wird. Das Feld source jedes Eintrags muss den absoluten Pfad innerhalb Ihres DevSite-Tenants enthalten, der in ein Colab-Notebook umgewandelt werden soll. Im Feld target muss der Google3-Depotpfad angegeben werden, in den die generierten Colab-Notebooks geschrieben werden.
Beispiel:
- source: /earth-engine/ee-image.html
target: //depot/google3/third_party/earthengine_community/ipynb/ee-image.ipynb
- source: /earth-engine/guides/image_objects.md
target: //depot/google3/third_party/earthengine_community/ipynb/guides/image_objects.ipynb
In diesem Beispiel werden Zielpfade verwendet, die mit Copybara auf GitHub gespiegelt werden, damit die generierten Notebooks über öffentlich zugängliche Hyperlinks geöffnet werden können. Weitere Informationen zum Synchronisieren von google3-Pfaden mit GitHub finden Sie unter copybara. Siehe auch Widget-Beispiele für Beispiele, die Links zu generierten Notebooks in GitHub hinzufügen.
Notebooks generieren
Bevor Sie nbgenerate zum ersten Mal ausführen, definieren Sie einen Alias in Ihrem
.bashrc und mit Ihrer aktuellen Shell:
alias nbgenerate="/google/bin/releases/devsite/tools/nbgenerate/nbgenerate.par"
Sie können dann nbgenerate über die Befehlszeile ausführen, um alle Dateien neu zu generieren
aufgeführt in _notebooks.yaml:
nbgenerate googledata/devsite/content/en/PROJECT
Geben Sie einen oder mehrere Pfade als Argumente für nbgenerate an, um die Verarbeitung auf die angegebenen Dateien oder Pfade zu beschränken, z. B.:
nbgenerate third_party/devsite/developers/en/earth-engine/guides
Verzeichnispfade werden rekursiv verarbeitet. beliebige Dateien in _notebooks.yaml unter oder
unter dem angegebenen Verzeichnis verarbeitet werden.
Wenn die Meldung „Berechtigung verweigert“ angezeigt wird wenn Sie nbgenerate mit den obigen Anweisungen ausführen
Alias verwenden, können Sie das Tool auch mit dem folgenden Befehl ausführen:
blaze run //devsite/tools/nbgenerate -- googledata/devsite/content/en/PROJECT
Inhalte filtern
Wenn einige Inhalte nur auf den DevSite-Seiten oder im generierten Colab-Notebook, aber nicht in beiden angezeigt werden sollen, können Sie Inhalte mithilfe der Variablen is_ipynb filtern. Diese wird während des nbgenerate-Konvertierungsvorgangs auf True festgelegt. Um Fehler beim Staging und Veröffentlichen auf der DevSite zu vermeiden, fügen Sie oben auf Seiten, die selektiv Inhalte enthalten müssen, Folgendes hinzu:
{% if is_ipynb is not defined %}{% set is_ipynb=False %}{% endif %}
Anschließend können Sie mithilfe von Jinja-Tags festlegen, welche Inhalte in Colab, DevSite oder in beiden angezeigt werden. Beispiel:
# Overview
This section will show in both the DevSite page and in the Colab notebook as
a text cell.
{% if is_ipynb %}
This content will only appear in Colab notebooks but not on DevSite pages. This
is useful for providing Colab-specific initialization and setup instructions or
code.
{% endif %}
{% if not is_ipynb %}
```js
// This code snippet will only be rendered in DevSite but not in Colab
// notebooks.
console.log('Hello, nbgenerate!');
```
{% endif %}
```py
# This snippet will appear in both DevSite and in the Colab notebook as a code
# cell.
print('Hello, nbgenerate!');
```
Widget-Beispiele
Websites definieren häufig eigene DevSite-Widgets, um häufige Verhaltensweisen zu erfassen. Unten findest du einige Beispiele für Widgets, die die Variable is_ipynb verwenden und an deine Website angepasst werden können.
Widget für Colab-Notebook-Schaltflächen
In der Earth Engine-Entwicklerdokumentation wird ein benutzerdefiniertes Widget verwendet, um auf DevSite-Seiten, die mit Colab-Notebooks auf GitHub synchronisiert sind, die Schaltflächen In Colab ausführen und Quellcode auf GitHub ansehen konsistent anzuzeigen.
Beispiel für ein Bereichs-Widget
Das Widget für Beispielbereiche zeigt, wie Sie Bereiche mit Tabs für Code-Snippets einrichten, die in mehreren Programmiersprachen oder Umgebungen präsentiert werden. Das Widget sorgt dafür, dass nur Python-Snippets in Colab-Notebooks eingefügt werden. Außerdem wird das Markup entfernt, das beim Erstellen des Notizbuchs zum Anzeigen der Bereichsbereiche verwendet wurde.