L'outil nbgenerate convertit le contenu et les modèles DevSite HTML et Markdown
aux notebooks Jupyter compatibles avec Colab.
OverView
Sur le site Google Colab:
Les notebooks Colab vous permettent de combiner du code exécutable et du texte enrichi dans une ainsi que des images, du code HTML, LaTeX et plus encore.
Dans Colab, le code Python peut être écrit et exécuté à partir d'un navigateur Web sans une configuration ou une installation supplémentaire. Le contenu Markdown peut être intercalé avec du code pour permettre l'insertion de contenu enrichi dans un même document. Ainsi, Les notebooks Colab sont une solution populaire non seulement pour la recherche quantitative et le machine learning, mais aussi pour démontrer et tester des API et comme ceux généralement disponibles dans la documentation pour les développeurs.
Pour cette raison, le contenu partagé dans les notebooks Colab chevauche souvent le contenu publiés dans la documentation Google pour les développeurs. L'outil nbgenerate élimine le devez synchroniser manuellement le balisage DevSite avec les notebooks Colab compatibles. Outil convertit le code HTML et Markdown de DevSite au format de fichier .ipynb utilisé par Colab et à d'autres implémentations de notebooks Jupyter. Cela permet d'utiliser le contenu DevSite comme source unique d'informations fiables à la fois pour les documents pour les développeurs et les notebooks Colab.
Vous trouverez le contexte et les détails techniques dans le document de conception original à l'adresse nbgenerate-dd
Utilisation de base
Pour générer des notebooks Colab pour les pages de votre projet DevSite, vous devez :
Ajoutez un fichier nommé _notebooks.yaml avant d'appeler la commande nbgenerate.
Ajouter _notebooks.yaml à votre projet
Pour générer des notebooks Colab à partir des pages d'un projet DevSite, ajoutez un fichier appelé
_notebooks.yaml à la racine du projet (dans le même répertoire que le répertoire
_project.yaml). Le fichier doit inclure une entrée pour chaque page partagée
en tant que notebook Colab. Le champ source de chaque entrée doit contenir la valeur absolue
dans votre locataire DevSite pour le convertir en notebook Colab. La
Le champ target doit spécifier le chemin du dépôt Google3 dans lequel le Colab est généré
notebooks seront écrits.
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
Cet exemple utilise des chemins d'accès cibles qui sont mis en miroir vers GitHub à l'aide de Copybara. Ainsi, que les notebooks générés peuvent être ouverts via des liens hypertexte accessibles publiquement. Voir copybara pour savoir comment synchroniser les chemins d'accès google3 avec GitHub. Voir aussi Exemples de widgets qui ajoutent des liens vers les notebooks générés dans GitHub.
Générer des notebooks
Avant d'exécuter nbgenerate pour la première fois, définissez un alias dans votre
.bashrc et à votre interface système actuelle:
alias nbgenerate="/google/bin/releases/devsite/tools/nbgenerate/nbgenerate.par"
Vous pouvez ensuite exécuter nbgenerate à partir de la ligne de commande pour regénérer tous les fichiers.
listé dans _notebooks.yaml:
nbgenerate googledata/devsite/content/en/PROJECT
Spécifiez un ou plusieurs chemins d'accès en tant qu'arguments de nbgenerate pour limiter le traitement à
les fichiers ou chemins d'accès spécifiés, par exemple:
nbgenerate third_party/devsite/developers/en/earth-engine/guides
Les chemins d'accès aux répertoires sont traités de manière récursive. tous les fichiers dans _notebooks.yaml dans ou
situé sous le répertoire spécifié sont traités.
Si le message "Autorisation refusée" s'affiche lors de l'exécution de nbgenerate à l'aide de ce qui précède
vous pouvez également exécuter l'outil à l'aide de la commande suivante:
blaze run //devsite/tools/nbgenerate -- googledata/devsite/content/en/PROJECT
Filtrer le contenu
Dans les cas où une partie du contenu ne doit apparaître que sur les pages DevSite ou dans
notebook Colab généré, mais pas les deux, vous pouvez filtrer le contenu à l'aide du
La variable is_ipynb, définie sur True lors de la conversion nbgenerate
processus. Pour éviter les erreurs lors de la préproduction et de la publication sur DevSite, ajoutez le
en haut des pages qui doivent inclure du contenu de façon sélective:
{% if is_ipynb is not defined %}{% set is_ipynb=False %}{% endif %}
Vous pouvez ensuite utiliser les balises Jinja pour contrôler le contenu qui apparaît dans Colab, DevSite ou les deux. 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
Les sites définissent fréquemment leurs propres widgets DevSite pour encapsuler les comportements courants. Vous trouverez ci-dessous quelques exemples de widgets qui utilisent la variable is_ipynb, qui peuvent être adaptés à votre site.
Widget des boutons du notebook Colab
La documentation destinée aux développeurs Earth Engine utilise un widget personnalisé pour afficher de manière cohérente les boutons Exécuter dans Colab et Afficher le code source sur GitHub sur les pages DevSite synchronisées avec les notebooks Colab dans GitHub.
Exemple de widget de section
Exemple de widget de section fournit un exemple de configuration des sections à onglets pour obtenir des extraits de code présentés dans plusieurs langages ou environnements de programmation. Le widget ne permet d'inclure que des extraits de code Python dans les notebooks Colab. Il supprime également le balisage utilisé pour afficher les sections à onglets lors de l'écriture du notebook.