Denne siden er oversatt av Cloud Translation API.

Generering av Jupyter/Colab-notatbøker

nbgenerate verktøyet konverterer DevSite HTML- og Markdown-innhold og maler til Colab-kompatible Jupyter-notatbøker.

Oversikt

Colab-notatbøker lar deg kombinere kjørbar kode og rik tekst i ett enkelt dokument, sammen med bilder, HTML, LaTeX og mer.

I Colab kan Python-kode skrives og kjøres fra en nettleser uten ytterligere oppsett eller installasjon. Markdown-innhold kan blandes med kodeceller for å tillate rikt innhold å gis i samme dokument. Dette gjør Colab-notebooks til en populær løsning, ikke bare for kvantitativ forskning og maskinlæring, men også for å demonstrere og eksperimentere med APIer og konsepter som de som vanligvis finnes i utviklerdokumentasjon.

Av denne grunn overlapper innhold som deles i Colab-notatbøker ofte med innhold publisert i Googles utviklerdokumentasjon. nbgenerate-verktøyet eliminerer behovet for å manuelt synkronisere DevSite-markering med støttende Colab-notatbøker. Verktøyet konverterer DevSite HTML og Markdown til .ipynb-filformatet som brukes av Colab og andre Jupyter bærbare implementeringer. Dette gjør at DevSite-innhold kan brukes som en enkelt kilde til sannhet for både utviklerdokumenter og Colab-notatbøker.

Bakgrunn og tekniske detaljer finnes i det originale designdokumentet på nbgenerate-dd .

Grunnleggende bruk

For å generere Colab-notatbøker for sider i DevSite-prosjektet ditt, må du legge til en fil kalt _notebooks.yaml før du starter kommandoen nbgenerate .

Legger til _notebooks.yaml til prosjektet ditt

For å generere Colab-notatbøker fra sider i et DevSite-prosjekt, legg til en fil kalt _notebooks.yaml til prosjektroten (i samme katalog som nettstedets _project.yaml ). Filen skal inneholde én oppføring for hver side som deles som en Colab-notatbok. source til hver oppføring må inneholde den absolutte banen i DevSite-leietakeren din for å bli konvertert til en Colab-notatbok. target må spesifisere google3-depotbanen der genererte Colab-notatbøker vil bli skrevet.

For eksempel:

- 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

Dette eksemplet bruker målstier som speiles til GitHub ved hjelp av Copybara slik at de genererte notatbøkene kan åpnes via offentlig tilgjengelige hyperkoblinger. Se copybara for detaljer om hvordan du synkroniserer google3-baner til GitHub. Se også Widget-eksempler for eksempler som legger til lenker til genererte notatbøker i GitHub.

Generer notatbøker

Før du kjører nbgenerate for første gang, definer et alias i din .bashrc og til ditt nåværende skall:

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

Du kan deretter kjøre nbgenerate fra kommandolinjen for å regenerere alle filene som er oppført i _notebooks.yaml :

nbgenerate googledata/devsite/content/en/PROJECT

Spesifiser én eller flere stier som argumenter for å nbgenerate for å begrense behandlingen til de angitte filene eller banene, for eksempel:

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

Katalogbaner behandles rekursivt; alle filer i _notebooks.yaml ved eller under den angitte katalogen vil bli behandlet.

Hvis du mottar "Permission denied" når du kjører nbgenerate ved å bruke aliaset ovenfor, kan du også kjøre verktøyet med følgende kommando:

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

Filtrering av innhold

I tilfeller der noe innhold bare skal vises enten på DevSite-sider eller i den genererte Colab-notatboken, men ikke begge deler, kan du filtrere innhold ved å bruke is_ipynb variabelen, som er satt til True under nbgenerate konverteringsprosessen. For å forhindre feil ved iscenesettelse og publisering til DevSite, legg til følgende nær toppen av sidene som selektivt må inkludere innhold:

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

Du kan deretter bruke Jinja-tagger for å kontrollere hvilket innhold som vises i Colab, DevSite eller begge deler. For eksempel:

# 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-eksempler

Nettsteder definerer ofte sine egne DevSite-widgets for å innkapsle vanlig atferd. Nedenfor er noen eksempler på widgets som bruker variabelen is_ipynb , som kan tilpasses nettstedet ditt.

Colab notebook knapper widget

Earth Engine-utviklerdokumentasjonen bruker en egendefinert widget for å konsekvent vise Kjør i Colab og Se kilde på GitHub- knapper på DevSite-sider synkronisert med Colab-notatbøker i GitHub.

Eksempel på seksjonswidget

Eksempelseksjonswidgeten gir et eksempel på hvordan du setter opp faneseksjoner for kodebiter presentert i flere programmeringsspråk eller miljøer. Widgeten tar seg av bare å inkludere Python-snutter i Colab-notatbøker. Den fjerner også markeringer som brukes til å vise fanedelene når du skriver notatboken.