このページは Cloud Translation API によって翻訳されました。

Jupyter ノートブックや Colab ノートブックの生成

nbgenerate ツールは、DevSite の HTML と Markdown のコンテンツとテンプレートを Colab 互換の Jupyter ノートブックに変換します。

概要

Google Colab のサイトから:

Colab ノートブックを使用すると、画像、HTML、LaTeX などと合わせて、実行可能コードとリッチテキストを 1 つのドキュメントに結合できます。

Colab では、ウェブブラウザから Python コードを作成して実行できますが、必要ありません。マークダウンコンテンツをコードセルに挿入して、同じドキュメントにリッチコンテンツを提供できます。そのため、Colab ノートブックは、定量的な研究や ML だけでなく、デベロッパードキュメントによく見られる API やコンセプトのデモやテストにも適したソリューションです。

そのため、Colab ノートブックで共有されるコンテンツがコンテンツと重複することがよくあります。詳しくは Google デベロッパー向けドキュメントをご覧くださいnbgenerate ツールを使用すると、DevSite マークアップと対応する Colab ノートブックを手動で同期する必要がなくなります。このツールは、DevSite HTML と Markdown を、Colab や他の Jupyter ノートブック実装で使用される .ipynb ファイル形式に変換します。これにより、DevSite のコンテンツをデベロッパー向けドキュメントと Colab ノートブックの両方の信頼できる単一の情報源として使用できます。

背景や技術的な詳細については、元の設計ドキュメント（ nbgenerate-dd

基本的な使用方法

DevSite プロジェクトのページ用に Colab ノートブックを生成するには、以下を行う必要があります。 nbgenerate コマンドを呼び出す前に _notebooks.yaml というファイルを追加します。

プロジェクトに _notebooks.yaml を追加する

DevSite プロジェクトのページから Colab ノートブックを生成するには、_notebooks.yaml というファイルをプロジェクトのルート（サイトの _project.yaml と同じディレクトリ）に追加します。このファイルには、Colab ノートブックとして共有されるページごとに 1 つのエントリを含める必要があります。各エントリの source フィールドには、 Colab ノートブックに変換できます。target フィールドには、生成された Colab ノートブックが書き込まれる google3 デポのパスを指定する必要があります。

例:

- 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

この例では、Copybara を使用して GitHub にミラーリングされるターゲットパスを使用するため、生成されたノートブックを、一般公開されているハイパーリンクで開けるようにする。 google3 パスを GitHub と同期する方法については、copybara をご覧ください。関連項目ウィジェットの例: GitHub で生成されたノートブックへのリンクを追加する例。

ノートブックの生成

nbgenerate を初めて実行する前に、.bashrc でエイリアスを定義し、現在のシェルにエイリアスを設定します。

alias nbgenerate="/google/bin/releases/devsite/tools/nbgenerate/nbgenerate.par"

コマンドラインから nbgenerate を実行すると、_notebooks.yaml にリストされているすべてのファイルを再生成できます。

nbgenerate googledata/devsite/content/en/PROJECT

1 つ以上のパスを引数として nbgenerate に指定し、処理を以下に制限します。次に例を示します。

nbgenerate third_party/devsite/developers/en/earth-engine/guides

ディレクトリのパスは再帰的に処理されます。または _notebooks.yaml 内のその下位にあるすべてのフォルダが処理されます。

「アクセスが拒否されました」というメッセージが表示された場合上記を使用して nbgenerate を実行する場合次のコマンドでツールを実行することもできます。

blaze run //devsite/tools/nbgenerate -- googledata/devsite/content/en/PROJECT

コンテンツのフィルタリング

一部のコンテンツを DevSite ページや両方ではなく、Gemini in Google Colab ノートブックを使用して is_ipynb 変数。nbgenerate 変換中に True に設定されます。プロセスですステージング時と DevSite への公開時のエラーを防ぐには、コンテンツを選択的に含める必要があるページの上部に、次のものが表示されます。

    
{% if is_ipynb is not defined %}{% set is_ipynb=False %}{% endif %}

その後、Jinja タグを使用して、Colab、DevSite、またはその両方に表示するコンテンツを制御できます。例:

# 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!');
```

ウィジェットの例

多くのサイトは、一般的な動作をカプセル化するために独自の DevSite ウィジェットを定義します。以下に、is_ipynb 変数を使用するウィジェットの例を示します。これらのウィジェットは、サイトに合わせて調整できます。

Colab ノートブックのボタンウィジェット

Earth Engine デベロッパー向けドキュメントでは、カスタムウィジェットを使用して、GitHub の Colab ノートブックと同期された DevSite ページに [Colab で実行] ボタンと [GitHub でソースを表示] ボタンを一貫して表示します。

サンプルセクションウィジェット

サンプルのセクションウィジェットは、タブ付きセクションを設定する方法の例を示しています。を使用して、複数のプログラミング言語や環境で記述されたコードスニペットに対応しました。このウィジェットは、Colab ノートブックに Python スニペットのみを追加します。また、ノートブックの作成時にタブ付きセクションの表示に使用されるマークアップも削除されます。