Jupyter Notebook 是 TensorFlow 文檔架構(gòu)的重要組成部分。Jupyter Notebook 是 tensorflow.google.cn 上發(fā)布文檔的首要格式，因此在 JupyterCon 2020 大會(huì)上，TensorFlow 文檔團(tuán)隊(duì)想要分享一些用于管理大量 Jupyter Notebook 的工具。

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

隨著 TensorFlow 生態(tài)系統(tǒng)的不斷發(fā)展，TensorFlow 文檔本身已發(fā)展成一個(gè)龐大的軟件項(xiàng)目。我們?cè)?tensorflow.google.cn 上發(fā)布了約 270 篇 Notebook 的指南和教程，這些內(nèi)容全部經(jīng)過了測(cè)試，并在 GitHub 上提供源碼。同時(shí)我們還另外發(fā)布了約 400 篇翻譯成多種語言的 Notebook，這些 Notebook 像其英文版本一樣也都經(jīng)過了測(cè)試。為了管理這些內(nèi)容，我們開發(fā)了可配合 Jupyter Notebook 使用的工具。

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

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

兩年前，我們?cè)?2018 年 TensorFlow 開發(fā)者峰會(huì)上通過 TensorFlow官網(wǎng)(tensorflow.google.cn)發(fā)布了首個(gè) Notebook，當(dāng)時(shí)社區(qū)的反響非常好。在 Google Colab 中，您在瀏覽文檔的同時(shí)，支持直接交互式地運(yùn)行樣例。實(shí)際上用戶也非常喜歡這一點(diǎn)。此設(shè)置可讓您直接在瀏覽器中運(yùn)行并試驗(yàn)我們的指南和教程，而無需在機(jī)器上安裝任何軟件。我們?cè)?TensorFlow 官網(wǎng)上集成 Colab 后，新手想要入門變得更加容易了，同時(shí)這也改變了我們指導(dǎo) TensorFlow 入門的方式：借助 Jupyter Notebook 實(shí)現(xiàn)更直觀易懂的教程。其他機(jī)器學(xué)習(xí)項(xiàng)目也將緊隨其后。您只需使用下面的網(wǎng)址，便可將 Notebook 直接從 GitHub 加載到 Google Colab：

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

對(duì)于計(jì)算密集型任務(wù)，Colab 也免費(fèi)提供了 TPU 和 GPU。TensorFlow 文檔（如：此快速入門教程）中有一些按鈕，可以鏈接到文檔在 GitHub 中的 Notebook 源代碼和其對(duì)應(yīng)的 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

更好地協(xié)作

軟件文檔是一項(xiàng)團(tuán)隊(duì)工作，而 Notebook 是一種富有表現(xiàn)力的專注于手把手教程式的格式，它可以讓工程師和作者搭建出交互式演示，更直觀的了解所學(xué)內(nèi)容。Jupyter Notebook 是 JSON 格式的文件，包含文本單元和代碼單元，通常按照從上到下的順序執(zhí)行。Notebook 是一種非常出眾的交流編程理念的方式，而且在某些規(guī)程約束下，也可用于分享可重復(fù)的結(jié)果。

在 TensorFlow 團(tuán)隊(duì)中，Notebook 可讓工程師、技術(shù)作者和開放源代碼貢獻(xiàn)者在同一文檔中協(xié)作，而無需再費(fèi)力處理單獨(dú)的代碼示例及其發(fā)布說明。我們選擇編寫 TensorFlow Notebook，這樣一來文檔即代碼，且易于共享和測(cè)試。

使用 GitLocalize 翻譯 Notebook

TensorFlow 團(tuán)隊(duì)十分重視文檔在不同地區(qū)可讀性。TensorFlow 社區(qū)翻譯項(xiàng)目經(jīng)過去兩年的發(fā)展，已支持 10 種語言。Translation Sprints 活動(dòng)是開源文檔項(xiàng)目與社區(qū)展開互動(dòng)的絕佳方式。

TensorFlow 社區(qū)翻譯項(xiàng)目
https://github.com/tensorflow/docs-l10n

為讓更多開發(fā)者能夠訪問 TensorFlow 文檔，我們與 Alconost 合作，在其 GitLocalize 翻譯工具中添加了對(duì) Jupyter Notebook 的支持。GitLocalize 可輕松創(chuàng)建 Notebook 翻譯版本，并可輕松與源文件同步文檔更新。開放源代碼貢獻(xiàn)者可以通過 TensorFlow GitLocalize 項(xiàng)目(gitlocalize.com/tensorflow/docs-l10n) 提交 PR 并提供評(píng)論。

GitLocalize 對(duì) Jupyter Notebook 的支持不僅能讓 TensorFlow 受益，現(xiàn)在該工具也可用于所有在 GitHub 中使用 Notebook 的開源翻譯項(xiàng)目。

TensorFlow 文檔 Notebook 工具

將 Jupyter Notebook 并入我們的文檔架構(gòu)后，我們將可以運(yùn)行并測(cè)試所有已發(fā)布的指南和教程，以確保站點(diǎn)上的一切內(nèi)容均適用于新發(fā)布的 TensorFlow 版本，無論使用的是穩(wěn)定版還是 Nightly 軟件包。

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

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

除了上述優(yōu)勢(shì)，將 Jupyter Notebook 作為源代碼進(jìn)行管理也面臨著一些挑戰(zhàn)。為讓代碼貢獻(xiàn)者和項(xiàng)目維護(hù)者更輕松地進(jìn)行 PR 和 Review，我們創(chuàng)建了 TensorFlow 文檔 Notebook 工具，以通過持續(xù)集成 (Continuous Integration) 測(cè)試自動(dòng)執(zhí)行常規(guī)修復(fù)并將對(duì)應(yīng)的 issue 傳達(dá)給貢獻(xiàn)者。您可以直接從 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 格式很簡(jiǎn)單，但 Notebook 創(chuàng)作環(huán)境通常存在與 JSON 格式不一致的情況，或者會(huì)將自己的元數(shù)據(jù)嵌入到文件中。這些不必要的更改可能會(huì)導(dǎo)致 PR 中的內(nèi)容混亂，以致于很難進(jìn)行內(nèi)容 Review。解決辦法是使用自動(dòng)格式工具來輸出一致的 Notebook JSON。

nbfmt 是一種 Notebook 格式工具，其首選的是 TensorFlow 文檔 Notebook 樣式。該工具可以設(shè)置 JSON 格式，去除不必要的元數(shù)據(jù)，并保留我們集成中所要使用的一些 Colab 特定字段。執(zhí)行以下代碼以運(yùn)行該工具：

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

對(duì)于 TensorFlow 文檔項(xiàng)目，沒有輸出單元的 Notebook 保存后將被執(zhí)行并測(cè)試；有輸出單元的 Notebook 保存后將按原樣發(fā)布。我們更希望除去輸出以測(cè)試我們的 Notebook，但這兩種形式都可以使用 nbfmt。

TensorFlow 文檔 Notebook 樣式
https://tensorflow.google.cn/community/contribute/docs

進(jìn)行持續(xù)集成測(cè)試時(shí)，我們可以使用 --test 標(biāo)記。使用這個(gè)標(biāo)記后，如果 Notebook 未設(shè)置好格式，系統(tǒng)會(huì)返回錯(cuò)誤，而不是更新 Notebook。我們?cè)谖覀兤渲幸粋€(gè) GitHub 操作工作流的持續(xù)集成測(cè)試中使用了該標(biāo)記。通過后續(xù)集成機(jī)器人，格式補(bǔ)丁程序?qū)⒖梢宰詣?dòng)應(yīng)用于貢獻(xiàn)者的 PR 。

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

nblint

進(jìn)行大規(guī)模 Review 的最簡(jiǎn)單方式就是讓機(jī)器自動(dòng)來操作。每個(gè)項(xiàng)目在審核過程中都會(huì)存在反復(fù)出現(xiàn)的問題，而解決樣式問題最有效的方式就是使用樣式指南（TensorFlow 偏好 Google 開發(fā)者文檔樣式指南）。對(duì)于大型項(xiàng)目，您能自動(dòng)捕捉并進(jìn)行修復(fù)的模式越多，用于實(shí)現(xiàn)其他目標(biāo)的時(shí)間也就越多。

Google 開發(fā)者文檔樣式指南
https://developers.google.com/style

nblint 是一款 Notebook lint 工具，可針對(duì)文檔的樣式規(guī)則進(jìn)行檢查。在 TensorFlow Notebook 中，我們用其來捕捉常見的樣式和結(jié)構(gòu)問題：

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

Lint 是用于測(cè)試 Notebook 特定部分的斷言。系統(tǒng)會(huì)將這些 lint 收集到 樣式模塊中。默認(rèn)情況下，nblint 會(huì)針對(duì)google和tensorflow樣式進(jìn)行測(cè)試，而其他樣式模塊則可通過命令行進(jìn)行加載。某些樣式的參數(shù)也需要通過命令行進(jìn)行傳遞，例如，在對(duì) TensorFlow 翻譯 Notebook 進(jìn)行 lint 時(shí)設(shè)置不同的代碼庫：

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

Lint 測(cè)試可以包含關(guān)聯(lián)的修復(fù)工具，以輕松更新 Notebook 來自動(dòng)進(jìn)行樣式檢查。使用 --fix 參數(shù)以應(yīng)用 lint 修復(fù)，從而覆蓋 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 的忠實(shí)粉絲。通過將 Notebook 和 Google Colab 結(jié)合，我們可以對(duì)指南、教程和翻譯內(nèi)容進(jìn)行驗(yàn)證，簡(jiǎn)化了 TensorFlow 原本的學(xué)習(xí)旅程和擴(kuò)展大型開源文檔項(xiàng)目的方式。我們希望通過分享一些工具，可以為其他想要使用 Notebook 發(fā)布文檔的開放源代碼項(xiàng)目提供幫助。

閱讀 TensorFlow 教程，然后在 Google Colab 中運(yùn)行 Notebook。要為 TensorFlow 文檔項(xiàng)目貢獻(xiàn)內(nèi)容，請(qǐng)向我們的 GitLocalize 項(xiàng)目提交 PR 或翻譯 Review。

閱讀 TensorFlow 教程
https://tensorflow.google.cn/tutorials/quickstart/beginner

運(yùn)行 Notebook
https://colab.research.google.com/github/tensorflow/docs/blob/master/site/en/tutorials/quickstart/beginner.ipynb

GitLocalize 項(xiàng)目
https://gitlocalize.com/tensorflow/docs-l10n

特別感謝 Mark Daoust、Wolff Dobson、Yash Katariya、TensorFlow 文檔團(tuán)隊(duì)，以及所有 TensorFlow 文檔作者、審核人員、貢獻(xiàn)者和支持者。

責(zé)任編輯：lq