Narzędzie nbgenerate konwertuje zawartość i szablony w formacie HTML i Markdown na stronie dewelopera na notatniki Jupyter zgodne z Colabem.
OverView
Na stronie Google Colab:
Notatniki Colab umożliwiają łączenie kodu wykonywalnego i tekstu sformatowanego w razem z obrazami, plikami HTML LaTeX i inne rozwiązania.
W Colab kod Pythona można pisać i wykonywać w przeglądarce bez dodatkowej konfiguracji czy instalacji. Treści Markdown mogą być przeplatane komórkami kodu, aby umożliwić wyświetlanie rozbudowanych treści w tym samym dokumencie. Dzięki temu zeszyty Colab jest popularnym rozwiązaniem nie tylko do badań ilościowych i systemów uczących się, ale też do demonstrowania i eksperymentowania z interfejsami API oraz pojęciami, które zwykle można znaleźć w dokumentacji dla programistów.
Z tego powodu treści udostępniane w notatnikach Colab często zasłaniają treść opublikowane w dokumentacji Google dla deweloperów. Narzędzie nbgenerate eliminuje muszą ręcznie synchronizować znaczniki DevSite z obsługiwanymi notatnikami Colab. Narzędzie konwertuje kod HTML i Markdown na pliki DevSite na format .ipynb używany przez Colab i inne implementacje notatników Jupyter. Dzięki temu treści na stronie dla programistów mogą być używane jako jedno źródło informacji zarówno w przypadku dokumentów dla programistów, jak i notebooków Colab.
Kontekst i szczegóły techniczne można znaleźć w oryginalnym dokumencie projektowym na stronie nbgenerate-dd.
Podstawowe użycie
Aby wygenerować notatki w Colab na potrzeby stron w projekcie DevSite, przed wywołaniem polecenia nbgenerate musisz dodać plik o nazwie _notebooks.yaml.
Dodanie pliku _notebooks.yaml do projektu
Aby wygenerować notatniki Colab na podstawie stron w projekcie DevSite, dodaj plik o nazwie
_notebooks.yaml do katalogu głównego projektu (w tym samym katalogu, w którym znajduje się witryna
_project.yaml). Plik powinien zawierać po jednej pozycji na każdą udostępnianą stronę.
jako notatnik Colab. Pole source każdego wpisu musi zawierać bezwzględną wartość
w ramach najemcy DevSite do przekonwertowania na notatnik Colab. W polu target musisz podać ścieżkę do repozytorium google3, w którym będą zapisywane wygenerowane notatniki Colab.
Na przykład:
- 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
W tym przykładzie są używane ścieżki docelowe powielane do GitHuba za pomocą narzędzia Copybara, że wygenerowane notatniki można otwierać za pomocą publicznie dostępnych hiperlinków. Zobacz copybara . Przykłady dodawania linków do wygenerowanych notatników na GitHubie znajdziesz w sekcji Przykłady widżetów.
Generowanie notatników
Przed pierwszym uruchomieniem usługi nbgenerate zdefiniuj alias w
.bashrc i do bieżącej powłoki:
alias nbgenerate="/google/bin/releases/devsite/tools/nbgenerate/nbgenerate.par"
Następnie możesz uruchomić nbgenerate z poziomu wiersza poleceń, aby wygenerować ponownie wszystkie pliki wymienione w pliku _notebooks.yaml:
nbgenerate googledata/devsite/content/en/PROJECT
Podaj co najmniej 1 ścieżkę jako argumenty funkcji nbgenerate, aby ograniczyć przetwarzanie do
w określonych plikach lub ścieżkach, na przykład:
nbgenerate third_party/devsite/developers/en/earth-engine/guides
Ścieżki katalogów są przetwarzane rekurencyjnie; wszystkich plików w folderze _notebooks.yaml lub
poniżej określonego katalogu, zostanie przetworzony.
Jeśli zobaczysz komunikat „Odmowa dostępu” podczas uruchamiania nbgenerate przy użyciu powyższego
alias, możesz też uruchomić narzędzie za pomocą następującego polecenia:
blaze run //devsite/tools/nbgenerate -- googledata/devsite/content/en/PROJECT
Filtrowanie treści
W przypadku treści, które powinny pojawiać się tylko na stronach DevSite lub w wygenerowanym notatniku Colab, ale nie na obu tych platformach, możesz filtrować treści za pomocą zmiennej is_ipynb, która jest ustawiona na True podczas procesu konwersji nbgenerate. Aby uniknąć błędów podczas tworzenia wersji roboczej i publikowania w DevSite, dodaj te informacje u góry stron, które mają zawierać treści tylko w wybranych miejscach:
{% if is_ipynb is not defined %}{% set is_ipynb=False %}{% endif %}
Następnie możesz używać tagów Jinja, aby kontrolować, które treści będą wyświetlane w Colab, DevSite lub obu tych usługach. Na przykład:
# 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!');
```
Przykłady widżetów
Strony często definiują własne widżety DevSite, aby ująć typowe zachowania. Poniżej znajdziesz kilka przykładów widżetów korzystających ze zmiennej is_ipynb, która może zostać dostosowana do Twojej witryny.
Widżet przycisków notatnika Colab
Dokumentacja dla deweloperów Earth Engine korzysta z widżetu niestandardowego do spójnego wyświetlania przycisków Uruchom w Colab i Wyświetl źródło w GitHubie na stronach DevSite zsynchronizowanych z notatnikami Colab w GitHubie.
Przykładowy widżet sekcji
Przykładowy widżet sekcji zawiera przykład konfiguracji sekcji z kartami dla fragmentów kodu prezentowanych w wielu językach programowania lub środowiskach. Widget uwzględnia tylko fragmenty kodu Pythona w notatkach w Colab. it usuwa też znaczniki używane do wyświetlania sekcji z kartami podczas tworzenia notatnika.