JupyterNotebook实用工具分享，高效管理TensorFlow文档-永久免费的源码丞旭猿

随着机器学习框架 TensorFlow 生态系统的不断发展，TensorFlow 文档已经发展成一个庞大的软件项目。其中，Jupyter Notebook 是TensorFlow 文档架构的重要组成部分，也是tensorflow.google.cn上发布文档的首要格式。本文将分享一些用于管理大量Jupyter Notebook的工具，创造更高效、流畅的 TensorFlow 文档体验。

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

两年前，我们在 2018 年TensorFlow 开发者峰会上通过 TensorFlow官网 (http://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 中。

更好地协作

软件文档是一项团队工作，而 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 项目提交 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

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

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

了解详情

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 文档作者、审核人员、贡献者和支持者。

谷歌开发者官方现已开通知乎专栏：TensorFlow 学习资源站，一站式收录来自官方的 TensorFlow 相关实用技术资源，欢迎关注，及时收到更新提醒！

想获取更多实用工具分享？欢迎关注 TensorFlow 官方微信公众号（TensorFlow_official）！

声明：本文部分素材转载自互联网，如有侵权立即删除 。