由 TensorFlow 团队的 Billy Lamberta 发布

随着 TensorFlow 生态系统的不断发展，TensorFlow 文档本身也已发展成为一个相当大的软件项目。我们在 tensorflow.org 上发布了约 270 个笔记本 指南 和 教程，所有这些都经过测试，可以在 GitHub 上获得。我们还发布了另外约 400 个 翻译后的笔记本，用于多种语言，所有这些都像其英文版本一样经过测试。我们开发的用于处理 Jupyter 笔记本的工具可以帮助我们管理所有这些内容。

当我们在两年多前为 2018 年 TensorFlow 开发者峰会发布了我们在 tensorflow.org 上的第一个笔记本时，社区的反应非常热烈。用户喜欢他们可以立即从网页文档跳转到 Google Colab 中的交互式计算体验。此设置允许您在浏览器中运行（并实验）我们的指南和教程，而无需在您的机器上安装任何软件。这种 tensorflow.org 与 Colab 的集成使入门变得更加容易，并改变了我们使用 Jupyter 笔记本教授 TensorFlow 的方式。其他机器学习项目也很快效仿。笔记本可以直接从 GitHub 加载到 Google Colab，只需使用 URL

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

对于计算密集型任务，Colab 免费提供 TPU 和 GPU。TensorFlow 文档（例如 此快速入门教程）包含按钮，这些按钮链接到其笔记本的 GitHub 中的源代码 以及 在 Colab 中加载。

更好的协作

软件文档是一项团队工作，笔记本是一种表达性强、以教育为中心的格式，允许工程师和作家构建交互式演示。Jupyter 笔记本是 JSON 格式的文件，包含文本单元格和代码单元格，通常按从上到下的顺序执行。它们是传达编程理念的绝佳方式，并且，如果有一定的纪律，还可以分享可再现的结果。

在 TensorFlow 团队中，笔记本允许工程师、技术作家和开源贡献者在同一个文档上进行协作，而无需担心独立的代码示例与其发布的解释之间存在冲突。我们编写 TensorFlow 笔记本，以便文档就是代码，它是自包含的、易于共享的、经过测试的。

使用 GitLocalize 进行笔记本翻译

文档需要触达世界各地的所有人，这是 TensorFlow 团队所重视的。在过去两年中，TensorFlow 社区翻译项目 已发展到 10 种语言。 翻译冲刺 是参与开源文档项目的社区的绝佳方式。

为了使 TensorFlow 文档更便于更多开发者访问，我们与 Alconost 合作，为其 GitLocalize 翻译工具添加了 Jupyter 笔记本支持。GitLocalize 使创建翻译后的笔记本和同步源文件中的文档更新变得容易。开源贡献者可以使用 TensorFlow GitLocalize 项目提交拉取请求并提供审阅：gitlocalize.com/tensorflow/docs-l10n.

GitLocalize 中的 Jupyter 笔记本支持不仅对 TensorFlow 有益，现在还可用于所有使用笔记本和 GitHub 的开源翻译项目。

TensorFlow 文档笔记本工具

将 Jupyter 笔记本纳入我们的文档基础设施，使我们能够运行和测试所有发布的 指南 和 教程，以确保网站上的所有内容都能在新版本的 TensorFlow 中正常工作，使用稳定版或夜间版软件包。

除了好处之外，将 Jupyter 笔记本作为源代码进行管理也存在一些挑战。为了使贡献者和项目维护者更方便地提交拉取请求和进行审阅，我们创建了 TensorFlow 文档笔记本工具 来自动执行常见的修复，并使用持续集成 (CI) 测试向贡献者传达问题。您可以直接从 tensorflow/docs GitHub 存储库安装 tensorflow-docs pip 包

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

nbfmt

虽然 Jupyter 笔记本格式很简单，但笔记本创作环境通常在 JSON 格式方面不一致，或者在文件中嵌入其自身的元数据。这些不必要的更改会导致拉取请求中的差异混乱，这会使内容审阅变得困难。解决办法是使用自动格式化程序，该格式化程序输出一致的笔记本 JSON。

nbfmt 是一款笔记本格式化程序，优先使用 TensorFlow 文档笔记本样式。它会格式化 JSON 并删除不必要的元数据，除了用于我们集成的某些特定于 Colab 的字段。要运行

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

对于 TensorFlow 文档项目，保存的不含输出单元格的笔记本将被执行和测试；保存的含输出单元格的笔记本将按原样发布。我们更喜欢删除输出以测试我们的笔记本，但 nbfmt 可以与这两种格式一起使用。

--test 标志可用于持续集成测试。它不会更新笔记本，而是在笔记本格式不正确的情况下返回错误。我们在 GitHub Actions 工作流程 之一中的 CI 测试中使用了它。并且通过一些进一步的机器人集成，格式化补丁可以自动应用到贡献者的拉取请求中。

nblint

扩大审阅范围的最简单方法是让机器来做。每个项目都会出现一些反复出现的问题，这些问题会在审阅中出现，而样式问题通常最好通过样式指南来解决（TensorFlow 喜欢 Google 开发者文档样式指南）。对于大型项目，您可以自动捕获和修复的模式越多，您就越有时间用于其他目标。

nblint 是一款笔记本代码风格检查工具，它会检查文档样式规则。我们使用它来捕获 TensorFlow 笔记本中常见的样式和结构问题

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

代码风格检查是测试笔记本特定部分的断言。这些代码风格检查收集到 样式模块 中。nblint 默认测试google 和tensorflow 样式，其他样式模块可以在命令行中加载。有些样式需要在命令行中传递的参数，例如，在对 TensorFlow 翻译笔记本进行代码风格检查时设置不同的存储库

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

代码风格检查测试可能有一个关联的修复程序，使更新笔记本以自动通过样式检查变得容易。使用 --fix 参数应用代码风格检查修复程序，该修复程序将覆盖笔记本，例如

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

了解更多信息

TensorFlow 是 Project Jupyter 和 Jupyter 笔记本的忠实粉丝。除了 Google Colab 之外，笔记本还改变了我们教授 TensorFlow 的方式，并通过经过测试的指南、教程和翻译来扩展大型开源文档项目。我们希望分享一些工具，可以帮助其他希望使用笔记本作为文档的开源项目。

阅读 TensorFlow 教程，然后在 Google Colab 中 运行该笔记本。要为 TensorFlow 文档项目做出贡献，请向我们的 提交拉取请求 或向我们的 GitLocalize 项目 提交翻译审阅。

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