nbgenerate 工具可转换 DevSite HTML 和 Markdown 内容和模板
转换为与 Colab 兼容的 Jupyter 笔记本。
OverView
在 Google Colab 网站上：
Colab 笔记本可让您将可执行代码和富文本合并到一个 以及图片、HTML LaTeX 等。
在 Colab 中，您可以通过网络浏览器编写和执行 Python 代码， 额外设置或安装。Markdown 内容可以夹杂代码 单元格以允许在同一文档中提供富媒体内容。这使得 Colab 笔记本是一种广受欢迎的解决方案，不仅用于定量研究和 还可用于演示和实验 API 和 概念，比如开发者文档中常见的概念。
因此，Colab 笔记本中分享的内容通常与 Google 开发者文档中发布的内容重叠。nbgenerate 工具消除了 需要手动将 DevSite 标记与支持的 Colab 笔记本同步。工具 将 DevSite HTML 和 Markdown 转换为 Colab 使用的 .ipynb 文件格式，并且 其他 Jupyter 笔记本实现。这样一来，开发者文档和 Colab 记事本就可以使用 DevSite 内容作为单一可信来源。
如需了解背景信息和技术详情，请参阅 nbgenerate-dd 中的原始设计文档。
基本用法
要为 DevSite 项目中的网页生成 Colab 笔记本，您需要
在调用 nbgenerate 命令之前，添加一个名为 _notebooks.yaml 的文件。
将 _notebooks.yaml 添加到项目中
如需根据 DevSite 项目中的网页生成 Colab 笔记本，请将名为 _notebooks.yaml 的文件添加到项目根目录（与您网站的 _project.yaml 位于同一目录中）。该文件应包含一个条目，用于表示要作为 Colab 笔记本共享的每个网页。每个条目的 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 中定义一个别名，并将其添加到当前 shell：
alias nbgenerate="/google/bin/releases/devsite/tools/nbgenerate/nbgenerate.par"
然后，您可以从命令行运行 nbgenerate 以重新生成所有文件
在 _notebooks.yaml 中列出：
nbgenerate googledata/devsite/content/en/PROJECT
将一个或多个路径作为 nbgenerate 的参数指定，以将处理限制为指定的文件或路径，例如：
nbgenerate third_party/devsite/developers/en/earth-engine/guides
以递归方式处理目录路径；_notebooks.yaml 中的任何文件在 或
会得到处理
如果您收到“权限遭拒”错误消息使用上面的命令运行 nbgenerate 时
别名，您也可以使用以下命令运行该工具：
blaze run //devsite/tools/nbgenerate -- googledata/devsite/content/en/PROJECT
过滤内容
如果某些内容只应显示在 DevSite 页面或
生成了 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 变量的 widget 示例，您可以根据自己的网站进行调整。
Colab 笔记本按钮微件
Earth Engine 开发者文档使用自定义 widget 在与 GitHub 中的 Colab 笔记本同步的 DevSite 页面上一致地显示在 Colab 中运行和在 GitHub 上查看源代码按钮。
部分 widget 示例
“示例部分”微件 提供了如何设置标签页式版块的示例 。 该 widget 仅在 Colab 笔记本中包含 Python 代码段。它 还会删除在编写 笔记本。