Generiranje Jupyter/Colab bilježnica

Alat nbgenerate pretvara sadržaj i predloške DevSite HTML i Markdown u Jupyter bilježnice kompatibilne s Colabom.

Pregled

Sa stranice Google Colab :

Colab prijenosna računala omogućuju vam kombiniranje izvršnog koda i obogaćenog teksta u jednom dokumentu, zajedno sa slikama, HTML-om, LaTeX-om i više.

U Colabu se Python kod može pisati i izvršavati iz web preglednika bez dodatnog postavljanja ili instalacije. Markdown sadržaj može biti ispresijecan ćelijama koda kako bi se omogućilo pružanje bogatog sadržaja u istom dokumentu. To Colab prijenosna računala čini popularnim rješenjem ne samo za kvantitativno istraživanje i strojno učenje, već i za demonstraciju i eksperimentiranje s API-jima i konceptima poput onih koji se obično nalaze u dokumentaciji za razvojne programere.

Iz tog se razloga sadržaj koji se dijeli u Colab bilježnicama često preklapa sa sadržajem objavljenim u Googleovoj dokumentaciji za razvojne programere. Alat nbgenerate eliminira potrebu za ručnom sinkronizacijom oznaka DevSite s podržavajućim Colab prijenosnim računalima. Alat pretvara DevSite HTML i Markdown u format datoteke .ipynb koji koriste Colab i druge implementacije prijenosnih računala Jupyter. Ovo omogućuje korištenje sadržaja DevSite kao jedinstvenog izvora istine i za dokumente razvojnih programera i za Colab bilježnice.

Pozadina i tehnički detalji mogu se pronaći u izvornom dizajn dokumentu na nbgenerate-dd .

Osnovna uporaba

Za generiranje Colab bilježnica za stranice u vašem DevSite projektu, morat ćete dodati datoteku pod nazivom _notebooks.yaml prije pozivanja naredbe nbgenerate .

Dodavanje _notebooks.yaml vašem projektu

Za generiranje Colab bilježnica sa stranica u DevSite projektu, dodajte datoteku pod nazivom _notebooks.yaml u korijen projekta (u isti direktorij kao i _project.yaml vaše web stranice). Datoteka bi trebala uključivati ​​jedan unos za svaku stranicu koja se dijeli kao Colab bilježnica. source polje svakog unosa mora sadržavati apsolutni put unutar vašeg zakupca DevSite da bi se pretvorio u Colab bilježnicu. target polje mora navesti stazu google3 depot gdje će se generirati Colab bilježnice.

Na primjer:

- 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

Ovaj primjer koristi ciljne staze koje se preslikavaju na GitHub pomoću Copybare tako da se generirane bilježnice mogu otvoriti putem javno dostupnih hiperveza. Pogledajte copybara za detalje o tome kako sinkronizirati google3 staze s GitHubom. Također pogledajte primjere widgeta za primjere koji dodaju veze na generirane bilježnice u GitHubu.

Generiranje bilježnica

Prije pokretanja nbgenerate po prvi put, definirajte pseudonim u vašem .bashrc i vašoj trenutnoj ljusci:

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

Zatim možete pokrenuti nbgenerate iz naredbenog retka za ponovno generiranje svih datoteka navedenih u _notebooks.yaml :

nbgenerate googledata/devsite/content/en/PROJECT

Navedite jednu ili više staza kao argumente za nbgenerate da ograničite obradu na navedene datoteke ili staze, na primjer:

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

Staze imenika obrađuju se rekurzivno; sve datoteke u _notebooks.yaml na ili ispod navedenog direktorija bit će obrađene.

Ako dobijete "Permission denied" kada pokrenete nbgenerate koristeći gornji alias, također možete pokrenuti alat sa sljedećom naredbom:

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

Filtriranje sadržaja

U slučajevima kada bi se neki sadržaj trebao pojaviti samo na stranicama DevSite ili u generiranoj Colab bilježnici, ali ne oboje, možete filtrirati sadržaj pomoću varijable is_ipynb , koja je postavljena na True tijekom procesa konverzije nbgenerate . Kako biste spriječili pogreške prilikom postavljanja i objavljivanja na DevSite, dodajte sljedeće pri vrhu stranica koje trebaju selektivno uključivati ​​sadržaj:

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

Tada možete koristiti Jinja oznake za kontrolu sadržaja koji se pojavljuje u Colabu, DevSiteu ili oboje. Na primjer:

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

Primjeri widgeta

Web-mjesta često definiraju vlastite widgete DevSite kako bi obuhvatila uobičajena ponašanja. Ispod su neki primjeri widgeta koji koriste varijablu is_ipynb , a koja se može prilagoditi vašoj web stranici.

Widget gumba za Colab bilježnicu

Dokumentacija za razvojne programere Earth Enginea koristi prilagođeni widget za dosljedan prikaz gumba Run in Colab i View source on GitHub na stranicama DevSite sinkroniziranim s Colab bilježnicama u GitHubu.

Uzorak widgeta odjeljka

Uzorak widgeta odjeljka pruža primjer kako postaviti odjeljke s karticama za isječke koda predstavljene u više programskih jezika ili okruženja. Widget se brine samo za uključivanje Python isječaka u Colab bilježnice. Također uklanja oznake koje se koriste za prikaz odjeljaka s karticama prilikom pisanja bilježnice.