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.