Luodaan Jupyter/Colab-muistikirjoja

nbgenerate työkalu muuntaa DevSite HTML- ja Markdown-sisällön ja -mallit Colab-yhteensopiviksi Jupyter-muistikirjoiksi.

Yleiskatsaus

Google Colab -sivustolta:

Colab-muistikirjojen avulla voit yhdistää suoritettavaa koodia ja muotoiltua tekstiä yhdeksi asiakirjaksi kuvien, HTML:n, LaTeXin ja muiden kanssa.

Colabissa Python-koodi voidaan kirjoittaa ja suorittaa verkkoselaimella ilman lisäasetuksia tai asennusta. Markdown-sisältö voidaan sekoittaa koodisolujen väliin, jotta samassa asiakirjassa voidaan tarjota monipuolista sisältöä. Tämä tekee Colab-muistikirjoista suositun ratkaisun kvantitatiivisen tutkimuksen ja koneoppimisen lisäksi myös sovellusliittymien ja konseptien demonstroimiseen ja kokeiluun, kuten kehittäjien dokumentaatiossa tyypillisesti.

Tästä syystä Colab-muistikirjoissa jaettu sisältö on usein päällekkäistä Googlen kehittäjien dokumentaatiossa julkaistun sisällön kanssa. Nbgenerate-työkalun ansiosta DevSite-merkintöjä ei tarvitse synkronoida manuaalisesti tukevien Colab-muistikirjojen kanssa. Työkalu muuntaa DevSite HTML:n ja Markdownin .ipynb-tiedostomuotoon, jota Colab ja muut Jupyterin muistikirjatoteutukset käyttävät. Näin DevSite-sisältöä voidaan käyttää yhtenä totuuden lähteenä sekä kehittäjien asiakirjoissa että Colab-muistikirjoissa.

Tausta ja tekniset tiedot löytyvät alkuperäisestä suunnitteluasiakirjasta osoitteessa nbgenerate-dd .

Peruskäyttö

Jos haluat luoda Colab-muistikirjoja DevSite-projektisi sivuille, sinun on lisättävä tiedosto nimeltä _notebooks.yaml ennen nbgenerate komennon käynnistämistä.

_notebooks.yaml:n lisääminen projektiisi

Luo Colab-muistikirjoja DevSite-projektin sivuilta lisäämällä _notebooks.yaml niminen tiedosto projektin juureen (samaan hakemistoon kuin sivustosi _project.yaml ). Tiedoston tulee sisältää yksi merkintä jokaisesta Colab-muistikirjana jaettavasta sivusta. Kunkin merkinnän source on sisällettävä DevSite-vuokraajasi absoluuttinen polku, jotta se muunnetaan Colab-muistikirjaksi. target on määritettävä google3-varastopolku, johon luodut Colab-muistikirjat kirjoitetaan.

Esimerkiksi:

- 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

Tämä esimerkki käyttää kohdepolkuja, jotka peilataan GitHubiin Copybaran avulla, jotta luodut muistikirjat voidaan avata julkisesti käytettävissä olevien hyperlinkkien kautta. Katso copybara saadaksesi lisätietoja google3-polkujen synkronoinnista GitHubiin. Katso myös Widget-esimerkit esimerkkejä, jotka lisäävät linkkejä luotuihin muistikirjoihin GitHubissa.

Muistikirjojen luominen

Ennen kuin ajat nbgenerate ensimmäistä kertaa, määritä alias .bashrc tiedostoon ja nykyiseen komentotulkkiisi:

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

Voit sitten suorittaa nbgenerate komennon komentoriviltä luodaksesi uudelleen kaikki tiedostot, jotka on lueteltu kohdassa _notebooks.yaml :

nbgenerate googledata/devsite/content/en/PROJECT

Määritä yksi tai useampi polku nbgenerate -argumenteiksi, jotta käsittely rajoitetaan määritettyihin tiedostoihin tai polkuihin, esimerkiksi:

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

Hakemistopolut käsitellään rekursiivisesti; kaikki tiedostot _notebooks.yaml tiedostossa määritetyssä hakemistossa tai sen alapuolella käsitellään.

Jos saat "Permission denied" -ilmoituksen, kun suoritat nbgenerate käyttämällä yllä olevaa aliasta, voit myös suorittaa työkalun seuraavalla komennolla:

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

Sisällön suodatus

Tapauksissa, joissa osan sisällöstä pitäisi näkyä vain joko DevSite-sivuilla tai luodussa Colab-muistikirjassa, mutta ei molemmissa, voit suodattaa sisältöä käyttämällä is_ipynb muuttujaa, jonka arvoksi asetetaan True nbgenerate muunnosprosessin aikana. Estä virheet lavastuksen ja DevSite-julkaisun aikana lisäämällä seuraavat tiedot niiden sivujen yläosaan, joille on sisällytettävä sisältöä valikoivasti:

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

Voit sitten käyttää Jinja-tageja määrittääksesi, mikä sisältö näkyy Colabissa, DevSitessa tai molemmissa. Esimerkiksi:

# 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-esimerkkejä

Sivustot määrittelevät usein omat DevSite-widgetinsä yleisten toimintojen kapseloimiseksi. Alla on esimerkkejä widgeteistä, jotka käyttävät is_ipynb muuttujaa ja joita voidaan mukauttaa sivustollesi.

Colab-muistikirjan painikkeiden widget

Earth Enginen kehittäjän dokumentaatio käyttää mukautettua widgetiä Suorita Colabissa- ja Näytä lähdekoodin GitHub- painikkeiden näyttämiseen jatkuvasti DevSite-sivuilla, jotka on synkronoitu Colab-muistikirjoihin GitHubissa.

Esimerkkiosion widget

Esimerkkiosion widget tarjoaa esimerkin välilehtiosien määrittämisestä useilla ohjelmointikielillä tai -ympäristöissä esitettäville koodinpätkille. Widget huolehtii vain Python-katkelmien sisällyttämisestä Colab-muistikirjoihin. Se myös poistaa merkinnät, joita käytetään välilehtien näyttämiseen muistikirjaa kirjoitettaessa.