Jupyter/Colab jegyzetfüzetek generálása

Az nbgenerate eszköz a DevSite HTML- és Markdown-tartalmakat és -sablonokat Colab-kompatibilis Jupyter-jegyzetfüzetekké alakítja.

Áttekintés

A Google Colab webhelyéről:

A Colab jegyzetfüzetek lehetővé teszik a futtatható kód és a formázott szöveg kombinálását egyetlen dokumentumban, valamint képeket, HTML-t, LaTeX-et és még sok mást.

A Colabban Python-kód írható és futtatható webböngészőből további beállítás vagy telepítés nélkül. A Markdown tartalom kódcellákkal tarkítható, hogy lehetővé tegye a gazdag tartalom megadását ugyanabban a dokumentumban. Emiatt a Colab-jegyzetfüzetek nemcsak a kvantitatív kutatás és a gépi tanulás, hanem az API-k és koncepciók demonstrálására és kísérletezésére is népszerű megoldássá válnak, mint amilyenek általában a fejlesztői dokumentációkban találhatók.

Emiatt a Colab-jegyzetfüzetekben megosztott tartalom gyakran átfedésben van a Google fejlesztői dokumentációjában közzétett tartalommal. Az nbgenerate eszközzel szükségtelenné válik a DevSite jelölés manuális szinkronizálása a támogató Colab-jegyzetfüzetekkel. Az eszköz a DevSite HTML-t és a Markdownt a Colab és más Jupyter-jegyzetfüzet-megvalósítások által használt .ipynb fájlformátumba konvertálja. Ez lehetővé teszi, hogy a DevSite tartalmat egyetlen igazságforrásként használják mind a fejlesztői dokumentumok, mind a Colab jegyzetfüzetek számára.

A háttér és a műszaki részletek az eredeti tervezési dokumentumban találhatók az nbgenerate-dd címen.

Alapvető használat

Ha Colab-jegyzetfüzeteket szeretne létrehozni a DevSite projekt oldalaihoz, az nbgenerate parancs meghívása előtt hozzá kell adnia egy _notebooks.yaml nevű fájlt.

A _notebooks.yaml hozzáadása a projekthez

Ha Colab-jegyzetfüzeteket szeretne létrehozni egy DevSite-projekt oldalaiból, adjon hozzá egy _notebooks.yaml nevű fájlt a projekt gyökérkönyvtárához (ugyanabban a könyvtárban, mint a webhely _project.yaml ). A fájlnak tartalmaznia kell egy bejegyzést minden Colab-jegyzetfüzetként megosztott oldalhoz. Minden bejegyzés source tartalmaznia kell a Colab-jegyzetfüzetté konvertálandó DevSite-bérlőn belüli abszolút elérési utat. A target meg kell adnia a google3 depot elérési útját, ahová a generált Colab-jegyzetfüzetek íródnak.

Például:

- 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

Ez a példa olyan célútvonalakat használ, amelyek a Copybara használatával tükröződnek a GitHubban, így a generált jegyzetfüzetek nyilvánosan elérhető hivatkozásokon keresztül nyithatók meg. Tekintse meg a copybarát a google3 útvonalak GitHubba való szinkronizálásának részleteiért. Tekintse meg a Widget-példákat is, ha olyan példákat találhat, amelyek hivatkozásokat adnak hozzá a GitHubban generált jegyzetfüzetekhez.

Jegyzetfüzetek generálása

nbgenerate első futtatása előtt határozzon meg egy álnevet .bashrc fájlban és az aktuális shellben:

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

Ezután futtathatja nbgenerate a parancssorból _notebooks.yaml fájlban felsorolt ​​összes fájl újragenerálásához:

nbgenerate googledata/devsite/content/en/PROJECT

Adjon meg egy vagy több elérési utat argumentumként nbgenerate -hez, hogy a feldolgozást a megadott fájlokra vagy útvonalakra korlátozza, például:

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

A címtár elérési utak feldolgozása rekurzív; _notebooks.yaml fájlban lévő, a megadott könyvtárban vagy az alatti fájl feldolgozásra kerül.

Ha az "Engedély megtagadva" üzenetet kapja nbgenerate futtatásakor a fenti álnévvel, akkor az eszközt a következő paranccsal is futtathatja:

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

Tartalom szűrése

Azokban az esetekben, amikor bizonyos tartalmak csak a DevSite oldalain vagy a generált Colab-jegyzetfüzetben jelennek meg, de mindkettőben nem, az is_ipynb változóval szűrheti a tartalmat, amely az nbgenerate konverziós folyamat során True értékre van állítva. Annak érdekében, hogy elkerülje a hibákat a DevSite elhelyezésekor és közzétételekor, adja hozzá a következőket azon oldalak tetejéhez, amelyeknek szelektíven tartalmazniuk kell a tartalmat:

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

Ezután a Jinja-címkék segítségével szabályozhatja, hogy mely tartalom jelenjen meg a Colabban, a DevSite-ban vagy mindkettőben. Például:

# 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 példák

A webhelyek gyakran definiálják saját DevSite moduljaikat a gyakori viselkedések beágyazása érdekében. Az alábbiakban bemutatunk néhány példát az is_ipynb változót használó modulokra, amelyek adaptálhatók az Ön webhelyéhez.

Colab jegyzetfüzet gombok widget

Az Earth Engine fejlesztői dokumentációja egyéni modult használ a Futtatás a Colabban és a Forrás megtekintése a GitHub gombokon a GitHub Colab-jegyzetfüzeteivel szinkronizált DevSite oldalain.

Minta szakasz widget

A minta szakasz widget példát ad arra, hogyan állíthat be füles szakaszokat több programozási nyelven vagy környezetben megjelenített kódrészletekhez. A widget csak a Python-kódrészletek Colab-jegyzetfüzetekbe való felvételéről gondoskodik. Ezenkívül eltávolítja a jegyzetfüzet írásakor a füles szakaszok megjelenítésére használt jelöléseket.