Generování poznámkových bloků Jupyter/Colab

Nástroj nbgenerate převádí obsah a šablony HTML a Markdown DevSite do poznámkových bloků Jupyter kompatibilních s Colab.

Přehled

Z webu Google Colab :

Poznámkové bloky Colab vám umožňují kombinovat spustitelný kód a formátovaný text v jediném dokumentu spolu s obrázky, HTML, LaTeXem a dalšími.

Ve službě Colab lze kód Pythonu psát a spouštět z webového prohlížeče bez dalšího nastavování nebo instalace. Obsah markdown lze proložit buňkami kódu, aby bylo možné poskytnout bohatý obsah ve stejném dokumentu. Díky tomu jsou notebooky Colab oblíbeným řešením nejen pro kvantitativní výzkum a strojové učení, ale také pro demonstraci a experimentování s rozhraními API a koncepty, které se obvykle vyskytují v dokumentaci pro vývojáře.

Z tohoto důvodu se obsah sdílený v sešitech Colab často překrývá s obsahem publikovaným v dokumentaci pro vývojáře Google. Nástroj nbgenerate eliminuje potřebu ruční synchronizace označení DevSite s podporou notebooků Colab. Nástroj převádí HTML a Markdown DevSite do formátu souboru .ipynb, který používá Colab a další implementace notebooků Jupyter. Díky tomu lze obsah webu DevSite používat jako jediný zdroj pravdy pro dokumenty pro vývojáře i notebooky Colab.

Pozadí a technické detaily lze nalézt v originálním design doc na nbgenerate-dd .

Základní použití

Chcete-li vygenerovat poznámkové bloky Colab pro stránky v projektu DevSite, musíte před vyvoláním příkazu nbgenerate přidat soubor s názvem _notebooks.yaml .

Přidání souboru _notebooks.yaml do vašeho projektu

Chcete-li vygenerovat poznámkové bloky Colab ze stránek v projektu DevSite, přidejte soubor s názvem _notebooks.yaml do kořenového adresáře projektu (ve stejném adresáři jako _project.yaml vašeho webu). Soubor by měl obsahovat jednu položku pro každou stránku sdílenou jako poznámkový blok Colab. source pole každé položky musí obsahovat absolutní cestu v rámci vašeho tenanta DevSite, která má být převedena na poznámkový blok Colab. V target poli musí být uvedena cesta k depu google3, kam budou zapsány vygenerované sešity Colab.

Napří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 příklad používá cílové cesty, které jsou zrcadleny na GitHub pomocí Copybara, takže vygenerované poznámkové bloky lze otevřít prostřednictvím veřejně přístupných hypertextových odkazů. Podrobnosti o tom, jak synchronizovat cesty google3 do GitHubu, najdete v copybara . Podívejte se také na příklady widgetů , kde najdete příklady, které přidávají odkazy na vygenerované poznámkové bloky na GitHubu.

Generování poznámkových bloků

Před prvním spuštěním nbgenerate definujte alias ve vašem .bashrc a ve vašem aktuálním shellu:

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

Poté můžete spustit nbgenerate z příkazového řádku a obnovit všechny soubory uvedené v _notebooks.yaml :

nbgenerate googledata/devsite/content/en/PROJECT

Zadejte jednu nebo více cest jako argumenty pro nbgenerate pro omezení zpracování na zadané soubory nebo cesty, například:

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

Cesty adresářů jsou zpracovávány rekurzivně; budou zpracovány všechny soubory v _notebooks.yaml v zadaném adresáři nebo pod ním.

Pokud se při spuštění nbgenerate pomocí výše uvedeného aliasu zobrazí „Oprávnění odepřeno“, můžete nástroj spustit také pomocí následujícího příkazu:

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

Filtrování obsahu

V případech, kdy by se nějaký obsah měl objevit pouze na stránkách DevSite nebo ve vygenerovaném poznámkovém bloku Colab, ale ne v obou, můžete obsah filtrovat pomocí proměnné is_ipynb , která je během procesu převodu nbgenerate nastavena na True . Chcete-li předejít chybám při vytváření a publikování na DevSite, přidejte do horní části stránek, které musí selektivně zahrnovat obsah, následující:

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

Pomocí značek Jinja pak můžete ovládat, který obsah se zobrazí ve službě Colab, na webu DevSite nebo na obou. Napří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!');
```

Příklady widgetů

Weby často definují své vlastní widgety DevSite k zapouzdření běžného chování. Níže jsou uvedeny některé příklady widgetů, které používají proměnnou is_ipynb , které mohou být přizpůsobeny vašemu webu.

Widget tlačítek sešitu Colab

Dokumentace pro vývojáře Earth Engine používá vlastní widget , který konzistentně zobrazuje tlačítka Spustit ve službě Colab a Zobrazit zdroj na GitHubu na stránkách DevSite synchronizovaných do poznámkových bloků Colab na GitHubu.

Ukázkový widget sekce

Widget ukázkové sekce poskytuje příklad, jak nastavit sekce s kartami pro úryvky kódu prezentované ve více programovacích jazycích nebo prostředích. Widget se stará pouze o zahrnutí úryvků jazyka Python do poznámkových bloků Colab. Odstraní také značky používané k zobrazení oddílů s kartami při psaní poznámkového bloku.