Instrumentul nbgenerate convertește conținutul și șabloanele DevSite HTML și Markdown în notebook-uri Jupyter compatibile cu Colab.
Vedere de ansamblu
De pe site-ul Google Colab :
Blocnotesurile Colab vă permit să combinați codul executabil și textul îmbogățit într-un singur document, împreună cu imagini, HTML, LaTeX și multe altele.
În Colab, codul Python poate fi scris și executat dintr-un browser web fără configurare sau instalare suplimentară. Conținutul Markdown poate fi intercalat cu celule de cod pentru a permite conținut bogat să fie furnizat în același document. Acest lucru face ca notebook-urile Colab să fie o soluție populară nu numai pentru cercetarea cantitativă și învățarea automată, ci și pentru demonstrarea și experimentarea cu API-uri și concepte precum cele găsite de obicei în documentația pentru dezvoltatori.
Din acest motiv, conținutul partajat în blocnotesurile Colab se suprapune adesea cu conținutul publicat în documentația pentru dezvoltatori Google. Instrumentul nbgenerate elimină necesitatea de a sincroniza manual marcajul DevSite cu notebook-uri Colab compatibile. Instrumentul convertește DevSite HTML și Markdown în formatul de fișier .ipynb utilizat de Colab și alte implementări de notebook Jupyter. Acest lucru permite conținutului DevSite să fie folosit ca o singură sursă de adevăr atât pentru documentele pentru dezvoltatori, cât și pentru notebook-urile Colab.
Context și detalii tehnice pot fi găsite în documentul de proiectare original la nbgenerate-dd .
Utilizare de bază
Pentru a genera notebook-uri Colab pentru paginile din proiectul dvs. DevSite, va trebui să adăugați un fișier numit _notebooks.yaml înainte de a invoca comanda nbgenerate .
Adăugarea _notebooks.yaml la proiectul dvs
Pentru a genera notebook-uri Colab din paginile unui proiect DevSite, adăugați un fișier numit _notebooks.yaml la rădăcina proiectului (în același director cu _project.yaml al site-ului dvs.). Fișierul ar trebui să includă o intrare pentru fiecare pagină care este partajată ca blocnotes Colab. Câmpul source al fiecărei intrări trebuie să conțină calea absolută din locatarul dvs. DevSite pentru a fi convertit într-un notebook Colab. Câmpul target trebuie să specifice calea de depozit google3 în care vor fi scrise caietele Colab generate.
De exemplu:
- 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
Acest exemplu utilizează căi țintă care sunt reflectate în GitHub folosind Copybara, astfel încât blocnotesurile generate să poată fi deschise prin hyperlinkuri accesibile public. Consultați copybara pentru detalii despre cum să sincronizați căile google3 cu GitHub. Consultați, de asemenea, exemple de widgeturi pentru exemple care adaugă linkuri către blocnotesurile generate în GitHub.
Generarea de caiete
Înainte de a rula nbgenerate pentru prima dată, definiți un alias în .bashrc și în shell-ul dvs. actual:
alias nbgenerate="/google/bin/releases/devsite/tools/nbgenerate/nbgenerate.par" Apoi puteți rula nbgenerate din linia de comandă pentru a regenera toate fișierele listate în _notebooks.yaml :
nbgenerate googledata/devsite/content/en/PROJECT Specificați una sau mai multe căi ca argumente pentru nbgenerate pentru a restricționa procesarea la fișierele sau căile specificate, de exemplu:
nbgenerate third_party/devsite/developers/en/earth-engine/guides Căile directoarelor sunt procesate recursiv; orice fișiere din _notebooks.yaml la sau sub directorul specificat vor fi procesate.
Dacă primiți „Permisiune refuzată” când rulați nbgenerate folosind aliasul de mai sus, puteți rula și instrumentul cu următoarea comandă:
blaze run //devsite/tools/nbgenerate -- googledata/devsite/content/en/PROJECT
Filtrarea conținutului
În cazurile în care un anumit conținut ar trebui să apară numai fie în paginile DevSite, fie în blocnotesul Colab generat, dar nu ambele, puteți filtra conținutul folosind variabila is_ipynb , care este setată la True în timpul procesului de conversie nbgenerate . Pentru a preveni erorile la montarea și publicarea pe DevSite, adăugați următoarele în partea de sus a paginilor care trebuie să includă selectiv conținut:
{% if is_ipynb is not defined %}{% set is_ipynb=False %}{% endif %}
Apoi puteți utiliza etichetele Jinja pentru a controla conținutul care apare în Colab, DevSite sau ambele. De exemplu:
# 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!'); ```
Exemple de widgeturi
Site-urile își definesc frecvent propriile widget-uri DevSite pentru a încapsula comportamentele comune. Mai jos sunt câteva exemple de widget-uri care utilizează variabila is_ipynb , care poate fi adaptată site-ului dvs.
Widget pentru butoanele pentru notebook Colab
Documentația pentru dezvoltatori Earth Engine utilizează un widget personalizat pentru a afișa constant butoanele Run in Colab și View sursa pe GitHub pe paginile DevSite sincronizate cu notebook-urile Colab în GitHub.
Widget de secțiune de probă
Widgetul de secțiune eșantion oferă un exemplu de configurare a secțiunilor cu file pentru fragmente de cod prezentate în mai multe limbaje sau medii de programare. Widgetul are grijă să includă doar fragmente Python în caietele Colab. De asemenea, elimină marcajul folosit pentru afișarea secțiunilor cu file atunci când scrieți caietul.