L'eina nbgenerate converteix el contingut i les plantilles HTML i Markdown de DevSite en quaderns Jupyter compatibles amb Colab.
Vista general
Des del lloc de Google Colab :
Els quaderns Colab us permeten combinar codi executable i text enriquit en un sol document, juntament amb imatges, HTML, LaTeX i molt més.
A Colab, el codi Python es pot escriure i executar des d'un navegador web sense cap configuració ni instal·lació addicional. El contingut Markdown es pot intercalar amb cel·les de codi per permetre que es proporcioni contingut enriquit al mateix document. Això fa que els quaderns de Colab siguin una solució popular no només per a la investigació quantitativa i l'aprenentatge automàtic, sinó també per demostrar i experimentar amb API i conceptes com els que normalment es troben a la documentació dels desenvolupadors.
Per aquest motiu, el contingut compartit als quaderns de Colab sovint es solapa amb el contingut publicat a la documentació per a desenvolupadors de Google. L'eina nbgenerate elimina la necessitat de sincronitzar manualment el marcatge de DevSite amb els quaderns de Colab compatibles. L'eina converteix DevSite HTML i Markdown al format de fitxer .ipynb utilitzat per Colab i altres implementacions de portàtils de Jupyter. Això permet que el contingut de DevSite s'utilitzi com a font única de veritat tant per als documents de desenvolupadors com per als quaderns de Colab.
Els antecedents i els detalls tècnics es poden trobar al document de disseny original a nbgenerate-dd .
Ús bàsic
Per generar quaderns Colab per a pàgines del vostre projecte DevSite, haureu d'afegir un fitxer anomenat _notebooks.yaml abans d'invocar l'ordre nbgenerate .
Afegint _notebooks.yaml al vostre projecte
Per generar quaderns de Colab a partir de pàgines d'un projecte DevSite, afegiu un fitxer anomenat _notebooks.yaml a l'arrel del projecte (al mateix directori que _project.yaml del vostre lloc). El fitxer hauria d'incloure una entrada per a cada pàgina que es comparteixi com a quadern de Colab. El camp source de cada entrada ha de contenir la ruta absoluta del vostre inquilí de DevSite per convertir-lo en un quadern de Colab. El camp target ha d'especificar la ruta del dipòsit de Google3 on s'escriuran els quaderns de Colab generats.
Per exemple:
- 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
Aquest exemple utilitza camins de destinació que es reflecteixen a GitHub mitjançant Copybara perquè els quaderns generats es puguin obrir mitjançant hiperenllaços d'accés públic. Consulteu copybara per obtenir més informació sobre com sincronitzar els camins de google3 amb GitHub. Vegeu també exemples de widgets per obtenir exemples que afegeixen enllaços a quaderns generats a GitHub.
Generació de quaderns
Abans d'executar nbgenerate per primera vegada, definiu un àlies al vostre .bashrc i al vostre shell actual:
alias nbgenerate="/google/bin/releases/devsite/tools/nbgenerate/nbgenerate.par" A continuació, podeu executar nbgenerate des de la línia d'ordres per regenerar tots els fitxers enumerats a _notebooks.yaml :
nbgenerate googledata/devsite/content/en/PROJECT Especifiqueu un o més camins com a arguments per a nbgenerate per restringir el processament als fitxers o camins especificats, per exemple:
nbgenerate third_party/devsite/developers/en/earth-engine/guides Els camins de directori es processen de manera recursiva; es processarà qualsevol fitxer de _notebooks.yaml al directori especificat o per sota.
Si rebeu "Permís denegat" quan executeu nbgenerate amb l'àlies anterior, també podeu executar l'eina amb l'ordre següent:
blaze run //devsite/tools/nbgenerate -- googledata/devsite/content/en/PROJECT
Filtrat de contingut
En els casos en què algun contingut només hauria d'aparèixer a les pàgines de DevSite o al bloc de notes de Colab generat, però no tots dos, podeu filtrar el contingut mitjançant la variable is_ipynb , que s'estableix en True durant el procés de conversió nbgenerate . Per evitar errors en la preparació i la publicació a DevSite, afegiu el següent a la part superior de les pàgines que han d'incloure contingut de manera selectiva:
{% if is_ipynb is not defined %}{% set is_ipynb=False %}{% endif %}
A continuació, podeu utilitzar les etiquetes Jinja per controlar quin contingut apareix a Colab, DevSite o tots dos. Per exemple:
# 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!'); ```
Exemples de widgets
Els llocs sovint defineixen els seus propis ginys DevSite per encapsular comportaments habituals. A continuació es mostren alguns exemples de ginys que utilitzen la variable is_ipynb , que es poden adaptar al vostre lloc.
Giny de botons de la llibreta Colab
La documentació per a desenvolupadors d'Earth Engine utilitza un widget personalitzat per mostrar de manera coherent els botons Executar a Colab i Veure font a GitHub a les pàgines de DevSite sincronitzades amb els quaderns de Colab a GitHub.
Giny de la secció de mostra
El giny de secció de mostra proporciona un exemple de com configurar seccions amb pestanyes per a fragments de codi presentats en diversos llenguatges o entorns de programació. El giny només s'encarrega d'incloure fragments de Python als quaderns de Colab. També elimina el marcatge utilitzat per mostrar les seccions amb pestanyes quan escriu el quadern.