Lo strumento nbgenerate converte i contenuti e i modelli HTML DevSite HTML e Markdown
nei blocchi note Jupyter compatibili con Colab.
Panoramica
Dal sito Google Colab:
I blocchi note di Colab ti consentono di combinare codice eseguibile e RTF in un unico documento, insieme a immagini, HTML, LaTeX e altro ancora.
In Colab, il codice Python può essere scritto ed eseguito da un browser web senza configurazione o installazione aggiuntiva. I contenuti Markdown possono essere intervallati da celle di codice per consentire di fornire contenuti avanzati nello stesso documento. Questo rende i notebook di Colab una soluzione popolare non solo per la ricerca quantitativa e il machine learning, ma anche per la dimostrazione e la sperimentazione di API e concetti come quelli che si trovano in genere nella documentazione per sviluppatori.
Per questo motivo, i contenuti condivisi nei blocchi note di Colab spesso si sovrappongono ai contenuti pubblicati nella documentazione per gli sviluppatori Google. Lo strumento nbgenerate elimina devono sincronizzare manualmente il markup DevSite con i blocchi note Colab di supporto. Lo strumento converte HTML e Markdown di DevSite nel formato file .ipynb utilizzato da Colab e da altre implementazioni di Jupyter Notebook. In questo modo è possibile usare i contenuti di DevSite come unica fonte attendibile sia per i documenti per gli sviluppatori sia per i blocchi note di Colab.
Informazioni generali e dettagli tecnici sono disponibili nel documento di progettazione originale all'indirizzo nbgenerate-dd.
Utilizzo di base
Per generare blocchi note di Colab per le pagine del tuo progetto DevSite, dovrai:
aggiungi un file denominato _notebooks.yaml prima di richiamare il comando nbgenerate.
Aggiunta di _notebooks.yaml al tuo progetto
Per generare notebook di Colab dalle pagine di un progetto DevSite, aggiungi un file denominato _notebooks.yaml alla directory principale del progetto (nella stessa directory di _project.yaml del tuo sito). Il file deve includere una voce per ogni pagina condivisa come notebook di Colab. Il campo source di ogni voce deve contenere il percorso assoluto all'interno del tenant DevSite per essere convertito in un notebook Colab. Il campo target deve specificare il percorso del repository google3 in cui verranno scritti i blocchi note di Colab generati.
Ad esempio:
- 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
Questo esempio utilizza percorsi di destinazione che vengono sottoposti a mirroring a GitHub utilizzando Copybara che i blocchi note generati possano essere aperti tramite link ipertestuali accessibili pubblicamente. Consulta copybara per informazioni dettagliate su come sincronizzare i percorsi google3 con GitHub. Consulta anche Esempi di widget per esempi che aggiungono link ai notebook generati in GitHub.
Generazione di blocchi note in corso
Prima di eseguire nbgenerate per la prima volta, definisci un alias nel tuo
.bashrc e alla tua shell attuale:
alias nbgenerate="/google/bin/releases/devsite/tools/nbgenerate/nbgenerate.par"
Puoi quindi eseguire nbgenerate dalla riga di comando per rigenerare tutti i file
elencato in _notebooks.yaml:
nbgenerate googledata/devsite/content/en/PROJECT
Specifica uno o più percorsi come argomenti per nbgenerate a cui limitare l'elaborazione
i file o i percorsi specificati, ad esempio:
nbgenerate third_party/devsite/developers/en/earth-engine/guides
I percorsi delle directory vengono elaborati in modo ricorsivo, qualsiasi file in _notebooks.yaml alle ore o
sotto la directory specificata verranno elaborati.
Se ricevi il messaggio "Autorizzazione negata" quando esegui nbgenerate utilizzando l'alias riportato sopra, puoi anche eseguire lo strumento con il seguente comando:
blaze run //devsite/tools/nbgenerate -- googledata/devsite/content/en/PROJECT
Filtrare i contenuti
Nei casi in cui alcuni contenuti debbano essere visualizzati solo nelle pagine DevSite o nel
blocco note di Colab generato, ma non entrambi, puoi filtrare i contenuti utilizzando
Variabile is_ipynb, che è impostata su True durante la conversione di nbgenerate
e il processo di sviluppo. Per evitare errori durante la gestione temporanea e la pubblicazione su DevSite, aggiungi il
seguenti nella parte superiore delle pagine che devono includere selettivamente i contenuti:
{% if is_ipynb is not defined %}{% set is_ipynb=False %}{% endif %}
Puoi quindi usare i tag Jinja per controllare quali contenuti vengono visualizzati in Colab, DevSite o entrambe le cose. Ad esempio:
# 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!');
```
Esempi di widget
I siti spesso definiscono i propri widget DevSite per incapsulare i comportamenti comuni. Di seguito sono riportati alcuni esempi di widget che utilizzano la variabile is_ipynb, che può essere adattata al tuo sito.
Widget dei pulsanti del blocco note di Colab
La documentazione per gli sviluppatori di Earth Engine usa un widget personalizzato per visualizzare in modo coerente i pulsanti Esegui in Colab e Visualizza sorgente su GitHub sulle pagine del sito per sviluppatori sincronizzate con i blocchi note di Colab in GitHub.
Widget sezione di esempio
Il widget di sezione di esempio fornisce un esempio di come configurare sezioni con schede per gli snippet di codice presentati in più linguaggi di programmazione o ambienti. Il widget si occupa di includere solo gli snippet di Python nei blocchi note di Colab. Inoltre, rimuove il markup utilizzato per visualizzare le sezioni con schede durante la scrittura del notebook.