参与TensorFlow文档编写

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

  • API 文档 —API 文档 经由 TensorFlow 源代码中的文档字符串(docstring)生成.
  • 叙述文档 —这部分内容为教程、 指南以及其他不属于TensorFlow代码的内容. 这部分代码位于GitHub的 tensorflow/docs 仓库(repository)中.
  • 社区翻译 —这些是经由社区翻译的指南和教程。他们都被存放在 tensorflow/docs 仓库(repository)中.

一些 TensorFlow 项目 将文档源文件保存在单独的存储库中，通常位于docs/目录中。 请参阅项目的CONTRIBUTING.md文件或联系维护者以参与。

参与到TensorFlow文档社区的方式有:

API 文档

如果想更新API文档，找到其对应的 源文件 并编辑相应的 文档字符串(docstring). tensorflow.org上的许多API 引用的页面都包含了指向源文件定义位置的链接。 文档字符串支持 Markdown格式 并且（绝大多数时候）都能使用 Markdown 预览器 进行浏览.

有关参考文档质量以及如何参与文档冲刺和社区，请参阅 TensorFlow 2.0 API文档建议。

版本(Versions) 和 分支(Branches)

本网站的 API 文档 版本默认为最新的稳定二进制文件—即与通过pip install tensorflow安装的版本所匹配.

默认的TensorFlow 包是根据tensorflow/tensorflow仓库(repository)中的稳定分支rX.x所构建的。文档则是由 Python、 C++与 Java代码中的注释与文档字符串所生成。

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

构建API文档

注意：编辑或预览API文档字符串不需要此步骤，只需生成tensorflow.org上使用的HTML。

Python 文档

tensorflow_docs包中包含Python API 文档的生成器。 安装方式：

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

要生成TensorFlow 2.0文档，使用 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 仓库(repository)下的rX.x发行版分支中。

简单更改

进行简单文档更新和修复的最简单方法是使用GitHub的 Web文件编辑器。 浏览tensorflow/docs 仓库(repository) 以寻找与 tensorflow.org 中的URL 结构相对应的Markdown或notebook文件。 在文件视图的右上角，单击铅笔图标 来打开文件编辑器。 编辑文件，然后提交新的拉取请求(pull request)。

设置本地Git仓库(repository)

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

注意：Git 是用于跟踪源代码更改的开源版本控制系统（VCS）。 GitHub是一种在线服务， 提供与Git配合使用的协作工具。请参阅GitHub Help以设置您的GitHub帐户并开始使用。

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

复制(fork) tensorflow/docs 仓库(repository)

在 tensorflow/docs 的Github页码中，点击Fork按钮 在您的GitHub帐户下创建您自己的仓库副本。复制(fork) 完成，您需要保持您的仓库副本副本与上游TensorFlow仓库的同步。

克隆您的仓库(repository)

下载一份您 username/docs 仓库的副本到本地计算机。这是您之后进行操作的工作目录：

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

添加上游仓库(upstream repo)以保持最新（可选）

要使本地存储库与tensorflow/docs保持同步，需要添加一个上游(upstream) 仓库来下载最新的更改。

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

添加远程仓库:

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

# 浏览远程仓库
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  # 列出本地分支
  master

* feature-name

2. 做更改

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

提交文件更改：

# 查看更改
git status  # 查看哪些文件被修改
git diff    # 查看文件中的更改内容

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

根据需要添加更多提交。

3. 创建一个拉取请求(pull request)

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

git push

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

4. 审校

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

成功后：您的更改会被TensorFlow文档接受。

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

交互式笔记本（notebook）

虽然可以使用GitHub的web文本编辑器来编辑笔记本JSON文件，但不推荐使用它，因为格式错误的JSON可能会损坏文件。 确保在提交拉取请求(pull request)之前测试笔记本。

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

有一个 Open in Colab 扩展程序，可以在GitHub上浏览笔记本时执行此URL替换。 这在您复制的仓库中中打开笔记本时非常有用，因为顶部按钮始终链接到TensorFlow Docs的master分支。

在Colab编辑

在Google Colab环境中，双击单元格以编辑文本和代码块。文本单元格使用Markdown格式，请遵循 TensorFlow文档样式指南.

通过点击 File > Download .pynb 可以从Colab中下载笔记本文件。 将此文件提交到您的本地Git仓库后再提交拉取请求。

如需要创建新笔记本，请复制和编辑 TensorFlow 笔记本模板.

Colab-GitHub工作流

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

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

成功后：您的更改会被TensorFlow文档接受。

社区翻译

社区翻译是让TensorFlow在全世界都可以访问的好方法。如需更新或添加翻译，在语言目录中按照en/相同的目录结构找到或添加一个新文件。英语文档是最基础的来源，翻译应尽可能地遵循这些指南。也就是说，翻译应尽量保持原汁原味。如果英语术语，短语，风格或语气不能翻译成其他语言，请采用适合读者的翻译。

注意：请勿翻译 tensorflow.org中的API引用.

有特定于语言的文档组，使翻译贡献者可以更轻松地进行组织。 如果您是作者，评论者或只是想为社区构建TensorFlow.org内容，请加入：

审校须知

所有文档更新都需要审核。 为了更有效地与TensorFlow翻译社区进行协作，以下是一些保持语言特定活动的方法：

  • 加入上面列出的语言组，以接收任何涉及该语言site/lang目录的已创建的 拉取请求。
  • 将您的GitHub用户名添加至site/<lang>/REVIEWERS文件在拉取请求中能被自动注释标记。在被标记后，GitHub会向您发送该拉取请求中所有更改和讨论的通知。

在翻译中让代码保持最新

对于像TensorFlow这样的开源项目，保持文档最新是一项挑战。在与社区交谈之后，翻译内容的读者能容忍有点过时的文本，但过时的代码会让人抓狂。为了更容易保持代码同步，请为翻译的笔记本使用 nb-code-sync工具：

./tools/nb_code_sync.py [--lang=en] site/lang/notebook.ipynb

此脚本读取语言笔记本的代码单元格，并根据英语版本进行检查。 剥离注释后，它会比较代码块并更新语言笔记本（如果它们不同）。 此工具对于交互式git工作流特别有用，可以选择性地将文件添加至更改中: git add --patch site/lang/notebook.ipynb

Docs sprint

参加您附近的 TensorFlow 2.0 Global Docs Sprint 活动，或远程加入。 请关注此 博客文章。这些事件是开始为TensorFlow文档做出贡献的好方法。