Generovanie poznámkových blokov Jupyter/Colab

Nástroj nbgenerate konvertuje obsah a šablóny DevSite HTML a Markdown do poznámkových blokov Jupyter kompatibilných s Colab.

Prehľad

Z webu Google Colab :

Poznámkové bloky Colab vám umožňujú kombinovať spustiteľný kód a formátovaný text v jednom dokumente spolu s obrázkami, HTML, LaTeX a ďalšími.

V službe Colab možno kód jazyka Python napísať a spustiť z webového prehliadača bez ďalšieho nastavovania alebo inštalácie. Obsah označenia môže byť rozptýlený bunkami kódu, aby sa umožnilo poskytovanie bohatého obsahu v tom istom dokumente. Vďaka tomu sú notebooky Colab obľúbeným riešením nielen na kvantitatívny výskum a strojové učenie, ale aj na predvádzanie a experimentovanie s rozhraniami API a konceptmi, ktoré sa bežne vyskytujú v dokumentácii pre vývojárov.

Z tohto dôvodu sa obsah zdieľaný v zošitoch Colab často prekrýva s obsahom zverejneným v dokumentácii Google pre vývojárov. Nástroj nbgenerate eliminuje potrebu ručnej synchronizácie značiek DevSite s podporou zápisníkov Colab. Nástroj konvertuje HTML a Markdown DevSite do formátu súboru .ipynb, ktorý používa Colab a ďalšie implementácie notebookov Jupyter. To umožňuje používať obsah DevSite ako jediný zdroj pravdy pre vývojárske dokumenty aj zápisníky Colab.

Pozadie a technické detaily nájdete v originálnom dizajnovom dokumente na nbgenerate-dd .

Základné použitie

Ak chcete vygenerovať poznámkové bloky Colab pre stránky v projekte DevSite, pred vyvolaním príkazu nbgenerate budete musieť pridať súbor s názvom _notebooks.yaml .

Pridanie súboru _notebooks.yaml do vášho projektu

Ak chcete generovať zápisníky Colab zo stránok v projekte DevSite, pridajte súbor s názvom _notebooks.yaml do koreňového adresára projektu (v rovnakom adresári ako _project.yaml vašej lokality). Súbor by mal obsahovať jednu položku pre každú stránku zdieľanú ako zápisník Colab. source pole každej položky musí obsahovať absolútnu cestu v rámci vášho nájomníka DevSite, aby sa skonvertovalo na poznámkový blok Colab. target pole musí špecifikovať cestu depa google3, kam sa budú zapisovať vygenerované zápisníky Colab.

Napríklad:

- 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

Tento príklad používa cieľové cesty, ktoré sú zrkadlené na GitHub pomocou Copybara, takže vygenerované poznámkové bloky je možné otvárať prostredníctvom verejne prístupných hypertextových odkazov. Podrobnosti o tom, ako synchronizovať cesty google3 s GitHub, nájdete v časti copybara . Pozrite si tiež príklady miniaplikácií , kde nájdete príklady, ktoré pridávajú odkazy na vygenerované poznámkové bloky v GitHub.

Generovanie poznámkových blokov

Pred prvým spustením nbgenerate definujte alias vo svojom .bashrc a pre váš aktuálny shell:

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

Potom môžete spustiť nbgenerate z príkazového riadku na regeneráciu všetkých súborov uvedených v _notebooks.yaml :

nbgenerate googledata/devsite/content/en/PROJECT

Zadajte jednu alebo viac ciest ako argumenty pre nbgenerate na obmedzenie spracovania na zadané súbory alebo cesty, napríklad:

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

Adresárové cesty sa spracovávajú rekurzívne; všetky súbory v _notebooks.yaml v zadanom adresári alebo pod ním budú spracované.

Ak sa pri spustení nbgenerate pomocou vyššie uvedeného aliasu zobrazí „Povolenie odmietnuté“, môžete nástroj spustiť aj pomocou nasledujúceho príkazu:

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

Filtrovanie obsahu

V prípadoch, keď by sa nejaký obsah mal zobraziť iba na stránkach DevSite alebo vo vygenerovanom zápisníku Colab, ale nie v oboch, môžete obsah filtrovať pomocou premennej is_ipynb , ktorá je počas procesu konverzie nbgenerate nastavená na True . Ak chcete zabrániť chybám pri vytváraní a publikovaní na lokalite DevSite, pridajte do hornej časti stránok, ktoré musia selektívne zahŕňať obsah, nasledujúce:

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

Pomocou značiek Jinja potom môžete ovládať, ktorý obsah sa zobrazí na stránkach Colab, DevSite alebo oboch. Napríklad:

# 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!');
```

Príklady widgetov

Stránky často definujú svoje vlastné miniaplikácie DevSite na zapuzdrenie bežného správania. Nižšie je uvedených niekoľko príkladov miniaplikácií, ktoré používajú premennú is_ipynb , ktorá môže byť prispôsobená vašej lokalite.

Miniaplikácia tlačidiel zápisníka Colab

Dokumentácia pre vývojárov Earth Engine používa vlastnú miniaplikáciu na konzistentné zobrazovanie tlačidiel Spustiť v Colab a Zobraziť zdroj na GitHub na stránkach DevSite synchronizovaných do poznámkových blokov Colab v GitHub.

Miniaplikácia ukážkovej sekcie

Widget vzorovej sekcie poskytuje príklad, ako nastaviť sekcie s kartami pre úryvky kódu prezentované vo viacerých programovacích jazykoch alebo prostrediach. Miniaplikácia sa stará len o zahrnutie úryvkov jazyka Python do poznámkových blokov Colab. Odstraňuje tiež značky používané na zobrazenie sekcií s kartami pri písaní poznámkového bloku.