„Jupyter“ / „Colab“ bloknotų generavimas

nbgenerate įrankis konvertuoja DevSite HTML ir Markdown turinį ir šablonus į su Colab suderinamas Jupyter bloknotas.

Apžvalga

Iš „Google Colab“ svetainės:

Naudodami „Colab“ bloknotus galite sujungti vykdomąjį kodą ir raiškųjį tekstą viename dokumente kartu su vaizdais, HTML, LaTeX ir kt.

Programoje Colab Python kodą galima parašyti ir vykdyti iš žiniatinklio naršyklės be papildomos sąrankos ar diegimo. Pažymėjimo turinys gali būti įterpiamas su kodo langeliais, kad tame pačiame dokumente būtų galima pateikti turtingą turinį. Dėl to „Colab“ bloknotai yra populiarus sprendimas ne tik atliekant kiekybinius tyrimus ir mašininį mokymąsi, bet ir demonstruojant bei eksperimentuojant su API ir koncepcijomis, tokiomis, kokios paprastai yra kūrėjų dokumentacijoje.

Dėl šios priežasties „Colab“ užrašinėse bendrinamas turinys dažnai sutampa su turiniu, paskelbtu „Google“ kūrėjų dokumentacijoje. Įrankis „nbgenerate“ pašalina poreikį rankiniu būdu sinchronizuoti „DevSite“ žymėjimą su palaikomomis „Colab“ bloknotėmis. Įrankis konvertuoja DevSite HTML ir Markdown į .ipynb failo formatą, naudojamą Colab ir kitų Jupyter bloknotų diegimo. Tai leidžia „DevSite“ turinį naudoti kaip vieną tiesos šaltinį tiek kūrėjų dokumentams, tiek „Colab“ bloknotams.

Foną ir technines detales galite rasti originaliame dizaino dokumente adresu nbgenerate-dd .

Pagrindinis naudojimas

Norėdami sugeneruoti „Colab“ bloknotus savo „DevSite“ projekto puslapiams, prieš iškviesdami komandą nbgenerate turėsite pridėti failą pavadinimu _notebooks.yaml .

_notebooks.yaml pridėjimas prie projekto

Norėdami sugeneruoti „Colab“ bloknotus iš „DevSite“ projekto puslapių, prie projekto šaknies pridėkite failą pavadinimu _notebooks.yaml (tame pačiame kataloge kaip ir jūsų svetainės _project.yaml ). Faile turi būti vienas įrašas kiekvienam puslapiui, kuris bendrinamas kaip „Colab“ bloknotas. Kiekvieno įrašo source lauke turi būti absoliutus kelias jūsų „DevSite“ nuomininke, kad jis būtų konvertuojamas į „Colab“ bloknotą. target lauke turi būti nurodytas google3 depo kelias, kuriame bus rašomos sugeneruotos „Colab“ užrašinės.

Pavyzdžiui:

- 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

Šiame pavyzdyje naudojami tiksliniai keliai, kurie atspindimi „GitHub“ naudojant „Copybara“, kad sukurtus bloknotus būtų galima atidaryti naudojant viešai pasiekiamus hipersaitus. Daugiau informacijos apie tai, kaip sinchronizuoti „Google3“ kelius su „GitHub“, rasite „Copybara“ . Taip pat žr . valdiklių pavyzdžius , kuriuose pateikiamos nuorodos į sugeneruotas užrašų knygeles sistemoje „GitHub“.

Sąsiuvinių generavimas

Prieš paleisdami nbgenerate pirmą kartą, nustatykite slapyvardį .bashrc ir dabartiniame apvalkale:

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

Tada galite paleisti nbgenerate iš komandinės eilutės ir atkurti visus failus, išvardytus _notebooks.yaml :

nbgenerate googledata/devsite/content/en/PROJECT

Nurodykite vieną ar daugiau kelių kaip nbgenerate argumentus, kad apribotumėte nurodytų failų ar kelių apdorojimą, pavyzdžiui:

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

Katalogų keliai apdorojami rekursyviai; bus apdorojami visi failai _notebooks.yaml , esantys nurodytame kataloge arba žemiau.

Jei paleisdami nbgenerate naudodami aukščiau pateiktą slapyvardį gaunate „Leidimas uždraustas“, taip pat galite paleisti įrankį naudodami šią komandą:

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

Turinio filtravimas

Tais atvejais, kai tam tikras turinys turėtų būti rodomas tik „DevSite“ puslapiuose arba sugeneruotame „Colab“ bloknote, bet ne abiejuose, galite filtruoti turinį naudodami kintamąjį is_ipynb , kuris nbgenerate konversijos proceso metu nustatytas į True . Kad išvengtumėte klaidų statant ir paskelbiant „DevSite“, puslapių, kuriuose reikia pasirinktinai įtraukti turinį, viršuje pridėkite toliau nurodytus elementus.

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

Tada galite naudoti „Jinja“ žymas, kad galėtumėte valdyti, kuris turinys bus rodomas „Colab“, „DevSite“ ar abiejuose. Pavyzdžiui:

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

Valdiklių pavyzdžiai

Svetainės dažnai apibrėžia savo „DevSite“ valdiklius, kad apimtų įprastą elgesį. Toliau pateikiami keli valdiklių, kuriuose naudojamas kintamasis is_ipynb , pavyzdžiai, kurie gali būti pritaikyti jūsų svetainei.

„Colab“ užrašų knygelės mygtukų valdiklis

„Earth Engine“ kūrėjo dokumentacijoje naudojamas tinkintas valdiklis, kad „GitHub“ mygtukai „DevSite“ puslapiuose, sinchronizuojamuose su „Colab“ bloknotais sistemoje „GitHub“, būtų nuosekliai rodomi Vykdyti naudojant „Colab“ ir „Žiūrėti šaltinį“ .

Skilties valdiklio pavyzdys

Skilties pavyzdiniame valdiklyje pateikiamas pavyzdys, kaip nustatyti kodo fragmentų, pateiktų keliomis programavimo kalbomis arba aplinkose, skyrius su skirtukais. Valdiklis pasirūpina tik „Python“ fragmentų įtraukimu į „Colab“ bloknotus. Taip pat pašalinami žymėjimai, naudojami skyreliams su skirtukais rodyti rašant bloknotą.