为 TensorFlow 文档做出贡献

TensorFlow 欢迎您为文档做出贡献 - 如果您改进文档，您就改进 TensorFlow 库本身。tensorflow.org 上的文档分为以下几类

• API 参考 - API 参考文档 是从 TensorFlow 源代码 中的 docstring 生成的。
• 叙述性文档 - 这些是 教程、指南 和其他不属于 TensorFlow 代码的写作。此文档位于 tensorflow/docs GitHub 存储库中。
• 社区翻译 - 这些是由社区翻译的指南和教程。所有社区翻译都位于 tensorflow/docs 存储库中。

某些 TensorFlow 项目 将文档源文件保存在代码附近的单独存储库中，通常位于 docs/ 目录中。请参阅项目的 CONTRIBUTING.md 文件或联系维护者以做出贡献。

要参与 TensorFlow 文档社区

• 关注 tensorflow/docs GitHub 存储库。
• 关注 docs 标签，该标签位于 TensorFlow 论坛 上。

API 参考

有关详细信息，请使用 TensorFlow API 文档贡献者指南。这将向您展示如何查找 源文件 并编辑符号的 docstring。tensorflow.org 上的许多 API 参考页面都包含指向定义符号的源文件的链接。Docstring 支持 Markdown，并且可以使用任何 Markdown 预览器 进行（近似）预览。

版本和分支

网站的 API 参考 版本默认为最新的稳定二进制文件 - 这与使用 pip install tensorflow 安装的软件包相匹配。

默认 TensorFlow 软件包是使用主 tensorflow/tensorflow 存储库中的稳定分支 rX.x 构建的。参考文档是从 Python、C++ 和 Java 源代码中的代码注释和 docstring 生成的。

以前版本的 TensorFlow 文档作为 rX.x 分支 可在 TensorFlow 文档存储库中获得。在发布新版本时会添加这些分支。

构建 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 步骤仅在您首次设置本地项目时才需要。

派生 tensorflow/docs 存储库

在 tensorflow/docs GitHub 页面上，单击派生按钮以在您的 GitHub 帐户下创建您自己的存储库副本。派生后，您有责任将您的存储库副本与上游 TensorFlow 存储库保持同步。

克隆您的存储库

将您的远程 username/docs 存储库的副本下载到您的本地计算机。这是您将进行更改的工作目录

git clone [email protected]:username/docs
cd ./docs

添加上游存储库以保持最新（可选）

要使您的本地存储库与 tensorflow/docs 保持同步，请添加一个上游远程存储库以下载最新更改。

添加远程存储库

git remote add upstream [email protected]:tensorflow/docs.git

# View remote repos
git remote -v
origin    [email protected]:username/docs.git (fetch)
origin    [email protected]:username/docs.git (push)
upstream  [email protected]:tensorflow/docs.git (fetch)
upstream  [email protected]: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/username/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
可以加载到 Google Colab 中，网址为：https://colab.research.google.com/github/tensorflow/docs/blob/master/site/en/tutorials/keras/classification.ipynb

有一个 在 Colab 中打开 Chrome 扩展程序，它可以在 GitHub 上浏览笔记本时执行此 URL 替换。当在您的仓库分支中打开笔记本时，这很有用，因为顶部按钮始终链接到 TensorFlow Docs 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 编辑和更新您的分叉 GitHub 仓库，而不是下载笔记本文件并使用本地 Git 工作流程。

1. 在您的分叉 username/docs 仓库中，使用 GitHub Web UI 创建一个新分支。
2. 导航到要编辑的笔记本文件。
3. 在 Google Colab 中打开笔记本：使用 URL 替换或 在 Colab 中打开 Chrome 扩展程序。
4. 在 Colab 中编辑笔记本。
5. 使用 文件 > 在 GitHub 中保存副本... 从 Colab 将更改提交到您的仓库。保存对话框应链接到相应的仓库和分支。添加有意义的提交消息。
6. 保存后，浏览到您的仓库或 tensorflow/docs 仓库，GitHub 应提示您创建拉取请求。
7. 拉取请求由维护者审查。

翻译

TensorFlow 团队与社区和供应商合作，为 tensorflow.org 提供翻译。笔记本和其他技术内容的翻译位于 tensorflow/docs-l10n GitHub 仓库中。请通过 TensorFlow GitLocalize 项目 提交拉取请求。

英文文档是真相来源，翻译应尽可能遵循这些指南。也就是说，翻译是为他们服务的社区编写的。如果英文术语、措辞、风格或语气无法翻译成另一种语言，请使用适合读者的翻译。

语言支持取决于许多因素，包括（但不限于）网站指标和需求、社区支持、英语熟练程度、受众偏好和其他指标。由于每种支持的语言都会产生成本，因此未维护的语言将被删除。对新语言的支持将在 TensorFlow 博客 或 Twitter 上公布。

如果您喜欢的语言不受支持，欢迎您为开源贡献者维护一个社区分支。这些不会发布到 tensorflow.org。