Jupyter Notebook是TensorFlow文档架构的重要组成部分

Jupyter Notebook 是 TensorFlow 文档架构的重要组成部分。Jupyter Notebook 是 tensorflow.google.cn 上发布文档的首要格式，因此在 JupyterCon 2020 大会上，TensorFlow 文档团队想要分享一些用于管理大量 Jupyter Notebook 的工具。

Jupyter Notebook
https://jupyter-notebook.readthedocs.io/

随着 TensorFlow 生态系统的不断发展，TensorFlow 文档本身已发展成一个庞大的软件项目。我们在 tensorflow.google.cn 上发布了约 270 篇 Notebook 的指南和教程，这些内容全部经过了测试，并在 GitHub 上提供源码。同时我们还另外发布了约 400 篇翻译成多种语言的 Notebook，这些 Notebook 像其英文版本一样也都经过了测试。为了管理这些内容，我们开发了可配合 Jupyter Notebook 使用的工具。

GitHub
https://github.com/tensorflow/docs

Notebook
https://github.com/tensorflow/docs-l10n

两年前，我们在 2018 年 TensorFlow 开发者峰会上通过 TensorFlow官网 (tensorflow.google.cn) 发布了首个 Notebook，当时社区的反响非常好。在 Google Colab 中，您在浏览文档的同时，支持直接交互式地运行样例。实际上用户也非常喜欢这一点。此设置可让您直接在浏览器中运行并试验我们的指南和教程，而无需在机器上安装任何软件。我们在 TensorFlow 官网上集成 Colab 后，新手想要入门变得更加容易了，同时这也改变了我们指导 TensorFlow 入门的方式：借助 Jupyter Notebook 实现更直观易懂的教程。其他机器学习项目也将紧随其后。您只需使用下面的网址，便可将 Notebook 直接从 GitHub 加载到 Google Colab：

https://colab.research.google.com/github//blob///notebook.ipynb

对于计算密集型任务，Colab 也免费提供了 TPU 和 GPU。TensorFlow 文档（如：此快速入门教程）中有一些按钮，可以链接到文档在 GitHub 中的 Notebook 源代码和其对应的 Google Colab 中。

Colab
https://colab.research.google.com/github/tensorflow/docs/blob/master/site/en/tutorials/quickstart/beginner.ipynb

此快速入门教程
https://tensorflow.google.cn/tutorials/quickstart/advanced

GitHub
https://github.com/tensorflow/docs/blob/master/site/en/tutorials/quickstart/advanced.ipynb

更好地协作

软件文档是一项团队工作，而 Notebook 是一种富有表现力的专注于手把手教程式的格式，它可以让工程师和作者搭建出交互式演示，更直观的了解所学内容。Jupyter Notebook 是 JSON 格式的文件，包含文本单元和代码单元，通常按照从上到下的顺序执行。Notebook 是一种非常出众的交流编程理念的方式，而且在某些规程约束下，也可用于分享可重复的结果。

在 TensorFlow 团队中，Notebook 可让工程师、技术作者和开放源代码贡献者在同一文档中协作，而无需再费力处理单独的代码示例及其发布说明。我们选择编写 TensorFlow Notebook，这样一来文档即代码，且易于共享和测试。

使用 GitLocalize 翻译 Notebook

TensorFlow 团队十分重视文档在不同地区可读性。TensorFlow 社区翻译项目经过去两年的发展，已支持 10 种语言。Translation Sprints 活动是开源文档项目与社区展开互动的绝佳方式。

TensorFlow 社区翻译项目
https://github.com/tensorflow/docs-l10n

为让更多开发者能够访问 TensorFlow 文档，我们与 Alconost 合作，在其 GitLocalize 翻译工具中添加了对 Jupyter Notebook 的支持。GitLocalize 可轻松创建 Notebook 翻译版本，并可轻松与源文件同步文档更新。开放源代码贡献者可以通过 TensorFlow GitLocalize 项目(gitlocalize.com/tensorflow/docs-l10n) 提交 PR 并提供评论。

GitLocalize 对 Jupyter Notebook 的支持不仅能让 TensorFlow 受益，现在该工具也可用于所有在 GitHub 中使用 Notebook 的开源翻译项目。

TensorFlow 文档 Notebook 工具

将 Jupyter Notebook 并入我们的文档架构后，我们将可以运行并测试所有已发布的指南和教程，以确保站点上的一切内容均适用于新发布的 TensorFlow 版本，无论使用的是稳定版还是 Nightly 软件包。

指南
https://tensorflow.google.cn/guide

教程
https://tensorflow.google.cn/tutorials

除了上述优势，将 Jupyter Notebook 作为源代码进行管理也面临着一些挑战。为让代码贡献者和项目维护者更轻松地进行 PR  和 Review，我们创建了 TensorFlow 文档 Notebook 工具，以通过持续集成 (Continuous Integration) 测试自动执行常规修复并将对应的 issue 传达给贡献者。您可以直接从 tensorflow/docs GitHub 代码库安装 tensorflow-docs pip 软件包。

$ python3 -m pip install -U git+https://github.com/tensorflow/docs

TensorFlow 文档 Notebook 工具
https://github.com/tensorflow/docs/tree/master/tools/tensorflow_docs/tools

nbfmt

尽管 Jupyter Notebook 格式很简单，但 Notebook 创作环境通常存在与 JSON 格式不一致的情况，或者会将自己的元数据嵌入到文件中。这些不必要的更改可能会导致 PR 中的内容混乱，以致于很难进行内容 Review。解决办法是使用自动格式工具来输出一致的 Notebook JSON。

nbfmt 是一种 Notebook 格式工具，其首选的是 TensorFlow 文档 Notebook 样式。该工具可以设置 JSON 格式，去除不必要的元数据，并保留我们集成中所要使用的一些 Colab 特定字段。执行以下代码以运行该工具：

$ python3 -m tensorflow_docs.tools.nbfmt [options] notebook.ipynb

对于 TensorFlow 文档项目，没有输出单元的 Notebook 保存后将被执行并测试；有输出单元的 Notebook 保存后将按原样发布。我们更希望除去输出以测试我们的 Notebook，但这两种形式都可以使用 nbfmt。

TensorFlow 文档 Notebook 样式
https://tensorflow.google.cn/community/contribute/docs

进行持续集成测试时，我们可以使用 --test 标记。使用这个标记后，如果 Notebook 未设置好格式，系统会返回错误，而不是更新 Notebook。我们在我们其中一个 GitHub 操作工作流的持续集成测试中使用了该标记。通过后续集成机器人，格式补丁程序将可以自动应用于贡献者的 PR 。

GitHub 操作工作流
https://github.com/tensorflow/docs/blob/master/.github/workflows/ci.yaml

nblint

进行大规模 Review 的最简单方式就是让机器自动来操作。每个项目在审核过程中都会存在反复出现的问题，而解决样式问题最有效的方式就是使用样式指南（TensorFlow 偏好 Google 开发者文档样式指南）。对于大型项目，您能自动捕捉并进行修复的模式越多，用于实现其他目标的时间也就越多。

Google 开发者文档样式指南
https://developers.google.com/style

nblint 是一款 Notebook lint 工具，可针对文档的样式规则进行检查。在 TensorFlow Notebook 中，我们用其来捕捉常见的样式和结构问题：

>$ python3 -m tensorflow_docs.tools.nblint [options] notebook.ipynb

Lint 是用于测试 Notebook 特定部分的断言。系统会将这些 lint 收集到 样式模块中。默认情况下，nblint 会针对google和tensorflow样式进行测试，而其他样式模块则可通过命令行进行加载。某些样式的参数也需要通过命令行进行传递，例如，在对 TensorFlow 翻译 Notebook 进行 lint 时设置不同的代码库：

$ python3 -m tensorflow_docs.tools.nblint --styles=tensorflow,tensorflow_docs_l10n --arg=repo:tensorflow/docs-1l0n notebook.ipynb

Lint 测试可以包含关联的修复工具，以轻松更新 Notebook 来自动进行样式检查。使用 --fix 参数以应用 lint 修复，从而覆盖 Notebook，例如：

$ python3 -m tensorflow_docs.tools.nblint --fix --arg=repo:tensorflow/docs notebook.ipynb

样式模块
https://github.com/tensorflow/docs/tree/master/tools/tensorflow_docs/tools/nblint/style

了解详情

TensorFlow 是 Project Jupyter 和 Jupyter Notebook 的忠实粉丝。通过将 Notebook 和 Google Colab 结合，我们可以对指南、教程和翻译内容进行验证，简化了 TensorFlow 原本的学习旅程和扩展大型开源文档项目的方式。我们希望通过分享一些工具，可以为其他想要使用 Notebook 发布文档的开放源代码项目提供帮助。

阅读 TensorFlow 教程，然后在 Google Colab 中运行 Notebook。要为 TensorFlow 文档项目贡献内容，请向我们的 GitLocalize 项目提交 PR 或翻译 Review。

阅读 TensorFlow 教程
https://tensorflow.google.cn/tutorials/quickstart/beginner

运行 Notebook
https://colab.research.google.com/github/tensorflow/docs/blob/master/site/en/tutorials/quickstart/beginner.ipynb

GitLocalize 项目
https://gitlocalize.com/tensorflow/docs-l10n

特别感谢 Mark Daoust、Wolff Dobson、Yash Katariya、TensorFlow 文档团队，以及所有 TensorFlow 文档作者、审核人员、贡献者和支持者。

责任编辑：lq