Genererar Jupyter/Colab-anteckningsböcker

Verktyget nbgenerate konverterar DevSite HTML- och Markdown-innehåll och mallar till Colab-kompatibla Jupyter-anteckningsböcker.

Översikt

Från Google Colabs webbplats:

Med Colab-anteckningsböcker kan du kombinera körbar kod och rik text i ett enda dokument, tillsammans med bilder, HTML, LaTeX och mer.

I Colab kan Python-kod skrivas och köras från en webbläsare utan ytterligare installation eller installation. Markdown-innehåll kan varvas med kodceller för att tillåta rikt innehåll att tillhandahållas i samma dokument. Detta gör Colab-datorer till en populär lösning inte bara för kvantitativ forskning och maskininlärning utan också för att demonstrera och experimentera med API:er och koncept som de som vanligtvis finns i utvecklardokumentation.

Av denna anledning överlappar innehåll som delas i Colab-anteckningsböcker ofta innehåll som publiceras i Googles utvecklardokumentation. Verktyget nbgenerate eliminerar behovet av att manuellt synkronisera DevSite-markering med stödjande Colab-datorer. Verktyget konverterar DevSite HTML och Markdown till filformatet .ipynb som används av Colab och andra Jupyter-anteckningsbokimplementeringar. Detta gör att DevSite-innehåll kan användas som en enda källa till sanning för både utvecklardokument och Colab-anteckningsböcker.

Bakgrund och tekniska detaljer finns i det ursprungliga designdokumentet på nbgenerate-dd .

Grundläggande användning

För att generera Colab-anteckningsböcker för sidor i ditt DevSite-projekt måste du lägga till en fil som heter _notebooks.yaml innan du anropar kommandot nbgenerate .

Lägger till _notebooks.yaml till ditt projekt

För att generera Colab-anteckningsböcker från sidor i ett DevSite-projekt, lägg till en fil som heter _notebooks.yaml till projektroten (i samma katalog som din webbplats _project.yaml ). Filen bör innehålla en post för varje sida som delas som en Colab-anteckningsbok. source för varje post måste innehålla den absoluta sökvägen inom din DevSite-hyresgäst för att konverteras till en Colab-anteckningsbok. target måste ange sökvägen till google3 depå där genererade Colab-anteckningsböcker kommer att skrivas.

Till exempel:

- 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

Det här exemplet använder målsökvägar som speglas till GitHub med Copybara så att de genererade anteckningsböckerna kan öppnas via allmänt tillgängliga hyperlänkar. Se copybara för detaljer om hur man synkroniserar google3-sökvägar till GitHub. Se även Widget-exempel för exempel som lägger till länkar till genererade anteckningsböcker i GitHub.

Skapa anteckningsböcker

Innan du kör nbgenerate för första gången, definiera ett alias i din .bashrc och till ditt nuvarande skal:

alias nbgenerate="/google/bin/releases/devsite/tools/nbgenerate/nbgenerate.par"

Du kan sedan köra nbgenerate från kommandoraden för att återskapa alla filer som listas i _notebooks.yaml :

nbgenerate googledata/devsite/content/en/PROJECT

Ange en eller flera sökvägar som argument att nbgenerate för att begränsa behandlingen till de angivna filerna eller sökvägarna, till exempel:

nbgenerate third_party/devsite/developers/en/earth-engine/guides

Katalogsökvägar bearbetas rekursivt; alla filer i _notebooks.yaml vid eller under den angivna katalogen kommer att bearbetas.

Om du får "Permission denied" när du kör nbgenerate med ovanstående alias, kan du också köra verktyget med följande kommando:

blaze run //devsite/tools/nbgenerate -- googledata/devsite/content/en/PROJECT

Filtrera innehåll

I de fall där visst innehåll bara ska visas antingen på DevSite-sidor eller i den genererade Colab-anteckningsboken men inte båda, kan du filtrera innehåll med hjälp av variabeln is_ipynb , som är satt till True under nbgenerate konverteringsprocessen. För att förhindra fel vid iscensättning och publicering på DevSite, lägg till följande nära toppen av sidor som selektivt måste inkludera innehåll:

    
{% if is_ipynb is not defined %}{% set is_ipynb=False %}{% endif %}

Du kan sedan använda Jinja-taggar för att styra vilket innehåll som visas i Colab, DevSite eller båda. Till exempel:

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

Webbplatser definierar ofta sina egna DevSite-widgets för att kapsla in vanliga beteenden. Nedan finns några exempel på widgets som använder variabeln is_ipynb , som kan anpassas till din webbplats.

Colab anteckningsbok knappar widget

Earth Engine-utvecklardokumentationen använder en anpassad widget för att konsekvent visa Kör i Colab och Visa källa på GitHub- knappar på DevSite-sidor synkroniserade med Colab-anteckningsböcker i GitHub.

Exempel på sektionswidget

Exempelsektionswidgeten ger ett exempel på hur man ställer in flikar för kodavsnitt som presenteras i flera programmeringsspråk eller miljöer. Widgeten tar hand om att endast inkludera Python-snuttar i Colab-anteckningsböcker. Den tar också bort markeringar som används för att visa flikavsnitten när du skriver anteckningsboken.