貢獻 TensorFlow 文件

TensorFlow 歡迎文件貢獻，如果您改善文件，就等於改善 TensorFlow 程式庫本身。tensorflow.org 上的文件分為下列類別

• API 參考資料 —API 參考文件是從 TensorFlow 原始碼中的文件字串產生。
• 說明文件 —這些是 教學課程、指南和其他非 TensorFlow 程式碼一部分的寫作。這份文件位於 tensorflow/docs GitHub 存放區中。
• 社群翻譯 —這些是由社群翻譯的指南和教學課程。所有社群翻譯都位於 tensorflow/docs 存放區中。

部分 TensorFlow 專案會將文件原始檔保留在程式碼附近的個別存放區中，通常是在 docs/ 目錄中。如要貢獻，請參閱專案的 CONTRIBUTING.md 檔案或聯絡維護人員。

如要參與 TensorFlow 文件社群

• 關注 tensorflow/docs GitHub 存放區。
• 在 TensorFlow 論壇上關注 docs 標籤。

API 參考資料

如需詳細資訊，請使用TensorFlow API 文件貢獻者指南。這份指南會說明如何尋找 原始檔，並編輯符號的 文件字串。tensorflow.org 上的許多 API 參考頁面都包含符號定義所在原始檔的連結。文件字串支援 Markdown，而且可以使用任何 Markdown 預覽器 (大約) 預覽。

版本和分支

網站的 API 參考資料版本預設為最新的穩定二進位檔，這與透過 pip install tensorflow 安裝的套件相符。

預設 TensorFlow 套件是從主要 tensorflow/tensorflow 存放區中的穩定分支 rX.x 建構而來。參考文件是從 Python、C++ 和 Java 的原始碼中的程式碼註解和文件字串產生。

TensorFlow 文件的先前版本在 TensorFlow 文件存放區中以 rX.x 分支提供。這些分支會在發布新版本時新增。

建構 API 文件

Python 參考資料

tensorflow_docs 套件包含 Python API 參考文件的產生器。如要安裝

pip install git+https://github.com/tensorflow/docs

如要產生 TensorFlow 2 參考文件，請使用 tensorflow/tools/docs/generate2.py 指令稿

git clone https://github.com/tensorflow/tensorflow tensorflow
cd tensorflow/tensorflow/tools/docs
pip install tensorflow
python generate2.py --output_dir=/tmp/out

說明文件

TensorFlow 指南和 教學課程是以 Markdown 檔案和互動式 Jupyter 筆記本的形式撰寫。筆記本可以使用 Google Colaboratory 在瀏覽器中執行。tensorflow.org 上的說明文件是從 tensorflow/docs master 分支建構而來。舊版可在 GitHub 上的 rX.x 發行分支中取得。

簡易變更

對 Markdown 檔案進行簡單文件更新的最簡單方式是使用 GitHub 的 Web 檔案編輯器。瀏覽 tensorflow/docs 存放區，尋找大致上對應於 tensorflow.org URL 結構的 Markdown。在檔案檢視的右上角，按一下鉛筆圖示以開啟檔案編輯器。編輯檔案，然後提交新的提取要求。

設定本機 Git 存放區

對於多檔案編輯或更複雜的更新，最好使用本機 Git 工作流程來建立提取要求。

下列 Git 步驟僅在您第一次設定本機專案時需要。

Fork tensorflow/docs 存放區

在 tensorflow/docs GitHub 頁面上，按一下「Fork」按鈕在您的 GitHub 帳戶下建立您自己的存放區副本。Fork 後，您有責任讓您的存放區副本與上游 TensorFlow 存放區保持在最新狀態。

複製您的存放區

將您的遠端 使用者名稱/docs 存放區副本下載到您的本機電腦。這是您將進行變更的工作目錄

git clone git@github.com:username/docs
cd ./docs

新增上游存放區以保持在最新狀態 (選用)

如要讓您的本機存放區與 tensorflow/docs 同步，請新增上游遠端以下載最新的變更。

新增遠端

git remote add upstream git@github.com:tensorflow/docs.git

# View remote repos
git remote -v
origin    git@github.com:username/docs.git (fetch)
origin    git@github.com:username/docs.git (push)
upstream  git@github.com:tensorflow/docs.git (fetch)
upstream  git@github.com:tensorflow/docs.git (push)

如要更新

git checkout master
git pull upstream master

git push  # Push changes to your GitHub account (defaults to origin)

GitHub 工作流程

1. 建立新分支

從 tensorflow/docs 更新您的存放區後，從本機master分支建立新分支

git checkout -b feature-name

git branch  # List local branches
  master

* feature-name

2. 進行變更

在您慣用的編輯器中編輯檔案，並請遵循 TensorFlow 文件樣式指南。

提交您的檔案變更

# View changes
git status  # See which files have changed
git diff    # See changes within files

git add path/to/file.md
git commit -m "Your meaningful commit message for the change."

視需要新增更多提交。

3. 建立提取要求

將您的本機分支上傳到您的遠端 GitHub 存放區 (github.com/使用者名稱/docs)

git push

推送完成後，訊息可能會顯示 URL，以自動向上游存放區提交提取要求。如果沒有，請前往 tensorflow/docs 存放區 (或您自己的存放區)，GitHub 會提示您建立提取要求。

4. 審查

維護人員和其他貢獻者將審查您的提取要求。請參與討論並進行要求的變更。您的提取要求獲得核准後，將會合併到上游 TensorFlow 文件存放區中。

有一個個別的發布步驟，可從 GitHub 存放區更新 tensorflow.org。通常，變更會批次處理在一起，並且網站會定期更新。

互動式筆記本

雖然可以使用 GitHub 的 Web 檔案編輯器編輯筆記本 JSON 檔案，但不建議這麼做，因為格式錯誤的 JSON 可能會損壞檔案。提交提取要求之前，請務必測試筆記本。

Google Colaboratory 是一種託管筆記本環境，可讓您輕鬆編輯和執行筆記本文件。GitHub 中的筆記本是透過將路徑傳遞至 Colab URL 來載入 Google Colab，例如，位於 GitHub 此處的筆記本：https://github.com/tensorflow/docs/blob/master/site/en/tutorials/keras/classification.ipynb
可以使用此 URL 載入 Google Colab：https://colab.research.google.com/github/tensorflow/docs/blob/master/site/en/tutorials/keras/classification.ipynb

有一個 Open in Colab Chrome 擴充功能，可在瀏覽 GitHub 上的筆記本時執行此 URL 替換。當您在存放區 Fork 中開啟筆記本時，這非常有用，因為頂端按鈕一律連結至 TensorFlow 文件 master 分支。

筆記本格式設定

筆記本格式設定工具可讓 Jupyter 筆記本原始碼差異保持一致，並更易於審查。由於筆記本撰寫環境在檔案輸出、縮排、中繼資料和其他未指定的欄位方面有所不同；nbfmt 使用約定俗成的預設值，並偏好 TensorFlow 文件 Colab 工作流程。如要設定筆記本格式，請安裝 TensorFlow 文件筆記本工具，並執行 nbfmt 工具

# Install the tensorflow-docs package:
$ python3 -m pip install -U [--user] git+https://github.com/tensorflow/docs

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

對於 TensorFlow 文件專案，沒有輸出儲存格的筆記本會執行並測試；有儲存輸出儲存格的筆記本會依原樣發布。nbfmt 會遵循筆記本狀態，並使用 --remove_outputs 選項明確移除輸出儲存格。

如要建立新的筆記本，請複製並編輯 TensorFlow 文件筆記本範本。

在 Colab 中編輯

在 Google Colab 環境中，按兩下儲存格以編輯文字和程式碼區塊。文字儲存格使用 Markdown，而且應遵循 TensorFlow 文件樣式指南。

使用「檔案 > 下載 .pynb」從 Colab 下載筆記本檔案。將此檔案提交至您的 本機 Git 存放區，並傳送提取要求。

如要建立新的筆記本，請複製並編輯 TensorFlow 筆記本範本。

Colab-GitHub 工作流程

您可以直接從 Google Colab 編輯和更新您的 Fork GitHub 存放區，而不用下載筆記本檔案並使用本機 Git 工作流程

1. 在您的 Fork 使用者名稱/docs 存放區中，使用 GitHub Web UI 建立新分支。
2. 導覽至要編輯的筆記本檔案。
3. 在 Google Colab 中開啟筆記本：使用 URL 交換或「Open in Colab」Chrome 擴充功能。
4. 在 Colab 中編輯筆記本。
5. 使用「檔案 > 在 GitHub 中儲存副本...」從 Colab 將變更提交至您的存放區。儲存對話方塊應連結至適當的存放區和分支。新增有意義的提交訊息。
6. 儲存後，瀏覽至您的存放區或 tensorflow/docs 存放區，GitHub 應提示您建立提取要求。
7. 提取要求會由維護人員審查。

翻譯

TensorFlow 團隊與社群和供應商合作，為 tensorflow.org 提供翻譯。tensorflow/docs-l10n GitHub 存放區中提供了筆記本和其他技術內容的翻譯。請透過 TensorFlow GitLocalize 專案提交提取要求。

英文文件是真理來源，翻譯應盡可能遵循這些指南。也就是說，翻譯是為其服務的社群而寫的。如果英文術語、措辭、樣式或語氣無法翻譯成其他語言，請使用適合讀者的翻譯。

語言支援取決於許多因素，包括 (但不限於) 網站指標和需求、社群支援、英語能力、受眾偏好和其他指標。由於每種支援的語言都會產生費用，因此系統會移除未維護的語言。對新語言的支援將在 TensorFlow 部落格或 Twitter 上公告。

如果您偏好的語言不受支援，歡迎您維護開放原始碼貢獻者的社群 Fork。這些不會發布到 tensorflow.org。