Jupyter Notebook是TensorFlow文檔架構(gòu)的重要組成部分

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

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

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

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

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

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

更好地協(xié)作

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

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

使用 GitLocalize 翻譯 Notebook

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

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

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

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

TensorFlow 文檔 Notebook 工具

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

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

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

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

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

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

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

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

進行持續(xù)集成測試時，我們可以使用 --test 標記。使用這個標記后，如果 Notebook 未設置好格式，系統(tǒng)會返回錯誤，而不是更新 Notebook。我們在我們其中一個 GitHub 操作工作流的持續(xù)集成測試中使用了該標記。通過后續(xù)集成機器人，格式補丁程序?qū)⒖梢宰詣討糜谪暙I者的 PR 。

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

nblint

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

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

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

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

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

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

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

閱讀 TensorFlow 教程，然后在 Google Colab 中運行 Notebook。要為 TensorFlow 文檔項目貢獻內(nèi)容，請向我們的 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