Jupyter Notebook 工具分享,增强 TensorFlow 文档体验

本文源于 JupyterCon 2020 大会上 TensorFlow 文档团队的分享。

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

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

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

https://colab.research.google.com/github/<repo>/blob/<branch>/<path>/notebook.ipynb

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

更好地协作

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

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

使用 GitLocalize 翻译 Notebook

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

为让更多开发者能够访问 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 软件包。

除了上述优势,将 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

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

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

nblint

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

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

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

Lint 是用于测试 Notebook 特定部分的断言。系统会将这些 lint 收集到 样式模块 中。默认情况下,nblint 会针对 googletensorflow 样式进行测试,而其他样式模块则可通过命令行进行加载。某些样式的参数也需要通过命令行进行传递,例如,在对 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

了解详情

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

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

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

原文:How TensorFlow docs uses Jupyter notebooks
中文:TensorFlow 公众号