GitHub Repository: tensorflow/docs-l10n
Path: blob/master/site/zh-cn/community/contribute/docs.md
²⁵¹¹⁸ views

为 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 [email protected]:<var>username</var>/docs
cd ./docs

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

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

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

添加远程仓库：

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

# View remote repos
<code class="devsite-terminal">git remote -v</code>
origin    [email protected]:<var>username</var>/docs.git (fetch)
origin    [email protected]:<var>username</var>/docs.git (push)
upstream  [email protected]:tensorflow/docs.git (fetch)
upstream  [email protected]: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 工作流：

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