为 TensorFlow 文档做贡献

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

• API 文档 - API 文档由 TensorFlow 源代码中的 docstring 生成。
• 叙述文档 - 这些内容为教程、指南以及其他不属于 TensorFlow 代码的内容。这种文档位于 tensorflow/docs GitHub 仓库中。
• 社区翻译 - 这些是由社区翻译的指南和教程。所有社区翻译都存放在 tensorflow/docs 仓库中。

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

参与 TensorFlow 文档社区：

• 关注 tensorflow/docs GitHub 仓库。
• 按照TensorFlow 论坛上的 docs标签进行操作。

API 参考

有关详细信息，请使用 TensorFlow API 文档贡献者指南。这向您展示了如何找到源文件并编辑符号的 docstring。tensorflow.org 上的许多 API 参考页面都包含指向定义符号的源文件的链接。Docstring 支持 Markdown 并且（绝大多数时候）都能使用任意 Markdown 预览程序进行浏览。

版本和分支

本网站的 API 参考版本默认为最新的稳定二进制文件，与通过 pip install tensorflow 安装的软件包匹配。

默认的 TensorFlow 软件包根据 tensorflow/tensorflow 主仓库中的稳定分支 rX.x 构建。参考文档由 Python、C++ 和 Java 源代码中的代码注释与 docstring 生成。

以前版本的 TensorFlow 文档在 TensorFlow Docs 仓库中以 rX.x 分支形式提供。在发布新版本时会添加这些分支。

构建 API 文档

注：编辑或预览 API docstring 不需要此步骤，只需生成 tensorflow.org 上使用的 HTML。

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 软件包来生成文档，并且仅适用于 TensorFlow 2.x。

叙述文档

TensorFlow 指南和教程作为 Markdown 文件和交互式 Jupyter 笔记本编写。可以使用 Google Colaboratory 在您的浏览器中运行笔记本。tensorflow.org 上的叙述文档根据 tensorflow/docs 的 master 分支构建。旧版本存储在在 GitHub 仓库下的 rX.x 版本分支中。

简单变更

Markdown 文件进行简单文档更新的最简单方法是使用 GitHub 的 Web 文件编辑器。浏览 tensorflow/docs 仓库以找到与 tensorflow.org 网址结构大致对应的 Markdown。在文件视图的右上角，点击铅笔图标 打开文件编辑器。编辑文件，然后提交新的拉取请求。

设置本地 Git 仓库

对于多文件编辑或更复杂的更新，最好使用本地 Git 工作流创建拉取请求。

注：Git 是用于跟踪源代码变更的开源版本控制系统 (VCS)。GitHub是一种在线服务，提供可与 Git 配合使用的协作工具。请参阅 GitHub 帮助来设置您的 GitHub 帐号并开始使用。

只有在第一次设置本地项目时才需要以下 Git 步骤。

复刻 tensorflow/docs 仓库

在 tensorflow/docs Github 页面中，点击 Fork 按钮 在您的 GitHub 帐号下创建您自己的仓库副本。复刻后，您需要保持您的仓库副本与上游 TensorFlow 仓库同步。

克隆您的仓库

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

git clone [e-mail]:<var>username</var>/docs
cd ./docs

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

要使本地存储库与 tensorflow/docs 保持同步，请添加一个上游仓库来下载最新变更。

注：确保在开始贡献之前更新您的本地仓库。定期向上游同步会降低您在提交拉取请求时产生合并冲突的可能性。

添加远程仓库：

<code class="devsite-terminal">git remote add upstream [e-mail]:tensorflow/docs.git</code>

# View remote repos
<code class="devsite-terminal">git remote -v</code>
origin    [e-mail]:<var>username</var>/docs.git (fetch)
origin    [e-mail]:<var>username</var>/docs.git (push)
upstream  [e-mail]:tensorflow/docs.git (fetch)
upstream  [e-mail]:tensorflow/docs.git (push)

更新：

<code class="devsite-terminal">git checkout master</code>
<code class="devsite-terminal">git pull upstream master</code>

<code class="devsite-terminal">git push</code>  # Push changes to your GitHub account (defaults to origin)

GitHub 工作流

1. 创建一个新分支

从 tensorflow/docs 更新您的仓库后，从本地 master 分支创建一个新分支：

<code class="devsite-terminal">git checkout -b <var>feature-name</var></code>

<code class="devsite-terminal">git branch</code>  # List local branches
  master

* <var>feature-name</var>

2. 进行更改

在您喜欢的编辑器中编辑文件，并请遵守 TensorFlow 文档风格指南。

提交文件变更：

# View changes
<code class="devsite-terminal">git status</code>  # See which files have changed
<code class="devsite-terminal">git diff</code>    # See changes within files

<code class="devsite-terminal">git add <var>path/to/file.md</var></code>
<code class="devsite-terminal">git commit -m "Your meaningful commit message for the change."</code>

根据需要添加更多提交。

3. 创建拉取请求

将本地分支上传到您的远程 GitHub 仓库 (github.com/username/docs)：

git push

推送完成后，消息可能会显示一个网址，以自动向上游仓库提交拉取请求。如果没有，请转到 tensorflow/docs 仓库或者您自己的仓库，GitHub 将提示您创建拉取请求。

4. 审查

维护者和其他贡献者将审查您的拉取请求。请参与讨论并根据要求进行修改。当您的请求获得批准后，它将被合并到上游 TensorFlow 文档仓库中。

成功：您的变更已被 TensorFlow 文档接受。

从 GitHub 仓库更新 tensorflow.org 是一个单独的步骤。通常情况下，多个变更将一起处理，并定期上传至网站。

交互式笔记本

虽然可以使用 GitHub 的 Web 文件编辑器编辑笔记本 JSON 文件，但不推荐使用，因为格式错误的 JSON 可能会损坏文件。确保先测试笔记本，然后再提交拉取请求。

Google Colaboratory 是一个托管笔记本环境，可以轻松编辑和运行笔记本文档。GitHub 中的笔记本通过将路径传递给 Colab 网址加载到 Google Colab 中，例如，位于 GitHub 中以下位置的笔记本： https://github.com/tensorflow/docs/blob/master/site/en/tutorials/keras/basic_classification.ipynb
可以通过以下网址加载到 Google Colab 中：https://colab.research.google.com/github/tensorflow/docs/blob/master/site/en/tutorials/keras/basic_classification.ipynb

有一个 Open in Colab Chrome 扩展程序，可以在 GitHub 上浏览笔记本时执行此网址替换。这在仓库复刻中打开笔记本时非常有用，因为顶部按钮始终链接到 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 文档风格指南。

点击 File > Download .pynb，从 Colab 中下载笔记本文件。将此文件提交到您的本地 Git 仓库并发送拉取请求。

要创建新笔记本，请复制并编辑 TensorFlow 笔记本模板。

Colab-GitHub 工作流

您可以直接 从Google Colab 编辑和更新复刻的 GitHub 仓库，而不用下载笔记本文件并使用本地 Git 工作流：

1. 在您复制的 username/docs 仓库中，使用 GitHub Web 界面创建新分支。
2. 导航到要编辑的笔记本文件。
3. 在 Google Colab 中打开笔记本：使用网址替换或 Open in Colab Chrome 扩展程序。
4. 在 Colab 中编辑笔记本。
5. 点击 File > Save a copy in GitHub... 从 Colab 中向您的仓库提交变更。保存对话框应链接到相应的仓库和分支。添加一条有意义的提交消息。
6. 保存后，浏览到您的仓库或者 tensorflow/docs 仓库，GitHub 应提示您创建拉取请求。
7. 维护者会审查拉取请求。

成功：您的变更已被 TensorFlow 文档接受。

翻译

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

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

语言支持由多种因素决定，包括但不限于站点指标和需求、社区支持、英语水平、受众偏好和其他指标。由于每种支持的语言都会产生成本，因此会删除未维护的语言。我们将在 TensorFlow 博客或 Twitter 上公布对新语言的支持。

如果您的首选语言不受支持，欢迎您为开源贡献者维护社区复刻。这些内容不会发布到 tensorflow.org。