De nbgenerate tool converteert DevSite HTML- en Markdown-inhoud en sjablonen naar Colab-compatibele Jupyter-notebooks.
Overzicht
Van de Google Colab -site:
Met Colab-notebooks kunt u uitvoerbare code en rich-text combineren in één document, samen met afbeeldingen, HTML, LaTeX en meer.
In Colab kan Python-code worden geschreven en uitgevoerd vanuit een webbrowser zonder extra configuratie of installatie. Markdown-inhoud kan worden afgewisseld met codecellen, zodat rijke inhoud in hetzelfde document kan worden aangeboden. Dit maakt Colab-notebooks niet alleen een populaire oplossing voor kwantitatief onderzoek en machinaal leren, maar ook voor het demonstreren en experimenteren met API's en concepten zoals die doorgaans te vinden zijn in documentatie voor ontwikkelaars.
Om deze reden overlapt inhoud die wordt gedeeld in Colab-notebooks vaak met inhoud die is gepubliceerd in de ontwikkelaarsdocumentatie van Google. Met de nbgenerate-tool is het niet meer nodig om DevSite-markup handmatig te synchroniseren met ondersteunende Colab-notebooks. De tool converteert DevSite HTML en Markdown naar de .ipynb-bestandsindeling die wordt gebruikt door Colab en andere Jupyter-notebookimplementaties. Hierdoor kan DevSite-inhoud worden gebruikt als enige bron van waarheid voor zowel ontwikkelaarsdocumenten als Colab-notebooks.
Achtergrond- en technische details zijn te vinden in het originele ontwerpdocument op nbgenerate-dd .
Basisgebruik
Als u Colab-notebooks wilt genereren voor pagina's in uw DevSite-project, moet u een bestand met de naam _notebooks.yaml toevoegen voordat u de opdracht nbgenerate aanroept.
_notebooks.yaml toevoegen aan uw project
Als u Colab-notebooks wilt genereren op basis van pagina's in een DevSite-project, voegt u een bestand met de naam _notebooks.yaml toe aan de hoofdmap van het project (in dezelfde map als _project.yaml van uw site). Het bestand moet één vermelding bevatten voor elke pagina die als Colab-notitieblok wordt gedeeld. Het source van elk item moet het absolute pad binnen uw DevSite-tenant bevatten om te worden geconverteerd naar een Colab-notebook. Het target moet het google3-depotpad specificeren waar de gegenereerde Colab-notebooks zullen worden geschreven.
Bijvoorbeeld:
- 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
In dit voorbeeld worden doelpaden gebruikt die met behulp van Copybara naar GitHub worden gespiegeld, zodat de gegenereerde notitieblokken kunnen worden geopend via openbaar toegankelijke hyperlinks. Zie copybara voor details over het synchroniseren van google3-paden met GitHub. Zie ook Widget-voorbeelden voor voorbeelden waarin koppelingen naar gegenereerde notitieblokken in GitHub worden toegevoegd.
Notitieboekjes genereren
Voordat u nbgenerate voor de eerste keer uitvoert, definieert u een alias in uw .bashrc en in uw huidige shell:
alias nbgenerate="/google/bin/releases/devsite/tools/nbgenerate/nbgenerate.par" U kunt vervolgens nbgenerate uitvoeren vanaf de opdrachtregel om alle bestanden in _notebooks.yaml opnieuw te genereren:
nbgenerate googledata/devsite/content/en/PROJECT Geef een of meer paden op als argumenten voor nbgenerate om de verwerking te beperken tot de opgegeven bestanden of paden, bijvoorbeeld:
nbgenerate third_party/devsite/developers/en/earth-engine/guides Directorypaden worden recursief verwerkt; alle bestanden in _notebooks.yaml op of onder de opgegeven map worden verwerkt.
Als u de melding "Toestemming geweigerd" ontvangt wanneer u nbgenerate uitvoert met de bovenstaande alias, kunt u de tool ook uitvoeren met de volgende opdracht:
blaze run //devsite/tools/nbgenerate -- googledata/devsite/content/en/PROJECT
Inhoud filteren
In gevallen waarin bepaalde inhoud alleen op DevSite-pagina's of in het gegenereerde Colab-notebook zou moeten verschijnen, maar niet in beide, kunt u inhoud filteren met de variabele is_ipynb , die is ingesteld op True tijdens het nbgenerate conversieproces. Om fouten bij het faseren en publiceren naar DevSite te voorkomen, voegt u het volgende toe bovenaan pagina's die selectief inhoud moeten opnemen:
{% if is_ipynb is not defined %}{% set is_ipynb=False %}{% endif %}
Vervolgens kunt u Jinja-tags gebruiken om te bepalen welke inhoud wordt weergegeven in Colab, DevSite of beide. Bijvoorbeeld:
# 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!'); ```
Widgetvoorbeelden
Sites definiëren vaak hun eigen DevSite-widgets om gemeenschappelijk gedrag vast te leggen. Hieronder vindt u enkele voorbeelden van widgets die de variabele is_ipynb gebruiken, die mogelijk aan uw site zijn aangepast.
Colab-widget voor notitieboekjeknoppen
De ontwikkelaarsdocumentatie van Earth Engine maakt gebruik van een aangepaste widget om de knoppen Uitvoeren in Colab en Bron weergeven op GitHub consistent weer te geven op DevSite-pagina's die zijn gesynchroniseerd met Colab-notebooks in GitHub.
Voorbeeldsectiewidget
De voorbeeldsectiewidget biedt een voorbeeld van hoe u secties met tabbladen kunt instellen voor codefragmenten die in meerdere programmeertalen of omgevingen worden gepresenteerd. De widget zorgt ervoor dat alleen Python-fragmenten in Colab-notebooks worden opgenomen. Het verwijdert ook de markeringen die worden gebruikt om de secties met tabbladen weer te geven bij het schrijven van het notitieblok.