Ustvarjanje zvezkov Jupyter/Colab

Orodje nbgenerate pretvori vsebino in predloge DevSite HTML in Markdown v zvezke Jupyter, združljive s Colabom.

Pregled

S spletnega mesta Google Colab :

Beležnice Colab vam omogočajo združevanje izvedljive kode in obogatenega besedila v enem dokumentu, skupaj s slikami, HTML, LaTeX in še več.

V Colabu je mogoče kodo Python napisati in izvesti iz spletnega brskalnika brez dodatnih nastavitev ali namestitve. Vsebino označevanja je mogoče premešati s kodnimi celicami, da se omogoči zagotavljanje bogate vsebine v istem dokumentu. Zaradi tega so prenosni računalniki Colab priljubljena rešitev ne le za kvantitativne raziskave in strojno učenje, ampak tudi za predstavitev in eksperimentiranje z API-ji in koncepti, kot so tisti, ki jih običajno najdemo v dokumentaciji za razvijalce.

Zaradi tega se vsebina v skupni rabi v zvezkih Colab pogosto prekriva z vsebino, objavljeno v Googlovi dokumentaciji za razvijalce. Orodje nbgenerate odpravlja potrebo po ročni sinhronizaciji oznak DevSite s podpornimi zvezki Colab. Orodje pretvori HTML in Markdown DevSite v obliko datoteke .ipynb, ki jo uporabljajo Colab in druge izvedbe prenosnih računalnikov Jupyter. To omogoča, da se vsebina DevSite uporablja kot en sam vir resnice za dokumente razvijalcev in zvezke Colab.

Ozadje in tehnične podrobnosti so na voljo v izvirnem načrtovalskem dokumentu na nbgenerate-dd .

Osnovna uporaba

Če želite ustvariti zvezke Colab za strani v vašem projektu DevSite, boste morali dodati datoteko z imenom _notebooks.yaml , preden prikličete ukaz nbgenerate .

Dodajanje _notebooks.yaml vašemu projektu

Če želite ustvariti zvezke Colab iz strani v projektu DevSite, dodajte datoteko z imenom _notebooks.yaml v koren projekta (v isti imenik kot _project.yaml vašega spletnega mesta). Datoteka mora vsebovati en vnos za vsako stran, ki je v skupni rabi kot zvezek Colab. source polje vsakega vnosa mora vsebovati absolutno pot znotraj vašega najemnika DevSite, ki ga želite pretvoriti v zvezek Colab. target polje mora podati pot google3 depot, kamor bodo zapisani ustvarjeni zvezki Colab.

Na primer:

- 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

Ta primer uporablja ciljne poti, ki so zrcaljene v GitHub z uporabo Copybare, tako da je mogoče ustvarjene zvezke odpreti prek javno dostopnih hiperpovezav. Glejte copybara za podrobnosti o tem, kako sinhronizirati poti google3 z GitHubom. Oglejte si tudi primere pripomočkov za primere, ki dodajajo povezave do ustvarjenih zvezkov v GitHubu.

Ustvarjanje zvezkov

Preden prvič zaženete nbgenerate , definirajte vzdevek v vašem .bashrc in vaši trenutni lupini:

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

Nato lahko iz ukazne vrstice zaženete nbgenerate , da ponovno ustvarite vse datoteke, navedene v _notebooks.yaml :

nbgenerate googledata/devsite/content/en/PROJECT

Določite eno ali več poti kot argumente za nbgenerate , da omejite obdelavo na določene datoteke ali poti, na primer:

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

Poti imenikov se obdelujejo rekurzivno; obdelane bodo vse datoteke v _notebooks.yaml v podanem imeniku ali pod njim.

Če prejmete "Dovoljenje zavrnjeno", ko izvajate nbgenerate z zgornjim vzdevkom, lahko orodje zaženete tudi z naslednjim ukazom:

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

Filtriranje vsebine

V primerih, ko bi se morala neka vsebina pojaviti samo na straneh DevSite ali v ustvarjenem zvezku Colab, vendar ne oboje, lahko vsebino filtrirate s spremenljivko is_ipynb , ki je med postopkom pretvorbe nbgenerate nastavljena na True . Če želite preprečiti napake pri uprizarjanju in objavljanju na DevSite, na vrh strani, ki morajo selektivno vključiti vsebino, dodajte naslednje:

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

Nato lahko z oznakami Jinja nadzirate, katera vsebina se pojavi v Colabu, DevSiteu ali obeh. Na primer:

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

Primeri pripomočkov

Spletna mesta pogosto definirajo lastne gradnike DevSite, da zajamejo običajno vedenje. Spodaj je nekaj primerov pripomočkov, ki uporabljajo spremenljivko is_ipynb , ki se lahko prilagodi vašemu spletnemu mestu.

Pripomoček za gumbe zvezka Colab

Dokumentacija za razvijalce Earth Engine uporablja gradnik po meri za dosleden prikaz gumbov Zaženi v Colabu in Ogled vira na GitHubu na straneh DevSite, sinhroniziranih z zvezki Colab v GitHubu.

Vzorčni pripomoček razdelka

Gradnik vzorčnega odseka nudi primer, kako nastaviti odseke z zavihki za izrezke kode, predstavljene v več programskih jezikih ali okoljih. Pripomoček skrbi samo za vključitev izrezkov Python v zvezke Colab. Prav tako odstrani oznake, ki se uporabljajo za prikaz odsekov z zavihki med pisanjem zvezka.